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

`BeastSecondQuantizationAdaptiveOrbitalOptimizationVqeCreator`	Builder for the adaptive VQE algorithm.
`SecondQuantizationAdaptiveOrbitalOptimizationVqe`	VQE that combines adaptive and orbital optimization VQE as the underlying algorithm.
`SecondQuantizationAdaptiveOrbitalOptimizationVqeCreator`	Builder for the adaptive VQE algorithm.

class BeastSecondQuantizationAdaptiveOrbitalOptimizationVqeCreator

Bases: VqeCreatorEstimatorMixin[AdaptiveVqeCreator], VqeCreatorMinimizerMixin[AdaptiveVqeCreator], VqeCreatorReminimizerMixin[AdaptiveVqeCreator], VqeCreatorOptionsMixin[AdaptiveVqeCreator], VqeCreatorStoppingCriterionMixin[AdaptiveVqeCreator], VqeCreatorAnalyticalBeastVqeMixin[AdaptiveVqeCreator], VqeCreatorDataPersisterManagerMixin[AdaptiveVqeCreator]

Builder for the adaptive VQE algorithm.

__init__(gate_selector_builder: FastGateSelectorCreator, intermittent_orbital_optimizer_factory: Callable[[Estimator, int | None], OrbitalOptimizerAlgorithm]) → None

Initialize builder for the adaptive VQE.

Parameters:

gate_selector_builder (FastGateSelectorCreator)
intermittent_orbital_optimizer_factory (Callable[[Estimator, int | None], OrbitalOptimizerAlgorithm])

Return type:

None

choose_data_persister_manager() → DataPersisterManagerSubCreator[Self]

Choose the data persister manager to use and whether to save and/or load the data.

Return type:: DataPersisterManagerSubCreator[Self]

choose_minimizer() → MinimizerSubCreator[Self]

Choose minimizer to use for the VQE.

Return type:: MinimizerSubCreator[Self]

choose_orbital_optimizer_stopping_criterion() → StoppingCriterionSubCreator[Self]

Choose an orbital rotation optimization stopping criterion.

Deprecated since version ``choose_orbital_optimizer_stopping_criterion``: is deprecated and will be removed in a future release. Use with_intermittent_orbital_optimizer_options() instead.

Return type:: StoppingCriterionSubCreator[Self]

choose_reminimizer() → ReMinimizerSubCreator[Self]

Choose reminimizer to use for the VQE.

Return type:: ReMinimizerSubCreator[Self]

choose_stopping_criterion() → StoppingCriterionSubCreator[Self]

Choose stopping criterion to use for the VQE.

Return type:: StoppingCriterionSubCreator[Self]

create() → SecondQuantizationAdaptiveOrbitalOptimizationVqe

Create an instance of SecondQuantizationAdaptiveOrbitalOptimizationVqe.

Return type:: SecondQuantizationAdaptiveOrbitalOptimizationVqe

with_analytical_beast_basic_vqe(*, active: bool = True) → Self

Choose to use the analytical basic vqe inside each adaptive iteration, which only works for BEAST.

Instead of having the minimizer call the estimator directly, the estimator is first called to make an analytical expression for the energy as a function of the gate parameter. This expression is then passed to the minimizer, requiring no more measurements.

Note: This feature only works with BEAST with last parameter optimization.

If a reminimizer is chosen, it will be paired with the normal Basic vqe since, only it, supports multiple parameters at once.

Parameters:: active (bool) – Whether to use the analytical beast basic vqe or not.
Return type:: Self

with_estimator(estimator: Estimator) → Self

Set the estimator to use for the VQE.

Parameters:: estimator (Estimator) – Estimator to use. Can be created using the estimator_creator() builder.
Return type:: Self

with_estimator_shots(shots: int | None) → Self

Set the number of shots to use in the estimator.

Parameters:

