qrunch.quantum.algorithms.second_quantization.vqes.adaptive_orbital_optimization_vqe

Module containing adaptive orbital optimization VQE.

Module Attributes

DEFAULT_OO_OPTIONS

Default options for when to apply the Intermittent Orbital Optimization.

Classes

SecondQuantizationAdaptiveOrbitalOptimizationVqe

VQE that combines adaptive and orbital optimization VQE as the underlying algorithm.
DEFAULT_OO_OPTIONS = IntermittentOrbitalOptimizerAlgorithmOptions(every_nth_iteration=1, gradient_threshold=inf, skip_gradient_threshold=1e-16, orbital_change_threshold=inf, force_full_after_n_non_full_steps=10, gate_addition_threshold=0.001)

Default options for when to apply the Intermittent Orbital Optimization.

class SecondQuantizationAdaptiveOrbitalOptimizationVqe

Bases: SecondQuantizationAdaptiveVqeAlgorithm

VQE that combines adaptive and orbital optimization VQE as the underlying algorithm.

__init__(vqe: PauliBasicVqeAlgorithm, intermittent_orbital_optimizer: OrbitalOptimizerAlgorithm, gate_selector: GateSelector, intermittent_oo_options: IntermittentOrbitalOptimizerAlgorithmOptions = IntermittentOrbitalOptimizerAlgorithmOptions(every_nth_iteration=1, gradient_threshold=inf, skip_gradient_threshold=1e-16, orbital_change_threshold=inf, force_full_after_n_non_full_steps=10, gate_addition_threshold=0.001), options: IterativeVqeOptions | None = None, reminimizer_vqe: PauliBasicVqeAlgorithm | None = None, final_orbital_optimizer: OrbitalOptimizerAlgorithm | None = None, mapper: Mapper | None = None, data_persister_manager: DataPersisterManager | None = None, stopping_criterion: StoppingCriterion | None = None) → None

Initialize adaptive orbital optimization VQE.

Parameters:

  • vqe (PauliBasicVqeAlgorithm) – The VQE object that can optimize the gate parameters.

  • intermittent_orbital_optimizer (OrbitalOptimizerAlgorithm) – The orbital optimizer that intermittently optimize rotation parameters. It is recommended to use a fast orbital optimizer here, with loose convergence criteria as it is run multiple times during the adaptive VQE.

  • reminimizer_vqe (PauliBasicVqeAlgorithm | None) – The VQE object that re-optimize the gate parameters at the end.

  • final_orbital_optimizer (OrbitalOptimizerAlgorithm | None) – The orbital optimizer that re-optimize rotation parameters at the end. Here it is recommended to use a more accurate orbital optimizer, with stricter convergence criteria, as it is only run once at the end of the adaptive VQE.

  • mapper (Mapper | None) – The mapper to use for mapping the second quantized operator to a qubit operator.

  • gate_selector (GateSelector) – The gate selector to use.

  • options (IterativeVqeOptions | None) – Options for the adaptive VQE.

  • intermittent_oo_options (IntermittentOrbitalOptimizerAlgorithmOptions) – Options for when to apply the intermittent orbital optimization.

  • data_persister_manager (DataPersisterManager | None) – Manager to handle saving and loading heavy vqe optimizations.

  • stopping_criterion (StoppingCriterion | None) – The stopping criterion to use when performing early stopping.

Return type:

None

static build_circuit_to_optimize(iteration_data: AdaptiveOrbitalOrbitalOptimizedIterationDataHandler[T], new_gates: list[GatePoolOperator], iteration_count: int) → Circuit

Build circuit to optimize.

The full unoptimized circuit with the new gates are provided.

Parameters:

  • iteration_data (AdaptiveOrbitalOrbitalOptimizedIterationDataHandler[T]) – The iteration data handler.

  • new_gates (list[GatePoolOperator]) – The new_gates to optimize.

  • iteration_count (int) – The iteration count.

Return type:

Circuit

build_metadata(second_quantized_operator: FermionHermitianSum | PairedHardcoreBosonHermitianSum, initial_ansatz: Circuit) → Mapping[str, HasMetadataHashMethod | int | float | str | Mapping[str, HasMetadataHashMethod | int | float | str | HashableStrDict | None] | None]

Create meta-data that represent the input.

Parameters:
Return type:

Mapping[str, HasMetadataHashMethod | int | float | str | Mapping[str, HasMetadataHashMethod | int | float | str | HashableStrDict | None] | None]

clear_cache() → None

Clear the cache of the underlying VQE and gate selector.

Return type:

None

decide_orbital_optimization_action(*, force_oo: bool, iteration_data: AdaptiveOrbitalOrbitalOptimizedIterationDataHandler[T], optimal_circuit: Circuit, iteration_count: int, last_orbital_change: float, last_gate_change: float) → OrbitalOptimizationAction

Decide between a full orbital optimization, a single Newton step, or skipping entirely.

The decision is based on a three-tier system:

  1. If force_oo is True (too many consecutive non-full steps) the full optimizer is always used.

  2. If the absolute orbital change of the previous OO step exceeds IntermittentOrbitalOptimizerAlgorithmOptions.orbital_change_threshold, a full optimization is performed.

  3. If the absolute change due to the previous gate addition exceeds IntermittentOrbitalOptimizerAlgorithmOptions.gate_addition_threshold, a full optimization is performed.

  4. Otherwise, the orbital gradient norm is compared against two thresholds:

    • Above gradient_threshold → full optimization.

    • Between the skip and full thresholds → single Newton step.

    • Below skip_gradient_threshold → skip entirely.

Parameters:

  • force_oo (bool) – Whether to force a full orbital optimization, bypassing all checks.

  • iteration_data (AdaptiveOrbitalOrbitalOptimizedIterationDataHandler[T]) – The data handler for the current iteration.

  • optimal_circuit (Circuit) – The circuit with the newly optimized gate parameters.

  • iteration_count (int) – The current iteration count, used for logging purposes.

  • last_orbital_change (float) – The absolute orbital energy change from the previous OO step (0.0 if no OO step was performed or the step was skipped).

  • last_gate_change (float) – The absolute change in expectation value from the previous gate addition step.

Return type:

OrbitalOptimizationAction

classmethod persistence_checkpoints() → list[str]

Define the persistence checkpoints used during the orbital optimization adaptive vqe.

These checkpoints specify computational stages where intermediate results can be saved and loaded to optimize computations and ensure reproducibility.

Return type:

list[str]

run(second_quantized_operator: T, gate_pool: GatePool, initial_ansatz: Circuit, callback: AdaptiveIterationCallback | None = None, input_result: SecondQuantizationAdaptiveVqeResult[T] | None = None) → SecondQuantizationAdaptiveVqeResult[T]

Run the VQE and find the eigenvalue.

Parameters:

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

  • gate_pool (GatePool) – The set of gates to choose from when building the ansatz.

  • initial_ansatz (Circuit) – The starting ansatz circuit. Gates from the gate_pool is appended to this.

  • callback (AdaptiveIterationCallback | None) – An optional callback function that is called at each minimizer iteration.

  • input_result (SecondQuantizationAdaptiveVqeResult[T] | None) – A prior results that should be refined.

Return type:

SecondQuantizationAdaptiveVqeResult[T]