qrunch.chemistry.orbital_optimizers.local_gradient_calculator

Module dedicated to local approximation-based orbital optimization gradient and Hessian computations.

This interface is intended for scenarios where gradients and Hessians are computed using a local approximation around a specific reference point (e.g., x=0).

Classes

`BosonReducedDensityMatrixGradientCalculator`	Class to construct the gradient and hessian for orbital optimization using boson RDMs.
`ReducedDensityMatrixGradientCalculator`	Class to construct the gradient and hessian for orbital optimization using restricted RDMs.
`RestrictedReducedDensityMatrixGradientCalculator`	Class to construct the gradient and hessian for orbital optimization using restricted RDMs.
`UnrestrictedReducedDensityMatrixGradientCalculator`	Class to construct the gradient and hessian for orbital optimization using unrestricted RDMs.

class BosonReducedDensityMatrixGradientCalculator

Bases: object

Class to construct the gradient and hessian for orbital optimization using boson RDMs.

__init__(estimator: Estimator, mapper: Mapper | None = None) → None

Initialize gradient calculator using boson RDMs.

Parameters:

estimator (Estimator) – Estimator to use for estimating the RDMs.
mapper (Mapper | None) – mapper to use when mapping RDM operators.

Return type:

None

clear_cache() → None

Clear the cache of the calculators.

Return type:: None

compute_energy(operator: ChemistryPairedHardcoreBosonHermitianSum, circuit: Circuit, shots: int | None = None) → float

Compute the energy (at kappa=0).

Parameters:

operator (ChemistryPairedHardcoreBosonHermitianSum) – Operator to estimate the energy of.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

float

