qrunch.quantum.estimators.creators

Contains builders for all available estimators .

Functions

estimator_creator()

Start creating an estimator.

Classes

`BackendEstimatorCreator`	Builder for the backend estimator.
`CuQuantumStatevectorEstimatorCreator`	Builder for the CuQuantum state vector estimator.
`EstimatorCreator`	Builder for all types of estimators available.
`ExcitationGateEstimatorCreator`	Builder for the excitation gate estimator.
`MemoryRestrictedEstimatorCreator`	Builder for the memory restricted estimator.
`QiskitStateVectorEstimatorCreator`	Builder for the Qiskit state vector estimator.

class BackendEstimatorCreator

Bases: object

Builder for the backend estimator.

__init__() → None

Initialize a backend estimator builder.

Return type:: None

choose_backend() → BackendSubCreator[Self]

Choose the backend to use for the estimator.

Return type:: BackendSubCreator[Self]

choose_estimator_error_mitigator() → EstimatorErrorMitigatorSubCreator[Self]

Add an error mitigator to use with the estimation.

Return type:: EstimatorErrorMitigatorSubCreator[Self]

choose_grouper() → MeasurementGrouperSubCreator[Self]

Choose the grouper to use for the estimator.

Return type:: MeasurementGrouperSubCreator[Self]

choose_sampler_error_mitigator() → SamplerErrorMitigatorSubCreator[Self]

Choose the error mitigator to use with the backend.

Return type:: SamplerErrorMitigatorSubCreator[Self]

create(*, with_shot_counter: Literal[False] = False) → BackendEstimator

create(*, with_shot_counter: Literal[True]) → EstimatorShotCounter

Create the configured estimator.

Parameters:: with_shot_counter (bool) – Whether to include a shot counter in the estimator. This will instead return a EstimatorShotCounter wrapped around the BackendEstimator.
Return type:: BackendEstimator | EstimatorShotCounter

with_measurement_cache(measurement_cache: MeasurementCache) → Self

Add an cache to use with the estimator.

Parameters:: measurement_cache (MeasurementCache) – The cache to use.
Return type:: Self

class CuQuantumStatevectorEstimatorCreator

Bases: object

Builder for the CuQuantum state vector estimator.

static create() → CuQuantumStatevectorEstimator

Create an instance of CuQuantumStatevectorEstimator.

Return type:: CuQuantumStatevectorEstimator

class EstimatorCreator

Bases: object

Builder for all types of estimators available. Default is the ExcitationGateEstimator.

static backend() → BackendEstimatorCreator

Narrow the estimator type to a backend estimator.

A backend estimator uses sampling from the quantum circuit using one of the available quantum or simulation backends to estimate expectation values of observables. Because the estimation is done using samples, it is not an exact calculation and requires shots != None when performing the estimation. Also if used with a simulated backend, it is typically slower than using the other available estimators directly.

Return type:: BackendEstimatorCreator

static create() → ExcitationGateEstimator

Create an instance of ExcitationGateEstimator.

Return type:: ExcitationGateEstimator

static cuquantum_statevector() → CuQuantumStatevectorEstimatorCreator

Narrow the estimator type to an estimator using the CuQuantum statevector simulator.

This is a facade around NVIDIA’s CuQuantum state vector simulator for exact circuit simulation.

Return type:: CuQuantumStatevectorEstimatorCreator

static excitation_gate() → ExcitationGateEstimatorCreator

Narrow the estimator type to an excitation gate estimator.

This estimator uses Kvantify’s proprietary simulator optimized for circuits built from excitation gates, and thus tailored specifically for quantum chemistry applications. It is thus the recommended estimator for simulating quantum algorithms for quantum chemistry.

Return type:: ExcitationGateEstimatorCreator

static memory_restricted() → MemoryRestrictedEstimatorCreator

Narrow the estimator type to a memory restricted estimator.

This estimator is a memory-efficient version that uses Kvantify’s proprietary simulator optimized for circuits built from excitation gates, and thus tailored specifically for quantum chemistry applications. It uses a configurable maximum amount of memory to enable simulation of larger systems than the excitation gate estimator, switching to a more memory-efficient mode when the limit is reached.

For small systems where the full state vector can be stored in memory, the excitation gate estimator will typically be faster, but for larger systems where the full state vector cannot be stored in memory, or is too slow, this simulator will enable simulation of larger systems at the cost of some precision.

Return type:: MemoryRestrictedEstimatorCreator

static qiskit_statevector() → QiskitStateVectorEstimatorCreator

Narrow the estimator type to an estimator using the Qiskit statevector simulator.

This is a facade around Qiskit’s state vector simulator for exact circuit simulation.

Return type:: QiskitStateVectorEstimatorCreator

class ExcitationGateEstimatorCreator

Bases: object

Builder for the excitation gate estimator.

__init__() → None

Initialize an excitation gate estimator builder.

Return type:: None

choose_estimator_error_mitigator() → EstimatorErrorMitigatorSubCreator[Self]

Add an error mitigator to use with the estimation.

Return type:: EstimatorErrorMitigatorSubCreator[Self]

