PullbackMetricEstimator

class PullbackMetricEstimator

Bases: MetricEstimator

Hamiltonian-aware pullback metric.

Builds G_ij = sum_r a_r^2 (d_i <P_r>)(d_j <P_r>) from the per-Pauli-term expectation gradients of the loss observable H = sum_r a_r P_r. The energy gradient J @ a and the metric share the same parameter-shift evaluation, so both are returned from one pass. Measurement-only and PSD by construction (rank at most the number of Hamiltonian terms).

Requires the program’s loss to be the expectation value of its cost Hamiltonian (VQE/QAOA, plain or unsupervised-data-bound CustomVQA).

When the cost fans out into several measurement branches (QDrift sampling, a data cohort), the energy gradient averages linearly across branches while the metric is the mean of the per-branch metrics E_b[G_b], not the metric of the mean Jacobian G(E_b[J]). This is deliberate and is the only well-defined choice: each QDrift branch samples a different Hamiltonian with its own term set and coefficients, so the branch Jacobians are not commensurable to average. E_b[G_b] is the expected pullback metric over the sampling distribution — the same empirical-Fisher averaging a batched natural gradient uses. For the single-branch case (all deterministic VQAs) the two forms coincide.

Methods Summary

bind(program)	Return the evaluators this metric provides, keyed by name.
check_compatible(program)	Raise ContractViolation if this metric cannot be applied to program.

Methods Documentation

bind(program)

Return the evaluators this metric provides, keyed by name.

Deterministic estimators (pullback, Fubini–Study) provide "metric_fn" — a pure function of the parameters returning the metric matrix — and the pullback estimator additionally returns the loss gradient under "jac". The stochastic-fidelity estimator instead provides "fidelity_fn": the QN-SPSA optimizer builds its metric from finite differences of that fidelity rather than from a closed-form matrix. The variational algorithm forwards whichever keys appear to the optimizer; keys absent fall back to the algorithm’s parameter-shift defaults.

Return type:

dict[str, Callable[..., Any]]

check_compatible(program)

Raise ContractViolation if this metric cannot be applied to program. Called at run() start so an incompatible pairing fails loudly before any optimization.

Return type:

None