QNSPSAOptimizer

class QNSPSAOptimizer(learning_rate=0.01, c=0.2, alpha=0.602, gamma=0.101, A=None, regularization=0.001, resamplings=1, blocking=False, blocking_history=5, blocking_tol=2.0, exact_loss=False, metric_estimator=None)[source]

Bases: _SPSAConfigMixin, Optimizer

Quantum Natural SPSA (Gacon et al.).

Combines the cheap SPSA gradient with a stochastic Fubini–Study metric, so both the gradient and the geometry cost a constant number of circuit evaluations per step regardless of the parameter count. The default metric is estimated from state-fidelity overlaps via two random directions \(h_1, h_2\):

\[\delta F = F(\theta,\theta + c_k h_1 + c_k h_2) - F(\theta,\theta + c_k h_1) - F(\theta,\theta - c_k h_1 + c_k h_2) + F(\theta,\theta - c_k h_1), \quad \hat g = -\frac{\delta F}{8 c_k^2}\,(h_1 h_2^\top + h_2 h_1^\top),\]

accumulated into a running average \(\bar g_k=(k\,\bar g_{k-1}+\hat g)/(k+1)\) seeded at the identity, conditioned as \(|\bar g_k| + \beta I\) (matrix absolute value plus an identity shift), and used to precondition the SPSA gradient: \(\theta \leftarrow \theta - a_k (|\bar g_k|+\beta I)^{-1}\hat g\).

The metric backend is pluggable, exactly as for QNGOptimizer. The default StochasticFidelityMetricEstimator is the faithful QN-SPSA metric; passing FubiniStudyMetricEstimator (or PullbackMetricEstimator) instead uses that estimator’s exact metric while keeping the SPSA gradient.

Single-point optimizer (n_param_sets == 1); the variational algorithm supplies the metric evaluator via build_evaluators().

Parameters:

  • learning_rate (float) – Spall’s \(a\) — the learning-rate gain numerator.

  • c (float) – Perturbation-size gain numerator \(c\).

  • alpha (float) – Decay exponent for the learning-rate gain (Spall default 0.602).

  • gamma (float) – Decay exponent for the perturbation gain (Spall default 0.101).

  • A (float | None) – Learning-rate stability constant; defaults to 0.1 * max_iterations.

  • regularization (float) – Identity-shift \(\beta\) added to the conditioned metric so the linear solve stays positive-definite.

  • resamplings (int) – Average this many independent gradient/metric samples per step to reduce variance.

  • blocking (bool) – Enable look-ahead blocking (reject a step whose candidate loss exceeds the current loss by more than blocking_tol·std of the recent window). Recommended for high-dimensional or noisy runs where the stochastic metric can otherwise drive a divergent step. Costs one extra evaluation per step, plus one at the start to seed the baseline. Off by default.

  • blocking_history (int) – Window length for the std band used by blocking.

  • blocking_tol (float) – Reject a candidate whose loss exceeds the current loss by more than blocking_tol·std of the recent window. This is the knob that absorbs cost noise in the accept/reject decision (resamplings de-noises the gradient/metric, not this single-evaluation comparison).

  • exact_loss (bool) – When True, spend one extra unperturbed evaluation per step to record the exact f(theta) for the callback and best-iterate tracking, instead of the (biased but free) perturbation-average proxy. Has no effect when blocking is set — blocking already records the exact loss.

  • metric_estimator (MetricEstimator | None) – Strategy supplying the metric. Defaults to the stochastic-fidelity estimator (the faithful QN-SPSA metric).

Methods Summary

build_evaluators(program)

Bind the metric estimator (its fidelity_fn or metric_fn).

optimize(cost_fn[, initial_params, callback_fn])

Run QN-SPSA for max_iterations steps.

validate_program(program)

Reject a program whose ansatz the chosen metric estimator cannot model.

Methods Documentation

build_evaluators(program)[source]

Bind the metric estimator (its fidelity_fn or metric_fn).

Return type:

dict[str, Callable[[ndarray[tuple[Any, ...], dtype[double]]], Any]]

optimize(cost_fn, initial_params=None, callback_fn=None, **kwargs)[source]

Run QN-SPSA for max_iterations steps.

Parameters:

  • cost_fn (Callable[[ndarray[tuple[Any, ...], dtype[double]]], float | ndarray[tuple[Any, ...], dtype[double]]]) – Cost function; called with a two-row batch per gradient sample so both perturbations share one stochastic-cost draw.

  • initial_params (ndarray[tuple[Any, ...], dtype[double]] | None) – Starting parameters (1D, or 2D with a single row).

  • callback_fn (Callable[[OptimizeResult], Any] | None) – Called after each step with an OptimizeResult whose x is 2D and fun is 1D. May raise StopIteration.

  • **kwargs – max_iterations (default 50, must be >= 1), rng (the perturbation directions — pass it for reproducible runs), and exactly one metric evaluator — fidelity_fn (stochastic, the default) or metric_fn (an exact estimator). jac is accepted and ignored (QN-SPSA’s gradient is the SPSA estimate).

Return type:

OptimizeResult

validate_program(program)[source]

Reject a program whose ansatz the chosen metric estimator cannot model.

Return type:

None