EmulatorResult

class guppylang.emulator.EmulatorResult(results: list[QsysShot] | None = None, *, _circuit_extractor: CircuitExtractor | None = None, _metric_store: MetricStore | None = None)

A result from running an emulator instance.

Collects data from output("tag", val) calls in the guppy program. Includes results for all shots.

Includes conversions to traditional distributions over bitstrings if a tagging convention is used, including conversion to a pytket BackendResult.

Under this convention, tags are assumed to be a name of a bit register unless they fit the regex pattern ^([a-z][\w_]*)\[(\d+)\]$ (like my_Reg[12]) in which case they are assumed to refer to the nth element of a bit register.

For results of the form output("<register>", value), value can be {0, 1} , wherein the register is assumed to be length 1, or lists over those values, wherein the list is taken to be the value of the entire register.

For results of the form output("<register>[n]", value) value can only be {0,1}. The register is assumed to be at least n+1 in size and unset elements are assumed to be 0.

Subsequent writes to the same register/element in the same shot will overwrite.

To convert to a BackendResult all registers must be present in all shots, and register sizes cannot change between shots.

__init__(results: list[QsysShot] | None = None, *, _circuit_extractor: CircuitExtractor | None = None, _metric_store: MetricStore | None = None)

circuits() → list[Circuit]

Return pytket Circuit objects representing the stream of gates output by the user program at emulation time.

Circuits are extracted from each shot’s trace in the gateset produced by compilation, typically the primitive gateset of the hardware platform being emulated.

Enable trace collection with EmulatorInstance.with_trace() before running the emulator. pytket availability is checked before conversion.

collated_counts() → Counter[tuple[tuple[str, str], ...]]

Calculate counts of bit strings for each tag by collating across shots using QsysResult.tag_collated_shots. Each result entry per shot is seen to be appending to the bitstring for that tag.

If the result value is a list, it is flattened and appended to the bitstring.

Example

>>> shots = [QsysShot([("a", 1), ("a", 0)]), QsysShot([("a", [0, 1])])]
>>> res = QsysResult(shots)
>>> res.collated_counts()
Counter({(('a', '10'),): 1, (('a', '01'),): 1})

Raises:

ValueError – If any primitive value is a float or not in {0,1}.

collated_digitstring_counts() → Counter[tuple[tuple[str, str], ...]]

Calculate counts of digit strings for each tag by collating across shots using QsysResult.tag_collated_shots. Each result entry per shot is seen to be appending to the digitstring for that tag.

If the result value is a list, it is flattened and appended to the digitstring.

Example

>>> shots = [QsysShot([("a", 1), ("a", 2)]), QsysShot([("a", [3, 4])])]
>>> res = QsysResult(shots)
>>> res.collated_digitstring_counts()
Counter({(('a', '12'),): 1, (('a', '34'),): 1})

Raises:

ValueError – If any primitive value is a float or not in 0-9.

collated_shots() → list[dict[str, list[DataValue]]]

For each shot generate a dictionary of tags to collated data.

metrics() → list[ShotMetrics]

Return collected metrics for each emulated shot.

Metrics include gate-count and allocation statistics for the user program and the operations emitted after runtime processing.

Enable metric collection with EmulatorInstance.with_metrics() before running the emulator.

partial_state_dicts() → list[dict[str, PartialVector]]

Extract state results from shot results in to dictionaries.

Looks for outputs from state_output(“tag”, qs) calls in the guppy program.

Returns:

A list of dictionaries, each dictionary containing the tag as the key and the PartialVector as the value. Each dictionary corresponds to a shot. Repeated tags in a shot will overwrite previous values.

partial_states() → list[list[tuple[str, PartialVector]]]

Extract state results from shot results.

Looks for outputs from state_output(“tag”, qs) calls in the guppy program.

Returns:

A list (over shots) of lists. The outer list is over shots, and the inner is over the state results in that shot. Each inner list contains tuples of (string tag, PartialVector).

register_bitstrings(strict_names: bool = False, strict_lengths: bool = False) → dict[str, list[str]]

Convert results to a dictionary from register name to list of bitstrings over the shots.

Parameters:

• strict_names – Whether to enforce that all shots have the same registers.

• strict_lengths – Whether to enforce that all register bitstrings have the same length.

register_counts(strict_names: bool = False, strict_lengths: bool = False) → dict[str, Counter[str]]

Convert results to a dictionary of register counts.

Returns:

A dictionary where the keys are the register names and the values are the counts of the register bitstrings.

Return type:

dict

results: list[QsysShot]

List of QsysShot objects, each representing a single shot’s results.

to_pytket() → BackendResult

Convert results to a pytket BackendResult.

Returns:

A BackendResult object with the shots.

Return type:

BackendResult

Raises:

• ImportError – If pytket is not installed.

• ValueError – If a register’s bitstrings have different lengths or not all

• registers are present in all shots. –

traces() → list[Trace]

Return the per-shot record of instructions emitted during emulation.

Each Trace is an ordered collection of events emitted by the user program, runtime, error model, and simulator. Use its get_user_program_trace(), get_runtime_trace(), get_error_model_trace(), and get_simulator_trace() methods to inspect an individual execution stage.

Enable trace collection with EmulatorInstance.with_trace() before running the emulator.