shots (int | None) – Number of shots to use in the estimator. If None is given, the estimator is assumed to be exact
simulator). ((e.g. the excitation gate)

Return type:

Self

with_final_orbital_optimizer(final_orbital_optimizer: OrbitalOptimizerAlgorithm | None) → Self

Provide an explicit final orbital optimizer instance.

Parameters:: final_orbital_optimizer (OrbitalOptimizerAlgorithm | None) – The orbital optimizer to use for the final optimization step.
Return type:: Self

with_gate_selector_sampler(sampler: Sampler) → Self

Set the sampler for the gate selector to use for the VQE.

Parameters:: sampler (Sampler) – The sampler to use. Can be created using the sampler_creator().
Return type:: Self

with_gate_selector_shots(shots: int | None) → Self

Set the shots on the gate selector to use for the VQE.

Parameters:: shots (int | None) – The number of shots to use in the Gate selector.
Return type:: Self

with_intermittent_orbital_optimizer_options(options: IntermittentOrbitalOptimizerAlgorithmOptions) → Self

Configure options for the intermittent orbital optimizer.

Parameters:: options (IntermittentOrbitalOptimizerAlgorithmOptions) – Options controlling when and how often the intermittent optimizer runs.
Return type:: Self

with_options(options: IterativeVqeOptions) → Self

Set the options to use for the VQE.

Parameters:: options (IterativeVqeOptions) – Options to use.
Return type:: Self

with_orbital_optimizer(orbital_optimizer: OrbitalOptimizerAlgorithm | None) → Self

Provide an explicit intermittent orbital optimizer instance.

Parameters:: orbital_optimizer (OrbitalOptimizerAlgorithm | None) – The orbital optimizer to use during adaptive iterations.
Return type:: Self

with_orbital_optimizer_estimator(estimator: Estimator) → Self

Replace the estimator used by the orbital optimizers.

When the creator was obtained from a factory method such as OrbitalOptimizedIterativeVqeCreator.beast(), the intermittent and final orbital optimizers are built with chemistry-default estimators. This convenience method lets you swap the estimator while keeping all other orbital-optimizer settings (Newton options, basin-hopping options, etc.) unchanged.

Note

If you have already called with_orbital_optimizer() or with_final_orbital_optimizer() with an explicit optimizer instance, those take precedence and this estimator will not be used for those optimizers.

Parameters:: estimator (Estimator) – The estimator to use inside the orbital optimizers.
Return type:: Self

with_orbital_optimizer_shots(shots: int | None) → Self

Set the number of shots used by the orbital optimizers.

Parameters:: shots (int | None) – Number of shots. None means exact (statevector) evaluation.
Return type:: Self

DEFAULT_OO_OPTIONS = IntermittentOrbitalOptimizerAlgorithmOptions(every_nth_iteration=1, gradient_threshold=1e+99, skip_gradient_threshold=1e-16, orbital_change_threshold=1e+99, 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=1e+99, skip_gradient_threshold=1e-16, orbital_change_threshold=1e+99, force_full_after_n_non_full_steps=10, gate_addition_threshold=0.001), options: IterativeVqeOptions = IterativeVqeOptions(max_iterations=5, gates_per_iteration=1, new_parameter_guess=0.0, force_all_iterations=False), 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) – 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

Create meta-data that represent the input.

Parameters:

second_quantized_operator (FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol) – The operator whose expectation value should be minimized.
initial_ansatz (Circuit) – The starting ansatz circuit. Gates from the gate_pool is appended to this.

Return type:

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:

If force_oo is True (too many consecutive non-full steps) the full optimizer is always used.
If the absolute orbital change of the previous OO step exceeds IntermittentOrbitalOptimizerAlgorithmOptions.orbital_change_threshold, a full optimization is performed.
If the absolute change due to the previous gate addition exceeds IntermittentOrbitalOptimizerAlgorithmOptions.gate_addition_threshold, a full optimization is performed.
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]

class SecondQuantizationAdaptiveOrbitalOptimizationVqeCreator

Bases: VqeCreatorEstimatorMixin[AdaptiveVqeCreator], VqeCreatorMinimizerMixin[AdaptiveVqeCreator], VqeCreatorReminimizerMixin[AdaptiveVqeCreator], VqeCreatorOptionsMixin[AdaptiveVqeCreator], VqeCreatorStoppingCriterionMixin[AdaptiveVqeCreator], VqeCreatorGateSelectorMixin[AdaptiveVqeCreator], VqeCreatorAnalyticalBeastVqeMixin[AdaptiveVqeCreator], VqeCreatorDataPersisterManagerMixin[AdaptiveVqeCreator]

Builder for the adaptive VQE algorithm.

__init__(intermittent_orbital_optimizer_factory: Callable[[Estimator, int | None], OrbitalOptimizerAlgorithm]) → None

Initialize builder for the adaptive VQE.

Parameters:: intermittent_orbital_optimizer_factory (Callable[[Estimator, int | None], OrbitalOptimizerAlgorithm])
Return type:: None

choose_data_persister_manager() → DataPersisterManagerSubCreator[Self]

Choose the data persister manager to use and whether to save and/or load the data.

Return type:: DataPersisterManagerSubCreator[Self]

