QNGOptimizer

class QNGOptimizer(step_size=0.1, regularization=0.001, scale_regularization=True, solver='tikhonov', rcond=1e-06, max_step_norm=None, metric_estimator=None)

Bases: Optimizer

Quantum Natural Gradient optimizer.

Performs regularized natural-gradient descent

\[\theta \leftarrow \theta - \eta \, (G + \lambda I)^{-1} \nabla L,\]

where \(\nabla L\) is the parameter-shift gradient and \(G\) is a positive-semidefinite metric tensor. The optimizer is metric-agnostic: the metric is produced by an injected MetricEstimator strategy (default PullbackMetricEstimator), bound to the program’s capabilities via build_evaluators(). Swapping the estimator changes the metric without changing the optimizer.

Because the default pullback metric is only PSD — and singular whenever the number of parameters exceeds the number of Hamiltonian terms — Tikhonov damping is applied before solving the linear system.

This is a single-point optimizer (n_param_sets == 1). The variational algorithm wires the estimator’s gradient and metric in via build_evaluators(); calling optimize directly without jac and metric_fn raises ValueError.

Parameters:

• step_size (float) – Learning rate \(\eta\) for the parameter update.

• regularization (float) – Tikhonov damping \(\lambda\) added to the metric diagonal before solving. Must be positive when solver is "tikhonov" so the damped system is positive-definite.

• scale_regularization (bool) – When True, scale \(\lambda\) by max(1, mean(diag(G))) so the damping tracks the metric’s magnitude instead of being fixed in absolute terms.

• solver (Literal['tikhonov', 'pinv']) – "tikhonov" solves (G + lambda I) delta = grad via a Cholesky-based symmetric solve (exploits PSD structure). "pinv" instead applies the Moore-Penrose pseudo-inverse of the raw (undamped) metric with cutoff rcond.

• rcond (float) – Singular-value cutoff for the "pinv" solver.

• max_step_norm (float | None) – If set, clip the L2 norm of the per-iteration parameter update step_size * (G + lambda I)^-1 grad to this value. None (default) applies no clip.

• metric_estimator (MetricEstimator | None) – The strategy that builds the metric G from the program’s capabilities. Defaults to PullbackMetricEstimator (the Hamiltonian-aware pullback metric). Inject a different estimator to change the metric without touching the optimizer.

Note

Because the pullback metric is only PSD (and singular whenever the parameter count exceeds the number of Hamiltonian terms), the preconditioned step can grow large along weakly-curved directions when regularization is small relative to the metric scale. If the optimizer oscillates (visible in the loss history), raise regularization, lower step_size, or set max_step_norm. A non-finite update raises FloatingPointError.

Attributes Summary

n_param_sets	Number of parameter sets per step — always 1 (single-point).
supports_checkpointing	False — QNG's only state is the parameter vector, already persisted by the variational algorithm's program state.

Methods Summary

build_evaluators(program)	Bind the metric estimator to the program's metric pipeline.
get_config()	QNGOptimizer does not support checkpointing.
load_state(checkpoint_dir)	QNGOptimizer does not support state loading.
optimize(cost_fn[, initial_params, callback_fn])	Run natural-gradient descent for max_iterations steps.
reset()	No-op: QNGOptimizer maintains no internal state between runs.
save_state(checkpoint_dir)	QNGOptimizer does not support state saving.
validate_program(program)	Reject a program whose loss the chosen metric estimator cannot model.

Attributes Documentation

n_param_sets

Number of parameter sets per step — always 1 (single-point).

supports_checkpointing

False — QNG’s only state is the parameter vector, already persisted by the variational algorithm’s program state.

Methods Documentation

build_evaluators(program)

Bind the metric estimator to the program’s metric pipeline.

The pullback estimator returns a fused jac + metric_fn (one memoized measurement serves both); the Fubini–Study estimator returns only metric_fn and lets the gradient fall back to the program’s parameter-shift rule.

Return type:

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

get_config()

QNGOptimizer does not support checkpointing.

Raises:

NotImplementedError – Always. The only optimizer state is the current parameter vector, which the variational algorithm already checkpoints via its parameter history.

Return type:

dict[str, Any]

classmethod load_state(checkpoint_dir)

QNGOptimizer does not support state loading.

Raises:

NotImplementedError – Always; see get_config().

Return type:

QNGOptimizer

optimize(cost_fn, initial_params=None, callback_fn=None, **kwargs)

Run natural-gradient descent for max_iterations steps.

Parameters:

• cost_fn (Callable[[ndarray[tuple[Any, ...], dtype[double]]], float | ndarray[tuple[Any, ...], dtype[double]]]) – Scalar cost function; called once per iteration at the current parameters to record the loss.

• 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, matching the variational-algorithm callback contract. May raise StopIteration for early stopping.

• **kwargs – max_iterations (default 50), jac (required gradient function), metric_fn (required metric function). rng is accepted and ignored — QNG is deterministic.

Returns:

Best evaluated iterate over the run.

Return type:

OptimizeResult

reset()

No-op: QNGOptimizer maintains no internal state between runs.

Return type:

None

save_state(checkpoint_dir)

QNGOptimizer does not support state saving.

Raises:

NotImplementedError – Always; see get_config().

Return type:

None

validate_program(program)

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

Return type:

None