EmulatorInstance

class guppylang.emulator.EmulatorInstance(_instance: SeleneInstance, _n_qubits: int, _options: _Options = <factory>, _arg_specs: tuple[EntrypointArgSpec, ...] = ())

An emulator instance for running a compiled program.

Returned by GuppyFunctionDefinition.emulator. Contains configuration options for the emulator instance, such as the number of qubits, the number of shots, the simulator backend, and more.

__delattr__(name)

Implement delattr(self, name).

__eq__(other)

Return self==value.

__init__(_instance: SeleneInstance, _n_qubits: int, _options: _Options = <factory>, _arg_specs: tuple[EntrypointArgSpec, ...] = ()) → None

__repr__()

Return repr(self).

__setattr__(name, value)

Implement setattr(self, name, value).

coinflip_sim() → Self

Set the simulation backend to the coinflip simulator. This performs no quantum simulation, and flips a coin for each measurement.

property error_model: ErrorModel

Device error model used for the emulator instance.

property n_processes: int

Number of processes to parallelise the emulator execution across. Defaults to 1, meaning no parallelisation.

property n_qubits: int

Number of qubits available in the emulator instance.

run(**args: int | float | bool | Sequence[int] | Sequence[float] | Sequence[bool]) → EmulatorResult

Run the emulator instance and return the results.

By default runs one shot, this can be configured with with_shots().

If the entrypoint takes runtime arguments, their values must be passed as keyword arguments. Only bool, signed int, float, and arrays of those types are supported. The same values are used for every shot. For example:

main.emulator(n_qubits=2).run(theta=1.5, n=3)

To vary arguments per shot, use run_per_shot() instead.

run_per_shot(args: Sequence[Mapping[str, ArgValue]]) → EmulatorResult

Run the emulator with a different set of runtime arguments per shot.

args is a sequence with one mapping of argument values per shot, so the number of shots run is len(args). For example:

main.emulator(n_qubits=2).run_per_shot(
    [{"theta": 1.0, "n": 10}, {"theta": 2.5, "n": 20}]
)

Because each record corresponds to exactly one shot, the shot count is fixed by args. If with_shots has been set explicitly to a value that disagrees with len(args) this raises, rather than silently picking one; not calling with_shots at all is always fine.

For constant arguments shared across all shots, use run() instead.

property runtime: Runtime

Runtime used for executing the emulator instance.

property seed: int | None

Random seed for the emulator instance, if any.

property shot_increment: int

Value to increment shot numbers by for each repeated run. Defaults to 1.

property shot_offset: int

Offset for the shot numbers, shot counts will begin at this offset. Defaults to 0.

This is useful for running multiple emulator instances in parallel

property shots: int

Number of shots to run for each execution.

Defaults to 1 when unset (with_shots was never called).

property simulator: Simulator

Simulation backend used for running the emulator instance.

stabilizer_sim() → Self

Set the simulation backend to the stabilizer simulator. This only works for clifford circuits but is very fast.

statevector_sim() → Self

Set the simulation backend to the default statevector simulator.

property timeout: datetime.timedelta | None

Timeout for the emulator execution, if any.

property verbose: bool

Whether to print verbose output during the emulator execution.

with_error_model(value: ErrorModel) → Self

Set the device error model used for the emulator instance. Defaults to IdealErrorModel (no errors).

with_event_hook(value: EventHook) → Self

Set the event hook used for the emulator instance. Defaults to NoEventHook.

with_n_processes(value: int) → Self

Set the number of processes to parallelise the emulator execution across. Defaults to 1, meaning no parallelisation.

with_n_qubits(value: int) → Self

Set the number of qubits available in the emulator instance.

with_progress_bar(value: bool = True) → Self

Set whether to display a progress bar during the emulator execution. Defaults to False.

with_runtime(value: Runtime) → Self

Set the runtime used for executing the emulator instance. Defaults to SimpleRuntime.

with_seed(value: int | None) → Self

Set the random seed for the emulator instance. Defaults to None.

with_shot_increment(value: int) → Self

Set the value to increment shot numbers by for each repeated run. Defaults to 1.

with_shot_offset(value: int) → Self

Set the offset for the shot numbers, shot counts will begin at this offset. Defaults to 0.

This is useful for running multiple emulator instances in parallel.

with_shots(value: int) → Self

Set the number of shots to run for each execution. Defaults to 1.

with_simulator(value: Simulator) → Self

Set the simulation backend used for running the emulator instance. Defaults to statevector simulation.

with_timeout(value: datetime.timedelta | None) → Self

Set the timeout for the emulator execution. Defaults to None (no timeout).

with_verbose(value: bool) → Self

Set whether to print verbose output during the emulator execution. Defaults to False.