qrunch.quantum.algorithms.second_quantization.orbital_optimizers.protocols

Protocols for orbital optimizers.

Module Attributes

OrbitalOptimizerFactory

Type alias for a factory that creates a OrbitalOptimizerAlgorithm given an estimator.

Classes

GradientCalculator

Protocol for calculating gradients and Hessians for orbital optimization.

OrbitalOptimizerAlgorithm

Protocol class for an orbital optimizer.

OrbitalOptimizerResult

Result of orbital optimization.
class GradientCalculator

Bases: Protocol

Protocol for calculating gradients and Hessians for orbital optimization.

__init__(*args, **kwargs)
clear_cache() → None

Clear the cache of the underlying estimator.

Return type:

None

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

Compute the energy.

Parameters:
Return type:

float

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

Compute the gradient.

Parameters:
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:
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.

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]]

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 OrbitalOptimizerAlgorithm

Bases: ABC

Protocol class for an orbital optimizer.

The orbital optimization algorithm rotates the observable with an ansatz unitary so that the expectation value is minimized.

abstractmethod clear_cache() → None

Clear the cache of the underlying estimator.

Return type:

None

abstractmethod gradient_norm(operator: FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol, circuit: Circuit) → float | None

Compute the norm of the orbital-optimization gradient at zero rotation.

The gradient is evaluated at \(\\kappa = 0\), i.e. using the unrotated operator directly. It returns None if the orbital optimizer does not have an analytical gradient.

Parameters:
Return type:

float | None

abstractmethod run(operator: T, circuit: Circuit) → OrbitalOptimizerResult[T]

Run the orbital optimizer and find the eigenvalue.

Parameters:

  • operator (T) – The operator whose expectation value should be minimized.

  • circuit (Circuit) – The parametrized circuit to find optimal parameters for. Should contain unspecified parameters.

Return type:

OrbitalOptimizerResult[T]

abstractmethod run_single_step(operator: T, circuit: Circuit) → OrbitalOptimizerResult[T]

Perform a single, cheap orbital-optimization step.

The default implementation simply delegates to run(). Subclasses may override to provide a genuinely cheaper step.

Parameters:

  • operator (T) – The operator whose expectation value should be minimized.

  • circuit (Circuit) – The circuit ansatz with optimized parameters set.

Return type:

OrbitalOptimizerResult[T]

OrbitalOptimizerFactory

Type alias for a factory that creates a OrbitalOptimizerAlgorithm given an estimator.

alias of Callable[[Estimator, int | None], OrbitalOptimizerAlgorithm]

class OrbitalOptimizerResult

Bases: Generic[T_COV]

Result of orbital optimization.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

  • sampler_shots – The total amount of shots used by the sampler

  • rotation_matrices – Optimal rotation_matrices

  • estimated_value – Estimated expectation value of the rotated operator

  • rotated_operator – The rotated second quantized operator.

  • rotation_parameters – Optimal parameters in the exponential of the rotation matrices (default=None)

__init__(sampler_shots: int, rotation_matrices: tuple[ndarray[tuple[Any, ...], dtype[float64]], ...], estimated_value: float, rotated_operator: T_COV, rotation_parameters: tuple[dict[tuple[int, int], float64], ...] | None = None) → None
Parameters:

  • sampler_shots (int)

  • rotation_matrices (tuple[ndarray[tuple[Any, ...], dtype[float64]], ...])

  • estimated_value (float)

  • rotated_operator (T_COV)

  • rotation_parameters (tuple[dict[tuple[int, int], float64], ...] | None)

Return type:

None

estimated_value: float
rotated_operator: T_COV
rotation_matrices: tuple[ndarray[tuple[Any, ...], dtype[float64]], ...]
rotation_parameters: tuple[dict[tuple[int, int], float64], ...] | None = None
sampler_shots: int