compute_gradient(operator: ChemistryPairedHardcoreBosonHermitianSum, circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the gradient.

Parameters:

operator (ChemistryPairedHardcoreBosonHermitianSum) – Operator to estimate the gradient from.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_hessian(operator: ChemistryPairedHardcoreBosonHermitianSum, circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the Hessian.

Parameters:

operator (ChemistryPairedHardcoreBosonHermitianSum) – Operator to estimate the Hessian from.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_hessian_on_trial_vector(operator: ChemistryPairedHardcoreBosonHermitianSum, kappa_vec: ndarray[tuple[Any, ...], dtype[float64]], circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the Hessian contracted with the trial vector kappa.

This computes sum_{z,w} hessian[x,y,z,w] * kappa[z,w] without building the full 4D hessian tensor. Here kappa is the antisymmetric matrix.

The implementation exploits eight-fold ERI symmetry, the symmetry of gamma and gamma_2d (symmetric), and the antisymmetry of kappa to combine many originally separate einsum calls into a much smaller set. Terms that appear identically in both the forward (A) and transpose (B) contractions are computed once and doubled.

When the underlying two-body integrals use a resolution-of-the-identity (RI) representation, the ERI patterns are chosen so that the x and y output indices land on the same Cholesky factor whenever possible, keeping intermediates at \(\\mathcal{O}(N^2)\). The few unavoidable \(\\mathcal{O}(N^3)\) intermediates (where x and y are on different factors) are identified and batched together.

Parameters:

operator (ChemistryPairedHardcoreBosonHermitianSum) – Operator to estimate the Hessian from.
kappa_vec (ndarray[tuple[Any, ...], dtype[float64]]) – The trial vector. reduced representation with upper triangular elements.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_second_order_energy(operator: ChemistryPairedHardcoreBosonHermitianSum, kappa: ndarray[tuple[Any, ...], dtype[float64]], circuit: Circuit, shots: int | None = None) → float

Compute the second order energy in terms of the kappa rotation parameters.

Parameters:

operator (ChemistryPairedHardcoreBosonHermitianSum) – Operator to estimate the Hessian from.
kappa (ndarray[tuple[Any, ...], dtype[float64]]) – The orbital rotation parameters.
circuit (Circuit) – Circuit to use as the ansatz for estimating the RDMs.
shots (int | None) – The number of shots to use in the estimation. Defaults to None.

Return type:

float

get_estimator_shots() → int

Get the total amount of shots made by the estimator.

Return type:: int

classmethod support_hessian_on_trial_vector() → bool

Indicate whether this class supports computing the Hessian on a trial vector.

Return type:: bool

class ReducedDensityMatrixGradientCalculator

Bases: GradientCalculator

Class to construct the gradient and hessian for orbital optimization using restricted RDMs.

__init__(estimator: Estimator, mapper: Mapper | None = None) → None

Initialize the gradient calculator using restricted RDMs.

Parameters:

estimator (Estimator) – Estimator to use for estimating the RDMs.
mapper (Mapper | None) – mapper to use when mapping RDM operators.

Return type:

None

clear_cache() → None

Clear the cache of the calculators.

Return type:: None

compute_energy(operator: FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol, circuit: Circuit, shots: int | None = None) → float

Compute the energy.

Parameters:

operator (FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol) – Operator to estimate the energy of.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

float

compute_gradient(operator: FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol, circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the gradient.

Parameters:

operator (FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol) – Operator to estimate the gradient from.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_hessian(operator: FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol, circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the Hessian.

Parameters:

operator (FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol) – Operator to estimate the Hessian from.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_hessian_on_trial_vector(operator: FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol, kappa_vec: ndarray[tuple[Any, ...], dtype[float64]], circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the Hessian contracted with the trial vector kappa.

This computes sum_{z,w} hessian[x,y,z,w] * kappa[z,w] without building the full 4D hessian tensor, where kappa is an antisymmetric matrix.

Parameters:

operator (FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol) – Operator to estimate the Hessian from.
kappa_vec (ndarray[tuple[Any, ...], dtype[float64]]) – The trial vector. reduced representation with upper triangular elements.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_second_order_energy(operator: FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol, kappa: ndarray[tuple[Any, ...], dtype[float64]], circuit: Circuit, shots: int | None = None) → float

Compute the second-order energy in terms of the kappa rotation parameters.

Parameters:

operator (FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol) – Operator to estimate the Hessian from.
kappa (ndarray[tuple[Any, ...], dtype[float64]]) – The orbital rotation parameters.
circuit (Circuit) – Circuit to use as the ansatz for estimating the RDMs.
shots (int | None) – The number of shots to use in the estimation. Defaults to None.

Return type:

float

get_estimator_shots() → int

Get the total amount of shots made by the estimator.

Return type:: int

support_hessian_on_trial_vector(operator: FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol) → bool

Indicate whether this class supports computing the Hessian on a trial vector.

Parameters:: operator (FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol) – Operator to check support for.
Return type:: bool

class RestrictedReducedDensityMatrixGradientCalculator

Bases: object

Class to construct the gradient and hessian for orbital optimization using restricted RDMs.

__init__(estimator: Estimator, mapper: Mapper | None = None) → None

Initialize the gradient calculator using restricted RDMs.

Parameters:

estimator (Estimator) – Estimator to use for estimating the RDMs.
mapper (Mapper | None) – mapper to use when mapping RDM operators.

Return type:

None

clear_cache() → None

Clear the cache of the calculators.

Return type:: None

compute_energy(operator: ChemistryFermionHermitianSum, circuit: Circuit, shots: int | None = None) → float

Compute the energy (at kappa=0).

Parameters:

operator (ChemistryFermionHermitianSum) – Operator to estimate the energy of.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

float

compute_gradient(operator: ChemistryFermionHermitianSum, circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the gradient.

\[\frac{\partial E^{(1)}(\kappa)}{\partial \kappa_{xy}} = \sum_{q} h_{yq} \gamma_{xq} - \sum_{q} h_{xq} \gamma_{yq} - \sum_{p} h_{px} \gamma_{py} + \sum_{p} h_{py} \gamma_{px} + \sum_{pqrsm} g_{yqrs} \Gamma_{xrsq} - \sum_{pqrsm} g_{xqrs} \Gamma_{yrsq} + \sum_{pqrsm} g_{pqys} \Gamma_{xpsq} - \sum_{pqrsm} g_{pqxs} \Gamma_{ypsq} + \sum_{pqrsn} g_{pxrs} \Gamma_{prsy} - \sum_{pqrsn} g_{pyrs} \Gamma_{prsx} + \sum_{pqrsn} g_{pqrx} \Gamma_{prqy} - \sum_{pqrsn} g_{pqry} \Gamma_{prqx}\]

Parameters:

operator (ChemistryFermionHermitianSum) – Operator to estimate the gradient from.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_hessian(operator: ChemistryFermionHermitianSum, circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the Hessian.

The calculation is based on eq. (S14) in [arXiv:2212.02482v1], but with the ordering of the indices changes to the physics ordering: pqrs -> prsq.

Furthermore, the indices 1 and 2 of the two-body reduced density matrices are swapped, as this seems to be an error in the paper.

Parameters:

operator (ChemistryFermionHermitianSum) – Operator to estimate the Hessian from.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_hessian_on_trial_vector(operator: ChemistryFermionHermitianSum, kappa_vec: ndarray[tuple[Any, ...], dtype[float64]], circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the Hessian contracted with the trial vector kappa.

This computes sum_{z,w} hessian[x,y,z,w] * kappa[z,w] without building the full 4D hessian tensor, where kappa is an antisymmetric matrix.

For the restricted case the hessian is built from four groups of terms (one-body, cross-alpha, cross-beta, remaining), each of which is eight-fold symmetrised. Instead of materialising each N⁴ block we contract every raw term directly with kappa to produce an N² intermediate, apply the symmetry identity (A - A^T) + (B - B^T) where A and B are the forward and transpose contractions, and sum the contributions.

Parameters:

operator (ChemistryFermionHermitianSum) – Operator to estimate the Hessian from.
kappa_vec (ndarray[tuple[Any, ...], dtype[float64]]) – The trial vector. reduced representation with upper triangular elements.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_second_order_energy(operator: ChemistryFermionHermitianSum, kappa: ndarray[tuple[Any, ...], dtype[float64]], circuit: Circuit, shots: int | None = None) → float

Compute the second order energy in terms of the kappa rotation parameters.

Parameters:

operator (ChemistryFermionHermitianSum) – Operator to estimate the Hessian from.
kappa (ndarray[tuple[Any, ...], dtype[float64]]) – The orbital rotation parameters.
circuit (Circuit) – Circuit to use as the ansatz for estimating the RDMs.
shots (int | None) – The number of shots to use in the estimation. Defaults to None.

Return type:

float

get_estimator_shots() → int

Get The total amount of shots made by the estimator.

Return type:: int

classmethod support_hessian_on_trial_vector() → bool

Indicate whether this class supports computing the Hessian on a trial vector.

Return type:: bool

class UnrestrictedReducedDensityMatrixGradientCalculator

Bases: object

Class to construct the gradient and hessian for orbital optimization using unrestricted RDMs.

__init__(estimator: Estimator, mapper: Mapper | None = None) → None

Initialize the gradient calculator using unrestricted RDMs.

Parameters:

estimator (Estimator) – Estimator to use for estimating the RDMs.
mapper (Mapper | None) – mapper to use when mapping RDM operators.

Return type:

None

clear_cache() → None

Clear the cache of the calculators.

Return type:: None

compute_energy(operator: ChemistryFermionHermitianSum, circuit: Circuit, shots: int | None = None) → float

Compute the energy (at kappa=0).

Parameters:

operator (ChemistryFermionHermitianSum) – Operator to estimate the energy of.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

float

compute_gradient(operator: ChemistryFermionHermitianSum, circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the gradient.

Parameters:

operator (ChemistryFermionHermitianSum) – Operator to estimate the gradient from.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_hessian(operator: ChemistryFermionHermitianSum, circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the Hessian.

Parameters:

operator (ChemistryFermionHermitianSum) – Operator to estimate the Hessian from.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_hessian_on_trial_vector(operator: ChemistryFermionHermitianSum, kappa_vec: ndarray[tuple[Any, ...], dtype[float64]], circuit: Circuit, shots: int | None = None) → ndarray[tuple[Any, ...], dtype[float64]]

Compute the Hessian contracted with the trial vector kappa.

This computes sum_{z,w} hessian[x,y,z,w] * kappa[z,w] without building the full 4D hessian tensor, where kappa is an antisymmetric matrix.

Parameters:

operator (ChemistryFermionHermitianSum) – Operator to estimate the Hessian from.
kappa_vec (ndarray[tuple[Any, ...], dtype[float64]]) – The trial vector. reduced representation with upper triangular elements.
circuit (Circuit) – The circuit ansatz with minimized parameters set.
shots (int | None) – The number of shots to use in the estimator.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

compute_second_order_energy(operator: ChemistryFermionHermitianSum, kappa: ndarray[tuple[Any, ...], dtype[float64]], circuit: Circuit, shots: int | None = None) → float

Compute the second order energy in terms of the kappa rotation parameters.

Parameters:

operator (ChemistryFermionHermitianSum) – Operator to estimate the Hessian from.
kappa (ndarray[tuple[Any, ...], dtype[float64]]) – The orbital rotation parameters.
circuit (Circuit) – Circuit to use as the ansatz for estimating the RDMs.
shots (int | None) – The number of shots to use in the estimation. Defaults to None.

Return type:

float

get_estimator_shots() → int

Get The total amount of shots made by the estimator.

Return type:: int

classmethod support_hessian_on_trial_vector() → bool

Indicate whether this class supports computing the Hessian on a trial vector.

Return type:: bool