qrunch.chemistry.calculators.vqe_ground_state_calculator

Classes for calculating the ground state energy of a molecule using a VQE algorithm.

The module contains one class for using a non-adaptive VQE algorithm, BasicVqeGroundStateCalculator, and one class for using an adaptive VQE algorithm, AdaptiveVqeGroundStateCalculator.

The latter algorithm builds the circuit ansatz adaptively, and is thus much more gate efficient. The adaptive version is the recommended option, while the “basic” (non-adaptive) is meant for expert users, who want to build their own ansatz circuit.

Classes

AdaptiveVqeGroundStateCalculator

Class for calculating the ground state energy using an adaptive VQE algorithm.

BasicVqeGroundStateCalculator

Class for calculating the ground state energy using a non-adaptive VQE algorithm.

BeastAcceleratedAdaptiveVqeGroundStateCalculator

Class for calculating the ground state energies of a reaction path.

BeastVqeGroundStateCalculator

Class for calculating the ground state energies of a reaction path using a BEAST-VQE algorithm.
class AdaptiveVqeGroundStateCalculator

Bases: object

Class for calculating the ground state energy using an adaptive VQE algorithm.

__init__(vqe: SecondQuantizationAdaptiveVqeAlgorithm, *, paired_electron_approximation: bool, include_single_excitations: bool = True, include_double_excitations: bool = True, excitation_gate_pool_options: ExcitationGatePoolOptions | None = None) → None

Initialize the adaptive VQE ground state energy calculator.

Parameters:

  • vqe (SecondQuantizationAdaptiveVqeAlgorithm) – The VQE algorithm to use for the calculation. Must be an adaptive VQE. If a basic VQE is desired, use the BasicVqeGroundStateCalculator class instead.

  • paired_electron_approximation (bool) – Whether to use the paired-electron approximation.

  • include_single_excitations (bool) – whether to include single-excitation gates in the gate pool.

  • include_double_excitations (bool) – whether to include double-excitation gates in the gate pool.

  • excitation_gate_pool_options (ExcitationGatePoolOptions | None) – Options for the excitation gate pool.

Return type:

None

calculate(problem: GroundStateProblem, callback: AdaptiveIterationCallback | None = None, vqe_input_result: AdaptiveVqeGroundStateProblemCalculatorResult | None = None) → AdaptiveVqeGroundStateProblemCalculatorResult
calculate(problem: ReactionPathProblem, callback: AdaptiveIterationCallback | None = None, vqe_input_result: AdaptiveVqeGroundStateProblemCalculatorResult | None = None) → AdaptiveVqeReactionPathProblemCalculatorResult

Calculate the ground state energies along the path of the given reaction path problem.

Parameters:
Return type:

AdaptiveVqeGroundStateProblemCalculatorResult | AdaptiveVqeReactionPathProblemCalculatorResult

static create_start_vqe_input(parametrized_circuit: Circuit, initial_parameters: dict[Parameter, float] | None = None, active_electrons_energy_per_macro_iteration: ListOfExpectationValues | None = None) → AdaptiveVqeGroundStateProblemCalculatorResult

Create a start VQE input from a parametrized circuit and optional initial parameter values.

This is useful when the user already has a parametrized ansatz circuit and wants to use it as the starting point for an adaptive VQE calculation.

If initial_parameters is not provided, all parameters default to 0.0.

If active_electrons_energy_per_macro_iteration is not provided, a placeholder list with one ExpectationValue(0.0, 0.0) entry per initial parameter is created. This ensures that the adaptive VQE treats the initial parameters as prior iterations. For example, if 10 parametrized gates are used in the parametrized_circuit, the adaptive VQE will start at the 11th iteration.

Note that if a greedy parameter optimization strategy is employed in the adaptive VQE, the initial parameters will be used and not modified. A balanced parameter optimization strategy will re-optimize the parameters at some point.

Parameters:

  • parametrized_circuit (Circuit) – A circuit that may contain unspecified parameters.

  • initial_parameters (dict[Parameter, float] | None) – Optional dictionary mapping each Parameter to its initial value. If None, every unspecified parameter is initialised to 0.0.

  • active_electrons_energy_per_macro_iteration (ListOfExpectationValues | None) – Optional list of expectation values for each prior macro iteration. If None, one placeholder ExpectationValue(0.0, 0.0) entry is created per initial parameter.

Return type:

AdaptiveVqeGroundStateProblemCalculatorResult

static create_start_vqe_input_from_circuit(circuit: Circuit) → AdaptiveVqeGroundStateProblemCalculatorResult

Create a start VQE input from a fully specified (parameter-free) circuit.

