qilisdk.readout.readout_spec

Classes

Readout

Type-safe specification of which readout methods to apply during execution.

Module Contents

class Readout

Bases: Generic[qilisdk.readout.readout_result.S, qilisdk.readout.readout_result.E, qilisdk.readout.readout_result.T]

Type-safe specification of which readout methods to apply during execution.

Readout is the primary interface for declaring what information to extract from the quantum backend after execution. Build a specification by chaining with_* builder methods, then pass it to execute().

Each with_* method returns a new Readout whose type parameters encode which readout slots are populated, allowing the type checker to verify result access at compile time. The original instance is not mutated.

Type parameters:

S: SamplingReadoutResult when with_sampling() was called, None

otherwise.

E: ExpectationReadoutResult when with_expectation() was called,

None otherwise.

T: StateTomographyReadoutResult when with_state_tomography() was

called, None otherwise.

Exemples

Sampling — measure in the computational basis and collect bitstring counts:

spec = Readout().with_sampling(nshots=1000)
result = backend.execute(functional, readout=spec)
counts = result.samples  # dict[str, int]
probs = result.probabilities  # dict[str, float]

Expectation values — compute <psi|O|psi> for one or more observables:

from qilisdk.analog import Z

spec = Readout().with_expectation(observables=[Z(0)], nshots=0)
result = backend.execute(functional, readout=spec)
ev = result.expectation_values  # list[float], one entry per observable

State tomography — retrieve the full quantum state vector after execution:

spec = Readout().with_state_tomography()
result = backend.execute(functional, readout=spec)
state = result.state  # QTensor

Multiple readout types can be combined in a single specification:

from qilisdk.analog import Z

spec = Readout().with_sampling(nshots=500).with_expectation(observables=[Z(0)])
result = backend.execute(functional, readout=spec)
counts = result.samples  # dict[str, int]
ev = result.expectation_values  # list[float]

with_sampling(nshots: int = 1000, expand_samples: bool = True) → Readout[qilisdk.readout.readout_result.SamplingReadoutResult, qilisdk.readout.readout_result.E, qilisdk.readout.readout_result.T]

Add a sampling readout to the specification.

If expand_samples is True, partial samples will be displayed with underscores for better readability. For example, «00_0» instead of «000» for a 4-qubit system where the third qubit’s state is not measured. Setting this to false can cause ambiguity, especially if you have a variety of mid-circuit measurements.

Paràmetres:

• nshots (int) – Number of measurement shots. Must be >= 0.

• expand_samples (bool) – Whether to display partial samples as «00_0» instead of «000» for better readability.

Retorna:

A new Readout with the sampling slot populated.

Llença:

ValueError – If a sampling readout was already set.

with_expectation(observables: list[qilisdk.analog.Hamiltonian | qilisdk.core.QTensor], nshots: int = 0) → Readout[qilisdk.readout.readout_result.S, qilisdk.readout.readout_result.ExpectationReadoutResult, qilisdk.readout.readout_result.T]

Add an expectation-value readout to the specification.

Paràmetres:

• observables (list[Hamiltonian | QTensor]) – Observables whose expectation values will be evaluated.

• nshots (int) – Number of measurement shots. Use 0 for exact (state-vector-based) evaluation.

Retorna:

A new Readout with the expectation slot populated.

Llença:

ValueError – If an expectation readout was already set.

with_state_tomography(method: Literal['exact'] = 'exact') → Readout[qilisdk.readout.readout_result.S, qilisdk.readout.readout_result.E, qilisdk.readout.readout_result.StateTomographyReadoutResult]

Add a state-tomography readout to the specification.

Paràmetres:

method (Literal) – Tomography method identifier. Currently only “exact” is supported.

Retorna:

A new Readout with the state-tomography slot populated.

Llença:

ValueError – If a state-tomography readout was already set.

property sampling: qilisdk.readout.readout.SamplingReadout | None

The sampling readout, or None if not set.

property expectation: qilisdk.readout.readout.ExpectationReadout | None

The expectation-value readout, or None if not set.

property state_tomography: qilisdk.readout.readout.StateTomographyReadout | None

The state-tomography readout, or None if not set.

to_list() → list[qilisdk.readout.readout.ReadoutMethod]

Return the readout methods as a flat list.

Useful for backward compatibility with APIs that accept list[ReadoutMethod].