choose_minimizer() → MinimizerSubCreator[Self]

Choose minimizer to use for the VQE.

Return type:: MinimizerSubCreator[Self]

choose_orbital_optimizer_stopping_criterion() → StoppingCriterionSubCreator[Self]

Choose an orbital rotation optimization stopping criterion.

Deprecated since version ``choose_orbital_optimizer_stopping_criterion``: is deprecated and will be removed in a future release. Use with_intermittent_orbital_optimizer_options() instead.

Return type:: StoppingCriterionSubCreator[Self]

choose_reminimizer() → ReMinimizerSubCreator[Self]

Choose reminimizer to use for the VQE.

Return type:: ReMinimizerSubCreator[Self]

choose_stopping_criterion() → StoppingCriterionSubCreator[Self]

Choose stopping criterion to use for the VQE.

Return type:: StoppingCriterionSubCreator[Self]

create() → SecondQuantizationAdaptiveOrbitalOptimizationVqe

Create an instance of SecondQuantizationAdaptiveOrbitalOptimizationVqe.

Return type:: SecondQuantizationAdaptiveOrbitalOptimizationVqe

with_analytical_beast_basic_vqe(*, active: bool = True) → Self

Choose to use the analytical basic vqe inside each adaptive iteration, which only works for BEAST.

Instead of having the minimizer call the estimator directly, the estimator is first called to make an analytical expression for the energy as a function of the gate parameter. This expression is then passed to the minimizer, requiring no more measurements.

Note: This feature only works with BEAST with last parameter optimization.

If a reminimizer is chosen, it will be paired with the normal Basic vqe since, only it, supports multiple parameters at once.

Parameters:: active (bool) – Whether to use the analytical beast basic vqe or not.
Return type:: Self

with_estimator(estimator: Estimator) → Self

Set the estimator to use for the VQE.

Parameters:: estimator (Estimator) – Estimator to use. Can be created using the estimator_creator() builder.
Return type:: Self

with_estimator_shots(shots: int | None) → Self

Set the number of shots to use in the estimator.

Parameters:

shots (int | None) – Number of shots to use in the estimator. If None is given, the estimator is assumed to be exact
simulator). ((e.g. the excitation gate)

Return type:

Self

with_final_orbital_optimizer(final_orbital_optimizer: OrbitalOptimizerAlgorithm | None) → Self

Provide an explicit final orbital optimizer instance.

Parameters:: final_orbital_optimizer (OrbitalOptimizerAlgorithm | None) – The orbital optimizer to use for the final optimization step.
Return type:: Self

with_gate_selector(gate_selector: GateSelector) → Self

Choose the gate selector to use for the VQE.

Parameters:: gate_selector (GateSelector) – Gate selector to use. Can be created using the gate_selector_creator().
Return type:: Self

with_intermittent_orbital_optimizer_options(options: IntermittentOrbitalOptimizerAlgorithmOptions) → Self

Configure options for the intermittent orbital optimizer.

Parameters:: options (IntermittentOrbitalOptimizerAlgorithmOptions) – Options controlling when and how often the intermittent optimizer runs.
Return type:: Self

with_options(options: IterativeVqeOptions) → Self

Set the options to use for the VQE.

Parameters:: options (IterativeVqeOptions) – Options to use.
Return type:: Self

with_orbital_optimizer(orbital_optimizer: OrbitalOptimizerAlgorithm | None) → Self

Provide an explicit intermittent orbital optimizer instance.

Parameters:: orbital_optimizer (OrbitalOptimizerAlgorithm | None) – The orbital optimizer to use during adaptive iterations.
Return type:: Self

with_orbital_optimizer_estimator(estimator: Estimator) → Self

Replace the estimator used by the orbital optimizers.

When the creator was obtained from a factory method such as OrbitalOptimizedIterativeVqeCreator.beast(), the intermittent and final orbital optimizers are built with chemistry-default estimators. This convenience method lets you swap the estimator while keeping all other orbital-optimizer settings (Newton options, basin-hopping options, etc.) unchanged.

Note

If you have already called with_orbital_optimizer() or with_final_orbital_optimizer() with an explicit optimizer instance, those take precedence and this estimator will not be used for those optimizers.

Parameters:: estimator (Estimator) – The estimator to use inside the orbital optimizers.
Return type:: Self

with_orbital_optimizer_shots(shots: int | None) → Self

Set the number of shots used by the orbital optimizers.

Parameters:: shots (int | None) – Number of shots. None means exact (statevector) evaluation.
Return type:: Self