This is useful when the circuit comes from an external source, e.g. an MP2 state-preparation algorithm, and should be used as the starting point for an adaptive VQE calculation.

Parameters:

circuit (Circuit) – A fully specified circuit with no unspecified parameters.

Return type:

AdaptiveVqeGroundStateProblemCalculatorResult

class BasicVqeGroundStateCalculator

Bases: object

Class for calculating the ground state energy using a non-adaptive VQE algorithm.

__init__(vqe: SecondQuantizationVqeAlgorithm) → None

Initialize the basic VQE ground state energy calculator.

Parameters:

vqe (SecondQuantizationVqeAlgorithm) – The VQE algorithm to use for the calculation. Must be a non-adaptive VQE. If an adaptive VQE is desired, use the AdaptiveVqeGroundStateCalculator instead.

Return type:

None

calculate(problem: GroundStateProblem, ansatz: Circuit, *, paired_electron_approximation: bool) → GroundStateProblemCalculatorResult
calculate(problem: ReactionPathProblem, ansatz: Circuit, *, paired_electron_approximation: bool) → ReactionPathProblemCalculatorResult

Calculate the expectation value of the ground state energy of the given molecule/reaction.

Parameters:
Return type:

GroundStateProblemCalculatorResult | ReactionPathProblemCalculatorResult

class BeastAcceleratedAdaptiveVqeGroundStateCalculator

Bases: object

Class for calculating the ground state energies of a reaction path.

This calculation is using an adaptive algorithm accelerated by a BEAST-VQE algorithm. The BEAST-VQE algorithm is a combination of using the FAST-VQE idea behind adaptively adding gates to a VQE (https://doi.org/10.1103/PhysRevA.108.052422) coupled with the orbital-optimization correction from (https://doi.org/10.1038/s41534-023-00730-8).

The latter is a necessary correction when using the paired-electron approximation thereby the name ‘BEAST’ (Bosonic Encoding Adaptive Sampling Theory).

__init__(beast_calculator: BeastVqeGroundStateCalculator, adaptive_calculator: AdaptiveVqeGroundStateCalculator) → None

Initialize the molecular ground state energy calculator.

Parameters:
Return type:

None

calculate(problem: GroundStateProblem, callback: AdaptiveIterationCallback | None = None, vqe_input_result: BeastVqeGroundStateProblemCalculatorResult | None = None) → AdaptiveVqeGroundStateProblemCalculatorResult
calculate(problem: ReactionPathProblem, callback: AdaptiveIterationCallback | None = None, vqe_input_result: BeastVqeGroundStateProblemCalculatorResult | None = None) → AdaptiveVqeReactionPathProblemCalculatorResult

Calculate the ground state energies along the path of the given reaction path problem.

Parameters:
Return type:

AdaptiveVqeGroundStateProblemCalculatorResult | AdaptiveVqeReactionPathProblemCalculatorResult

class BeastVqeGroundStateCalculator

Bases: object

Class for calculating the ground state energies of a reaction path using a BEAST-VQE algorithm.

The BEAST-VQE algorithm is a combination of using the FAST-VQE idea behind adaptively adding gates to a VQE (https://doi.org/10.1103/PhysRevA.108.052422) together with a paired-electron approximation and bosonic encoding, thereby the name ‘BEAST’ (Bosonic Encoding Adaptive Sampling Theory).

This can optionally be coupled with the orbital-optimization correction from (https://doi.org/10.1038/s41534-023-00730-8), and/or a second-order perturbative correction to the energy.

__init__(vqe: SecondQuantizationAdaptiveVqeAlgorithm, second_order_corrector: BeastSecondOrderPerturbationCorrector | None = None) → None

Initialize the molecular ground state energy calculator.

Parameters:

  • vqe (SecondQuantizationAdaptiveVqeAlgorithm) – The VQE algorithm to use for the calculation. Must be a an adaptive VQE.

  • second_order_corrector (BeastSecondOrderPerturbationCorrector | None) – Corrector used to calculate correction to the final energy.

Return type:

None

calculate(problem: GroundStateProblem, callback: AdaptiveIterationCallback | None = None, vqe_input_result: BeastVqeGroundStateProblemCalculatorResult | None = None) → BeastVqeGroundStateProblemCalculatorResult
calculate(problem: ReactionPathProblem, callback: AdaptiveIterationCallback | None = None, vqe_input_result: BeastVqeGroundStateProblemCalculatorResult | None = None) → BeastVqeReactionPathProblemCalculatorResult

Calculate the ground state energies along the path of the given reaction path problem.

Parameters:
Return type:

BeastVqeGroundStateProblemCalculatorResult | BeastVqeReactionPathProblemCalculatorResult