qrunch.quantum.algorithms.second_quantization.vqes.vqe_protocols

Interfaces for the VQE classes and their options dataclasses.

Classes

`SecondQuantizationAdaptiveVqeAlgorithm`	Protocol class for VQE that takes a second quantized operator as input and returns the eigenvalue.
`SecondQuantizationAdaptiveVqeResult`	Result of the SecondQuantizationAdaptiveVqe calculation.
`SecondQuantizationVqeAlgorithm`	Protocol class for VQE that takes a second quantized operator as input and returns the eigenvalue.
`SecondQuantizationVqeResult`	Result of the VQE calculation.
`VqeCreatorAnalyticalBeastVqeMixin`	Mixin to add estimator options to a creator that own a vqe_creator.
`VqeCreatorDataPersisterManagerMixin`	Mixin to add data persister manager options to a creator that own a vqe_creator.
`VqeCreatorEstimatorMixin`	Mixin to add estimator options to a creator that own a vqe_creator.
`VqeCreatorGateSelectorMixin`	Mixin to add estimator options to a creator that own a vqe_creator.
`VqeCreatorGateSelectorSamplerMixin`	Mixin to add estimator options to a creator that own a vqe_creator.
`VqeCreatorMinimizerMixin`	Mixin to add minimizer options to a creator that own a vqe_creator.
`VqeCreatorOptionsMixin`	Mixin to add estimator options to a creator that own a vqe_creator.
`VqeCreatorOrbitalOptimizationStoppingCriterionMixin`	Mixin to add minimizer options to a creator that own a vqe_creator.
`VqeCreatorOrbitalOptimizerMixin`	Mixin to add estimator options to a creator that own a vqe_creator.
`VqeCreatorReminimizerMixin`	Mixin to add minimizer options to a creator that own a vqe_creator.
`VqeCreatorStoppingCriterionMixin`	Mixin to add minimizer options to a creator that own a vqe_creator.
`VqeCreatorWithAnalyticalBeastVqeProtocol`	VQE creator protocol that ensure gate selector interface.
`VqeCreatorWithDataPersisterManagerProtocol`	VQE creator protocol that ensure a readable/writable data_persister_manager slot.
`VqeCreatorWithEstimatorProtocol`	VQE creator protocol that ensure estimator interface.
`VqeCreatorWithGateSelectorProtocol`	VQE creator protocol that ensure gate selector interface.
`VqeCreatorWithGateSelectorSamplerProtocol`	VQE creator protocol that ensure gate selector interface.
`VqeCreatorWithMinimizerProtocol`	VQE creator protocol that ensure a readable/writable minimizer slot.
`VqeCreatorWithOptionsProtocol`	VQE creator protocol that ensure options interface.
`VqeCreatorWithOrbitalOptimizationStoppingCriterionProtocol`	VQE creator protocol that ensure a readable/writable stopping_criterion slot.
`VqeCreatorWithOrbitalOptimizerProtocol`	VQE creator protocol that ensure orbital optimizer interface.
`VqeCreatorWithReminimizerProtocol`	VQE creator protocol that ensure a readable/writable reminimizer slot.
`VqeCreatorWithStoppingCriterionProtocol`	VQE creator protocol that ensure a readable/writable stopping_criterion slot.

class SecondQuantizationAdaptiveVqeAlgorithm

Bases: ABC

Protocol class for VQE that takes a second quantized operator as input and returns the eigenvalue.

The VQEs are based on an underlying quantum algorithm, which perform the eigenvalue calculation.

abstractmethod clear_cache() → None

Clear the cache of the underlying VQE.

Return type:: None

abstractmethod 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 adaptive iteration.
input_result (SecondQuantizationAdaptiveVqeResult[T] | None) – A prior results that should be refined.

Return type:

SecondQuantizationAdaptiveVqeResult[T]

class SecondQuantizationAdaptiveVqeResult

Bases: HasCustomEncoding, Generic[T_COV]

Result of the SecondQuantizationAdaptiveVqe calculation.

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

Parameters:

unspecified_circuit – Circuit ansatz
parameters – Optimal parameters that minimizes the expectation value of the ansatz
estimated_value – Final estimated expectation value of the operator.
estimated_value_per_gate_iteration – Estimated expectation value of the operator for every iteration where an additional gate was added.
operator – The second quantized operator under consideration. Might be rotated compared to the input.
is_converged – True if VQE converged.
best_iteration – The iteration with the best estimated cost

__init__(unspecified_circuit: Circuit, parameters: dict[Parameter, float], estimated_value: ExpectationValue, estimated_value_per_gate_iteration: ListOfExpectationValues, operator: T_COV, is_converged: bool, best_iteration: int) → None

