qrunch.chemistry.ground_state_problem.calculators.vqe_ground_state_problem_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, BasicVqeGroundStateProblemCalculator, and one class for using an adaptive VQE algorithm, AdaptiveVqeGroundStateProblemCalculator.

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.

Functions

create_vqe_input_from_circuit(circuit)

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

Classes

AdaptiveVqeGroundStateProblemCalculator

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

BasicVqeGroundStateProblemCalculator

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

BeastAcceleratedAdaptiveVqeGroundStateProblemCalculator

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

BeastVqeGroundStateProblemCalculator

Class for calculating the ground state energy of a molecule using a BEAST-VQE algorithm.
class AdaptiveVqeGroundStateProblemCalculator

Bases: object

Class for calculating the ground state energy of a molecule 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 molecular 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 BasicVqeGroundStateProblemCalculator 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(ground_state_problem: RestrictedGroundStateProblem | UnrestrictedGroundStateProblem, callback: AdaptiveIterationCallback | None = None, vqe_input_result: AdaptiveVqeGroundStateProblemCalculatorResult | None = None) → AdaptiveVqeGroundStateProblemCalculatorResult

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

Parameters:
Return type:

AdaptiveVqeGroundStateProblemCalculatorResult

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, and it 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 BasicVqeGroundStateProblemCalculator

Bases: object

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

__init__(vqe: SecondQuantizationVqeAlgorithm) → None

Initialize the molecular 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 AdaptiveVqeGroundStateProblemCalculator instead.

Return type:

None

calculate(ground_state_problem: RestrictedGroundStateProblem | UnrestrictedGroundStateProblem, ansatz: Circuit, *, paired_electron_approximation: bool) → GroundStateProblemCalculatorResult

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

Parameters:
Return type:

GroundStateProblemCalculatorResult

class BeastAcceleratedAdaptiveVqeGroundStateProblemCalculator

Bases: object

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

__init__(beast_calculator: BeastVqeGroundStateProblemCalculator, adaptive_calculator: AdaptiveVqeGroundStateProblemCalculator) → None

Initialize the molecular ground state energy calculator.

Parameters:
Return type:

None

calculate(ground_state_problem: RestrictedGroundStateProblem | UnrestrictedGroundStateProblem, callback: AdaptiveIterationCallback | None = None, vqe_input_result: BeastVqeGroundStateProblemCalculatorResult | None = None) → AdaptiveVqeGroundStateProblemCalculatorResult

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

Parameters:
Return type:

AdaptiveVqeGroundStateProblemCalculatorResult

class BeastVqeGroundStateProblemCalculator

Bases: object

Class for calculating the ground state energy of a molecule 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) 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__(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(ground_state_problem: RestrictedGroundStateProblem | UnrestrictedGroundStateProblem, callback: AdaptiveIterationCallback | None = None, vqe_input_result: BeastVqeGroundStateProblemCalculatorResult | None = None) → BeastVqeGroundStateProblemCalculatorResult

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

Parameters:
Return type:

BeastVqeGroundStateProblemCalculatorResult

static extract_integrals_from_operator(operator: FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol) → RestrictedElectronicStructureIntegrals

Return potentially orbital optimized integrals from the operator.

Parameters:

operator (FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol) – The operator who hold the integrals.

Return type:

RestrictedElectronicStructureIntegrals

create_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, and it 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