QUIVEROptimizer

class QUIVEROptimizer(learning_rate=0.1, epsilon=0.1, V_init=1, V_min=1, V_max=50, M_init=100, M_min=10, M_max=10000, adapt_V=True, adapt_M=True, derivative_mode='finite_diff', lipschitz=None, mu=0.99, b=1e-06, alpha=0.0, gamma=0.0, A=None, blocking=False, blocking_history=5, blocking_tol=2.0, exact_loss=False)[source]

Bases: _SPSAConfigMixin, Optimizer

Adaptive directional (forward) gradients — QUIVER (arXiv 2606.09734).

Reconstructs the full gradient from V random Rademacher directional derivatives, independent of the parameter count N:

\[\tilde\nabla^{\mathsf F} f = \frac{1}{V}\sum_{\ell=1}^{V} \Big(\frac{f(\theta+\varepsilon v_\ell) - f(\theta-\varepsilon v_\ell)} {2\varepsilon}\Big)\, v_\ell , \qquad \theta \leftarrow \theta - a_k\,\tilde\nabla^{\mathsf F} f ,\]

costing 2V evaluations per step. This unifies SPSA (V=1, finite-difference), random coordinate descent (V=1, parameter-shift directional derivative) and the full parameter-shift rule (V=N) under one tunable V.

QUIVER additionally adapts V and the per-direction shot count M each step (iCANS/gCANS-style), maximising expected progress per measurement shot:

  • ``V`` from the sample spread (no backend variance needed). The V i.i.d. directional samples already estimate the forward-gradient variance S²; more directions are spent when the relative gradient variance is high and fewer as the estimate concentrates. This encodes the paper’s assumption that measurement noise concentrates uniformly across random directions, so allocation is by number of directions, not per-parameter.

  • ``M`` from the injected measurement variance. When the variational algorithm’s cost closure exposes a shot-noise variance (shot-based backends), QUIVER reads the single-shot cost variance and sets M to balance derivative noise against the gradient signal. On native-expval backends or a plain cost_fn (no variance channel) it falls back to a fixed M and V-from-spread only — still a valid forward-gradient optimizer.

Note

A per-evaluation shot budget is delivered to the backend as explicit per-circuit shot_groups, which disables circuit-template batching for that submission. On template-capable backends (e.g. the Qoro cloud) an adapting M therefore trades template reuse for shot adaptivity; if submission overhead dominates, prefer adapt_M=False there and keep adapt_M for local shot-based simulators.

Single-point optimizer (n_param_sets == 1); gradient-free, so any jac/metric_fn supplied by the variational algorithm is ignored.

Parameters:

  • learning_rate (float) – Step-size numerator a (constant by default; the gain schedule reuses Spall’s a/(A+k+1)**alpha with alpha=0).

  • epsilon (float) – Finite-difference step ε (paper default 0.1); for derivative_mode='parameter_shift' the shift π/2 is used instead.

  • V_init/V_min/V_max – Initial / minimum / maximum number of random directions per step.

  • M_init/M_min/M_max – Initial / minimum / maximum shots per directional evaluation (only adapted on shot-based backends).

  • adapt_V (bool) – Adapt the number of directions from the sample spread.

  • adapt_M (bool) – Adapt the shot budget from the injected measurement variance.

  • derivative_mode (Literal['finite_diff', 'parameter_shift']) – 'finite_diff' (default, central difference with step ε) or 'parameter_shift' (directional shift π/2; exact only for equal-eigenvalue generators along basis directions, otherwise an approximation).

  • lipschitz (float | None) – Smoothness constant L for the gain bound; when None the optimal step a = 1/L is taken to be learning_rate.

  • mu (float) – EMA decay for the running gradient / variance estimates.

  • b (float) – Small floor guarding divisions by a vanishing gradient norm.

  • alpha/gamma/A – Spall gain-schedule knobs (default to constant gains).

  • blocking/blocking_history/blocking_tol/exact_loss – Inherited look-ahead blocking and loss-recording behaviour (see SPSAOptimizer).

Methods Summary

optimize(cost_fn[, initial_params, callback_fn])

Run QUIVER for max_iterations steps.

validate_program(program)

Warn when adapt_M is combined with a configured shot distribution.

Methods Documentation

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

Run QUIVER 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 directional sample. When it accepts shots/return_variance (the variational algorithm’s closure), QUIVER drives the adaptive shot budget and reads the measurement variance for M-adaptivity.

  • 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) and rng. jac and metric_fn are accepted and ignored (QUIVER is gradient-free).

Return type:

OptimizeResult

validate_program(program)[source]

Warn when adapt_M is combined with a configured shot distribution.

M-adaptivity recovers the single-shot cost variance as Var(<H>)·M, which assumes every measurement group received the same M shots. A shot distribution splits the budget unevenly across groups, so that recovery is miscalibrated — the gradient and loss stay correct, but the adapted M may be off. Disable adapt_M or drop the shot distribution to silence this.

Return type:

None