Parameters:

unspecified_circuit (Circuit)
parameters (dict[Parameter, float])
estimated_value (ExpectationValue)
estimated_value_per_gate_iteration (ListOfExpectationValues)
operator (T_COV)
is_converged (bool)
best_iteration (int)

Return type:

None

best_iteration: int

classmethod decode(data: dict[str, Any]) → SecondQuantizationAdaptiveVqeResult[T_COV]

Decode a dictionary to an instance of TensorHyperContractionIntegrals.

Parameters:: data (dict[str, Any]) – The dictionary representation of a TensorHyperContractionIntegrals instance.
Return type:: SecondQuantizationAdaptiveVqeResult[T_COV]

encode() → dict[str, Any]

Encode the instance into a dictionary.

Return type:: dict[str, Any]

estimated_value: ExpectationValue

estimated_value_per_gate_iteration: ListOfExpectationValues

is_converged: bool

operator: T_COV

parameters: dict[Parameter, float]

property specified_circuit: Circuit: Circuit ansatz with the optimal parameters.

to_pauli_result() → PauliAdaptiveVqeResult

Return the result of the VQE calculation as a Pauli VQE result.

Return type:: PauliAdaptiveVqeResult

unspecified_circuit: Circuit

class SecondQuantizationVqeAlgorithm

Bases: ABC

Protocol class for VQE that takes a second quantized operator as input and returns the eigenvalue.

The VQEs are based on an underlying quantum algorithm, which perform the eigenvalue calculation.

abstractmethod clear_cache() → None

Clear the cache of the underlying VQE.

Return type:: None

abstractmethod run(second_quantized_operator: T, circuit: Circuit, initial_parameter_guess: dict[Parameter, float] | None = None) → SecondQuantizationVqeResult[T]

Run the VQE and find the eigenvalue.

Parameters:

second_quantized_operator (T) – The operator whose expectation value should be minimized.
circuit (Circuit) – The parametrized circuit to find optimal parameters for. Should contain unspecified parameters.
initial_parameter_guess (dict[Parameter, float] | None) – Dict specifying the initial value of each Parameter. If None is given initial guess is 0.0

Return type:

SecondQuantizationVqeResult[T]

class SecondQuantizationVqeResult

Bases: Generic[T_COV]

Result of the VQE calculation.

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

Parameters:

estimator_shots – The total amount of shots used by the estimator
parameters – Optimal parameters that minimizes the expectation value of the ansatz.
estimated_value – Final estimated expectation value of the operator.
operator – The second quantized operator under consideration. Might be rotated compared to the input.
unspecified_circuit – The unspecified circuit.

__init__(estimator_shots: int, parameters: dict[Parameter, float], estimated_value: ExpectationValue, operator: T_COV, unspecified_circuit: Circuit) → None

Parameters:

estimator_shots (int)
parameters (dict[Parameter, float])
estimated_value (ExpectationValue)
operator (T_COV)
unspecified_circuit (Circuit)

Return type:

None

estimated_value: ExpectationValue

estimator_shots: int

operator: T_COV

parameters: dict[Parameter, float]

property specified_circuit: Circuit | None: Circuit ansatz with the optimal parameters.

unspecified_circuit: Circuit

class VqeCreatorAnalyticalBeastVqeMixin

Bases: Generic[VqeCreatorWithAnalyticalBeastVqeT], ABC

Mixin to add estimator options to a creator that own a vqe_creator.

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

class VqeCreatorDataPersisterManagerMixin

Bases: Generic[VqeCreatorWithDataPersisterManagerT], ABC

Mixin to add data persister manager options to a creator that own a vqe_creator.

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]

class VqeCreatorEstimatorMixin

Bases: Generic[VqeCreatorWithEstimatorT], ABC

Mixin to add estimator options to a creator that own a vqe_creator.

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

class VqeCreatorGateSelectorMixin

Bases: Generic[VqeCreatorWithGateSelectorT], ABC

Mixin to add estimator options to a creator that own a vqe_creator.

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

class VqeCreatorGateSelectorSamplerMixin

Bases: Generic[VqeCreatorWithGateSelectorSamplerT], ABC

Mixin to add estimator options to a creator that own a vqe_creator.

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

class VqeCreatorMinimizerMixin

Bases: Generic[VqeCreatorWithMinimizerT], ABC

Mixin to add minimizer options to a creator that own a vqe_creator.

choose_minimizer() → MinimizerSubCreator[Self]

Choose minimizer to use for the VQE.

Return type:: MinimizerSubCreator[Self]

class VqeCreatorOptionsMixin

Bases: Generic[VqeCreatorWithOptionsT], ABC