choose_grouper() → MeasurementGrouperSubCreator[Self]

Choose the grouper to use for the estimator.

Return type:: MeasurementGrouperSubCreator[Self]

create(*, with_shot_counter: Literal[False] = False) → ExcitationGateEstimator

create(*, with_shot_counter: Literal[True]) → EstimatorShotCounter

Create the configured estimator.

Parameters:: with_shot_counter (bool) – Whether to include a shot counter in the estimator. This will instead return a EstimatorShotCounter wrapped around the ExcitationGateEstimator.
Return type:: ExcitationGateEstimator | EstimatorShotCounter

with_eps(eps: float | None) → Self

Choose epsilon to use as lower bound for absolute value of amplitude when sampling in the estimator.

Parameters:: eps (float | None) – Epsilon to use as lower bound for absolute amplitude when sampling.
Return type:: Self

with_float_type(float_type: Literal['f32', 'f64']) → Self

Chose the float type precision used in the estimator.

Parameters:: float_type (Literal['f32', 'f64']) – Float type to use.
Return type:: Self

with_parallel_setting(parallel_setting: Literal['serial', 'parallel']) → Self

Choose parallel setting to use in the estimator.

Parameters:: parallel_setting (Literal['serial', 'parallel']) – Parallel setting to use.
Return type:: Self

with_seed(seed: int | None) → Self

Choose seed to use for randomness in the estimator.

Parameters:: seed (int | None) – Seed used to initialize internal randomness in the simulator.
Return type:: Self

with_spin_particle_conservation() → Self

Specify that the number of spin up and spin down particles are conserved separately (fermionic encoding).

Excitation gates are expected to conserve the number of particles in each half of the circuit.

This is the case of fermionic encoding where half the number of qubits represent spin up orbitals, while the other half represent spin down orbitals. Thus excitation gates represents spin conserving gates.

In case of hard-core bosonic encoding the qubits represent spatial orbitals (occupied by electron pairs) and thus the total number of (electron-pair) particles are conserved, thus total particle conservation must be used.

Return type:: Self

with_total_particle_conservation() → Self

Specify that the total number of particles are conserved (bosonic encoding).

Excitation gates are expected to conserve the total number of particles, but not necessarily the number of particles in each half.

This is the case of hard-core bosonic encoding where the qubits represents spatial orbitals (occupied by electron pairs) and thus the total number of (electron-pair) particles are conserved.

In case of fermionic encoding half the number of qubits represent spin up orbitals, while the other half represent spin down orbitals, and spin particle conservation must be used.

Return type:: Self

class MemoryRestrictedEstimatorCreator

Bases: object

Builder for the memory restricted estimator.

__init__() → None

Initialize a memory restricted estimator builder.

Return type:: None

choose_estimator_error_mitigator() → EstimatorErrorMitigatorSubCreator[Self]

Add an error mitigator to use with the estimation.

Return type:: EstimatorErrorMitigatorSubCreator[Self]

choose_grouper() → MeasurementGrouperSubCreator[Self]

Choose the grouper to use for the estimator.

Return type:: MeasurementGrouperSubCreator[Self]

create(*, with_shot_counter: Literal[False] = False) → MemoryRestrictedEstimator

create(*, with_shot_counter: Literal[True]) → EstimatorShotCounter

Create the configured estimator.

Parameters:: with_shot_counter (bool) – Whether to include a shot counter in the estimator. This will instead return a EstimatorShotCounter wrapped around the MemoryRestrictedEstimator.
Return type:: MemoryRestrictedEstimator | EstimatorShotCounter

with_max_memory(max_memory_usage_in_kb: int) → Self

Set the maximum allowed memory for the statevector in the estimator.

Arg:: max_memory_usage_in_kb: Maximum memory allowed by the estimator measured in kilobytes.

Parameters:: max_memory_usage_in_kb (int)
Return type:: Self

with_measurement_cache(measurement_cache: MeasurementCache) → Self

Add an cache to use with the estimator.

Parameters:: measurement_cache (MeasurementCache) – The cache to use.
Return type:: Self

with_options(options: MemoryRestrictedSimulatorOptions) → Self

Set options for the estimator to use.

Arg:: options: Options for the MemoryRestrictedEstimator to use.

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

with_precise_defaults() → Self

Set all options to a precise default version of the MemoryRestrictedEstimator.

This estimator raises a warning if the simulation can not be done accurately enough. The precise default is 1,000,000 amplitudes.

Return type:: Self

with_quick_defaults() → Self

Set all options to a quick but imprecise default version of the MemoryRestrictedEstimator.

The quick defaults are 1000 amplitudes and warnings are suppressed.

Return type:: Self

class QiskitStateVectorEstimatorCreator

Bases: object

Builder for the Qiskit state vector estimator.

static create() → QiskitStateVectorEstimator

Create an instance of QiskitStateVectorEstimator.

Return type:: QiskitStateVectorEstimator

estimator_creator() → EstimatorCreator

Start creating an estimator.

An estimator is an object capable of estimating expectation values of quantum observables with respect to the state of a quantum circuit.

Return type:: EstimatorCreator