microquantum.core.gradient

Analytical gradients via the Parameter-Shift Rule (MQ-13).

The parameter-shift rule computes the exact derivative of an expectation value \(\langle O\rangle(\theta)\) for circuits built from single-qubit rotation gates. For \(U(\theta)=e^{-i\theta P/2}\) with \(P\in\{X,Y,Z\}\) the derivative is

\[\frac{d\langle O\rangle}{d\theta} = \frac{\langle O\rangle(\theta+s) - \langle O\rangle(\theta-s)}{2\,\sin(s)}\;,\]

for any shift \(s\) that is not an integer multiple of \(\pi\) (the default \(s=\pi/2\)).

Policies (MQ-13):

  • Identity: parameters are matched by name (consistent with the MQ-12 parameter model), so a Parameter works transparently even when another instance with the same name appears in the circuit.

  • Chain rule: when a gate angle is a ParameterExpression a*theta + c, each occurrence contributes a times the parameter-shift difference; a parameter used in several gates contributes the sum of its per-occurrence gradients (product rule).

  • Observables: Operator, PauliString and PauliSum are all supported; PauliString/PauliSum terms are evaluated without building dense matrices, optionally over a subset of qubits via targets.

  • Execution: by default shifted circuits are simulated with the built-in state-vector engine. Pass backend= to route evaluation through the MQ-11/12 execution core (backend.run with seed/shots for reproducibility).

  • Strictness: param_values must be a Mapping and must provide values for every circuit parameter; observables must be one of the supported types; a shift with \(\sin(s)\approx 0\) is rejected.

Module Contents

microquantum.core.gradient.parameter_shift_gradient(circuit, observable, param, param_values, shift=np.pi / 2, targets=None, *, backend=None, seed=None, shots=None)[source]

Compute d<O>/dparam with the Parameter-Shift Rule.

For a rotation \(U(\theta)=e^{-i\theta G/2}\) with Pauli generator \(G\), the derivative of an expectation value is

\[\frac{d\langle O\rangle}{d\theta} = \frac{\langle O\rangle(\theta+s) - \langle O\rangle(\theta-s)}{2\,\sin(s)}\;.\]

When the parameter appears in several gates (or inside a ParameterExpression with a coefficient), each occurrence is shifted independently, scaled by the chain-rule factor a of its angle expression w.r.t. param, and the results are summed (product rule).

Parameters:

  • circuit (microquantum.core.circuit.QuantumCircuit) – Parameterized quantum circuit.

  • observable (Union[microquantum.core.operators.Operator, microquantum.core.pauli.PauliString, microquantum.core.pauli.PauliSum]) – Operator, PauliString or PauliSum.

  • param (microquantum.core.parameter.Parameter) – The parameter to differentiate with respect to (matched by name).

  • param_values (collections.abc.Mapping[Union[str, microquantum.core.parameter.Parameter], float]) – Mapping of parameter names/objects to numeric values for the differentiation point. Must cover every parameter in the circuit.

  • shift (float) – Shift angle for the rule (default pi/2). Must not be an integer multiple of pi.

  • targets (Optional[list[int]]) – Optional qubit indices a Pauli/operator observable acts on. Needed when an Operator/PauliString/PauliSum covers a strict subset of the circuit’s qubits.

  • backend (object) – Optional execution backend used to evaluate the shifted circuits. Defaults to the built-in state-vector engine.

  • seed (Optional[int]) – Optional seed passed to backend.run for reproducible evaluation.

  • shots (Optional[int]) – Optional shot count passed to backend.run. Expectation values use the exact statevector, so shots only affects the (ignored) sampled counts.

Returns:

The analytical partial derivative d<O>/d(param).

Raises:

  • ValueError – If shift is an integer multiple of pi, an observable is malformed, or the backend returns no statevector.

  • TypeError – If param_values is not a Mapping or the observable is not an Operator/PauliString/PauliSum.

  • KeyError – If param (or any other circuit parameter) has no value in param_values, or param does not occur in any gate.

Return type:

float

microquantum.core.gradient.gradient(circuit, observable, param_values, shift=np.pi / 2, targets=None, *, backend=None, seed=None, shots=None)[source]

Compute the full analytic gradient vector for all parameters.

Evaluates d<O>/d(theta_i) for every Parameter of circuit (in the deterministic QuantumCircuit.parameters order), delegating each entry to parameter_shift_gradient(). The result uses the circuit’s Parameter objects as keys, so it plugs directly into the gradient-aware optimizers (gradient_fn=).

Parameters:

  • circuit (microquantum.core.circuit.QuantumCircuit) – Parameterized quantum circuit.

  • observable (Union[microquantum.core.operators.Operator, microquantum.core.pauli.PauliString, microquantum.core.pauli.PauliSum]) – Operator, PauliString or PauliSum.

  • param_values (collections.abc.Mapping[Union[str, microquantum.core.parameter.Parameter], float]) – Mapping of parameter names/objects to numeric values for the differentiation point. Must cover every parameter in the circuit.

  • shift (float) – Shift angle for the rule (default pi/2).

  • targets (Optional[list[int]]) – Optional qubit indices the observable acts on.

  • backend (object) – Optional execution backend (see parameter_shift_gradient()).

  • seed (Optional[int]) – Optional seed for backend evaluation.

  • shots (Optional[int]) – Optional shot count for backend evaluation (expectations use the statevector, so shots does not change the result).

Returns:

A {Parameter: float} mapping with one analytic gradient entry per circuit parameter.

Raises:

  • TypeError – If param_values is not a Mapping.

  • KeyError – If a circuit parameter has no value in param_values.

Return type:

dict[microquantum.core.parameter.Parameter, float]