qrunch.quantum.samplers.creators

Builder classes for creating samplers for all available samplers.

Classes

`BackendSamplerCreator`	Builder for the backend sampler.
`ExcitationGateSamplerCreator`	Builder for the excitation gate sampler.
`MemoryRestrictedSamplerCreator`	Builder for the memory restricted sampler.

class BackendSamplerCreator

Bases: object

Builder for the backend sampler.

__init__() → None

Initialize a backend sampler builder.

Return type:: None

choose_backend() → BackendSubCreator[Self]

Choose the backend to use for the sampler.

Return type:: BackendSubCreator[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) → BackendSampler

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

Create the configured sampler.

Parameters:: with_shot_counter – Whether to include a shot counter in the sampler. This will instead return a SamplerShotCounter wrapped around the BackendSampler.

with_measurement_cache(measurement_cache: MeasurementCache) → Self

Add a cache to use with the sampler.

All available MeasurementCaches can be created by using the MeasurementCacheFactory.

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

class ExcitationGateSamplerCreator

Bases: object

Builder for the excitation gate sampler.

__init__() → None

Initialize an excitation gate sampler builder.

Return type:: None

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

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

Create the configured sampler.

Parameters:: with_shot_counter – Whether to include a shot counter in the sampler. This will instead return a SamplerShotCounter wrapped around the ExcitationGateSampler.

with_eps(eps: float | None) → Self

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

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

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

Choose the float type precision used in the sampler.

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

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

Choose parallel setting to use in the sampler.

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

with_seed(seed: int | None) → Self

Choose seed to use for randomness in the sampler.

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 MemoryRestrictedSamplerCreator

Bases: object

Builder for the memory restricted sampler.

__init__() → None

Initialize a memory restricted sampler builder.

Return type:: None

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

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

Create the configured sampler.

Parameters:: with_shot_counter – Whether to include a shot counter in the sampler. This will instead return a SamplerShotCounter wrapped around the MemoryRestrictedSampler.

with_max_memory(max_memory_usage_in_kb: int) → Self

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

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

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

with_options(options: MemoryRestrictedSimulatorOptions) → Self

Set options for the sampler to use.

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

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

with_precise_defaults() → Self

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

This sampler 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 MemoryRestrictedSampler.

The quick defaults are 1000 amplitudes and warnings are suppressed.

Return type:: Self