Mixin to add estimator options to a creator that own a vqe_creator.

with_options(options: IterativeVqeOptions) → Self

Set the options to use for the VQE.

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

class VqeCreatorOrbitalOptimizationStoppingCriterionMixin

Bases: Generic[VqeCreatorWithOrbitalOptimizationStoppingCriterionT], ABC

Mixin to add minimizer options to a creator that own a vqe_creator.

choose_orbital_optimizer_stopping_criterion() → StoppingCriterionSubCreator[Self]

Choose an orbital rotation optimization stopping criterion.

Return type:: StoppingCriterionSubCreator[Self]

class VqeCreatorOrbitalOptimizerMixin

Bases: Generic[VqeCreatorWithOrbitalOptimizerT], ABC

Mixin to add estimator options to a creator that own a vqe_creator.

with_orbital_optimizer(orbital_optimizer: OrbitalOptimizerAlgorithm) → Self

Choose minimizer to determine optimal orbital rotation parameters in adaptive orbital optimization VQE.

Parameters:: orbital_optimizer (OrbitalOptimizerAlgorithm)
Return type:: Self

class VqeCreatorReminimizerMixin

Bases: Generic[VqeCreatorWithReminimizerT], ABC

Mixin to add minimizer options to a creator that own a vqe_creator.

choose_reminimizer() → ReMinimizerSubCreator[Self]

Choose reminimizer to use for the VQE.

Return type:: ReMinimizerSubCreator[Self]

class VqeCreatorStoppingCriterionMixin

Bases: Generic[VqeCreatorWithStoppingCriterionT], ABC

Mixin to add minimizer options to a creator that own a vqe_creator.

choose_stopping_criterion() → StoppingCriterionSubCreator[Self]

Choose stopping criterion to use for the VQE.

Return type:: StoppingCriterionSubCreator[Self]

class VqeCreatorWithAnalyticalBeastVqeProtocol

Bases: Protocol

VQE creator protocol that ensure gate selector interface.

__init__(*args, **kwargs)

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

class VqeCreatorWithDataPersisterManagerProtocol

Bases: Protocol

VQE creator protocol that ensure a readable/writable data_persister_manager slot.

__init__(*args, **kwargs)

class VqeCreatorWithEstimatorProtocol

Bases: Protocol

VQE creator protocol that ensure estimator interface.

__init__(*args, **kwargs)

with_estimator(estimator: Estimator) → Self

Set estimator on the VQE creator.

Parameters:: estimator (Estimator)
Return type:: Self

with_estimator_shots(shots: int | None) → Self

Set estimator shots on the VQE creator.

Parameters:: shots (int | None)
Return type:: Self

class VqeCreatorWithGateSelectorProtocol

Bases: Protocol

VQE creator protocol that ensure gate selector interface.

__init__(*args, **kwargs)

with_gate_selector(gate_selector: GateSelector) → Self

Set the gate selector to use for the VQE creator.

Parameters:: gate_selector (GateSelector)
Return type:: Self

class VqeCreatorWithGateSelectorSamplerProtocol

Bases: Protocol

VQE creator protocol that ensure gate selector interface.

__init__(*args, **kwargs)

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

class VqeCreatorWithMinimizerProtocol

Bases: Protocol

VQE creator protocol that ensure a readable/writable minimizer slot.

__init__(*args, **kwargs)

class VqeCreatorWithOptionsProtocol

Bases: Protocol

VQE creator protocol that ensure options interface.

__init__(*args, **kwargs)

with_options(options: IterativeVqeOptions) → Self

Set options on the VQE creator.

Parameters:: options (IterativeVqeOptions)
Return type:: Self

class VqeCreatorWithOrbitalOptimizationStoppingCriterionProtocol

Bases: Protocol

VQE creator protocol that ensure a readable/writable stopping_criterion slot.

__init__(*args, **kwargs)

class VqeCreatorWithOrbitalOptimizerProtocol

Bases: Protocol

VQE creator protocol that ensure orbital optimizer interface.

__init__(*args, **kwargs)

with_orbital_optimizer(orbital_optimizer: OrbitalOptimizerAlgorithm | None) → Self

Set the orbital optimizer to use for the VQE creator.

Parameters:: orbital_optimizer (OrbitalOptimizerAlgorithm | None)
Return type:: Self

class VqeCreatorWithReminimizerProtocol

Bases: Protocol

VQE creator protocol that ensure a readable/writable reminimizer slot.

__init__(*args, **kwargs)

class VqeCreatorWithStoppingCriterionProtocol

Bases: Protocol

VQE creator protocol that ensure a readable/writable stopping_criterion slot.

__init__(*args, **kwargs)