kosmos.ml.models.vqc.circuit.qiskit_circuit.gradient_method

Module Attributes

DEVICE = 'cpu'

Classes

class GradientMethod

Bases: abc.ABC

Abstract base class for quantum-circuit gradient methods.

Implementations may follow analytic rules (e.g., parameter-shift) or stochastic gradient-free approaches (e.g., SPSA). All subclasses must implement the jacobian method that computes d(outputs)/d(weights).

Notes

This package provides two implementations:

  • ParameterShiftRule: exact, low variance, but requires 2 evaluations per parameter.

  • SPSA: stochastic, higher variance, but requires only 2 evaluations per sample independent of parameter count.

Initialize the gradient method.


Methods

set_parameterized_circuit(parameterized_circuit: QiskitParameterizedCircuit) → None

Assign the parameterized circuit to be used by the gradient method.

This must be called before computing gradients.

Parameters:

parameterized_circuit (QiskitParameterizedCircuit) – The Qiskit parameterized circuit.

validate_parameterized_circuit() → None

Validate that the parameterized circuit has been set.

jacobian(x: kosmos.ml.typing.TensorNpArray, weights: numpy.ndarray) → torch.Tensor

Compute d(outputs)/d(weights).

Parameters:

  • x (TensorNpArray) – Input values, shape (len_x, input_dim).

  • weights (np.ndarray) – Weights values.

Returns:

Jacobian of shape (len_x, output_dim, followed by weights.shape).

Return type:

torch.Tensor

class ParameterShiftRule(shift: float = np.pi / 2)

Bases: GradientMethod

Gradient computation using the parameter-shift rule.

The parameter-shift rule is an analytic approach to computing gradients in variational quantum circuits. The gradient of an expectation value can be computed exactly using two circuit evaluations per parameter:

\[f'(\theta) = \frac{f(\theta + s) - f(\theta - s)}{2 \sin(s)}\]

In the common case of Pauli rotations, the canonical shift is \(s = \pi/2\).

Notes

  • The method provides low-variance, unbiased gradients.

  • Computational cost scales linearly with the number of parameters (two evaluations per parameter).

  • Requires the circuit to be differentiable in the parameter of interest and the underlying generator to have a known spectrum.

Initialize the parameter-shift rule.

Parameters:

shift (float) – Shift magnitude. Defaults to π/2.


Methods

jacobian(x: kosmos.ml.typing.TensorNpArray, weights: numpy.ndarray) → torch.Tensor

Compute d(outputs)/d(weights) via parameter-shift.

Parameters:

  • x (TensorNpArray) – Input values, shape (len_x, input_dim).

  • weights (np.ndarray) – Weights values.

Returns:

Jacobian of shape (len_x, output_dim, followed by weights.shape).

Return type:

torch.Tensor

class SPSA(epsilon: float = 0.01, num_samples: int = 3)

Bases: GradientMethod

Gradient computation using Simultaneous Perturbation Stochastic Approximation (SPSA).

SPSA is a gradient-free method that estimates all partial derivatives using only two circuit evaluations per random perturbation, independent of the number of parameters. A random perturbation vector \(\Delta\) is drawn from a symmetric Bernoulli distribution \(\{-1, +1\}\), which is optimal in the sense of minimizing estimator variance (Sadegh & Spall, 1998).

The gradient estimate for parameter \(i\) is:

\[\hat{g}_i \approx \frac{f(\theta + \epsilon \Delta) - f(\theta - \epsilon \Delta)} {2\epsilon \Delta_i}\]

Multiple samples are averaged to reduce variance.

Notes

  • Cost is \(O(\mathrm{num\_samples})\) compared to \(O(\mathrm{num\_parameters})\) of the parameter-shift rule.

  • Produces an unbiased gradient estimator under mild regularity.

  • Typically more robust to noise than analytic gradient methods such as parameter-shift.

  • Only gradient estimation is implemented here; the optimizer gain sequences \(a_k\) and \(c_k\) are not part of this component.

  • This implementation follows standard formulations used in quantum optimization, such as PennyLane’s SPSAOptimizer (https://docs.pennylane.ai/en/stable/_modules/pennylane/optimize/spsa.html#SPSAOptimizer.compute_grad).

Initialize the SPSA gradient method.

Parameters:

  • epsilon (float) – Perturbation magnitude. Defaults to 0.01.

  • num_samples (int) – Number of random perturbation samples to average over. Defaults to 3.


Methods

jacobian(x: kosmos.ml.typing.TensorNpArray, weights: numpy.ndarray) → torch.Tensor

Compute d(outputs)/d(weights) via SPSA.

Parameters:

  • x (TensorNpArray) – Input values, shape (len_x, input_dim).

  • weights (np.ndarray) – Weights values.

Returns:

Jacobian of shape (len_x, output_dim, followed by weights.shape).

Return type:

torch.Tensor