qilisdk.readout.readout_result

Attributes

`NORMALIZATION_TOLERANCE`
`C`
`S`
`E`
`T`

Classes

`ReadoutResult`	Abstract base class for a single readout result.
`SamplingReadoutResult`	Result produced by a `SamplingReadout`.
`ExpectationReadoutResult`	Result produced by an `ExpectationReadout`.
`StateTomographyReadoutResult`	Result produced by a `StateTomographyReadout`.
`ReadoutCompositeResults`	Aggregated container for readout results from a single execution step.

Functions

`has_sampling`(→ TypeGuard[_HasSampling])	Return `True` if the composite contains a sampling result.
`has_expectation_values`(→ TypeGuard[_HasExpectation])	Return `True` if the composite contains an expectation-value result.
`has_state_tomography`(→ TypeGuard[_HasStateTomography])	Return `True` if the composite contains a state-tomography result.

Module Contents

NORMALIZATION_TOLERANCE = 1e-08[source]

C[source]

class ReadoutResult[source]

Bases: qilisdk.core.result.Result, Generic[C]

Abstract base class for a single readout result.

Every concrete subclass must expose a readout property that returns the ReadoutMethod configuration used to produce the result.

class SamplingReadoutResult(samples: dict[str, int], probabilities: dict[str, float] | None = None)[source]

Bases: ReadoutResult[qilisdk.readout.readout.SamplingReadout]

Result produced by a SamplingReadout.

Holds bitstring measurement counts and the corresponding probability distribution. The object can be constructed in two ways:

From explicit samples (and optionally probabilities).
From a quantum state, in which case samples are drawn stochastically according to the state amplitudes.

Parameters:

readout (SamplingReadout) – The readout configuration that produced this result.
samples (dict[str, int] | None) – Mapping of bitstring to measurement count. Mutually exclusive with state.
probabilities (dict[str, float] | None) – Pre-computed probability distribution. If omitted when samples is given, it is derived from the counts.
state (QTensor | None) – Quantum state from which to derive samples and probabilities. Mutually exclusive with samples.

Raises:

ValueError – If neither samples/probabilities nor state is provided.

classmethod from_samples(samples: dict[str, int], qubits_to_measure: list[int] | None = None, nqubits: int | None = None, expand_samples: bool | None = None) → Self[source]

Construct a SamplingReadoutResult from raw samples.

Parameters:

samples (dict[str, int]) – Mapping of bitstring to measurement count.
qubits_to_measure (list[int] | None) – Optional list of qubit indices that were measured.
nqubits (int | None) – Total number of qubits in the system.
expand_samples (bool | None) – Whether to expand samples with placeholders for unmeasured qubits.

Returns:

The constructed result object.

Return type:

SamplingReadoutResult

Raises:

ValueError – If samples are not provided.
ValueError – If not all bitstring keys have the same length.
ValueError – If qubits_to_measure is provided and has more qubits than are present in the bitstrings.

classmethod from_state(sampling_readout: qilisdk.readout.readout.SamplingReadout, state: qilisdk.core.QTensor, qubits_to_measure: list[int] | None = None, expand_samples: bool = True) → Self[source]

property samples: dict[str, int][source]

Mapping of measured bitstring to count.

Type:: dict[str, int]

property probabilities: dict[str, float][source]

Estimated probability distribution over bitstrings.

Returns:: Mapping of bitstring to probability.
Return type:: dict[str, float]

get_probability(bitstring: str) → float[source]

Return the probability for a single bitstring.

Parameters:: bitstring (str) – The bitstring to look up (e.g. "010").
Returns:: The probability associated with bitstring, or 0.0 if it was not observed.
Return type:: float

get_probabilities(n: int | None = None) → list[tuple[str, float]][source]

Return the most probable bitstrings in descending order.

Parameters:: n (int | None) – Maximum number of entries to return. None (the default) returns all outcomes.
Returns:: Up to n (bitstring, probability) pairs sorted by probability in descending order.
Return type:: list[tuple[str, float]]

class ExpectationReadoutResult(expectation_values: list[float], nshots: int | None = None)[source]

Bases: ReadoutResult[qilisdk.readout.readout.ExpectationReadout]

Result produced by an ExpectationReadout.

Contains the computed expectation values for each observable specified in the readout configuration. The object can be constructed in two ways:

From pre-computed expectation_values.
From a quantum state, in which case the expectation values are derived via expect_val().

Parameters:

readout (ExpectationReadout) – The readout configuration that produced this result.
expectation_values (list[Number] | None) – Pre-computed expectation values, one per observable. Mutually exclusive with state.
state (QTensor | None) – Quantum state used to compute expectation values on-the-fly. Mutually exclusive with expectation_values.

Raises:

ValueError – If neither expectation_values nor state is provided.

classmethod from_expectations(expectation_values: list[float], nshots: int | None = None) → Self[source]

classmethod from_state(expectation_readout: qilisdk.readout.readout.ExpectationReadout, state: qilisdk.core.QTensor) → Self[source]

property expectation_values: list[float][source]

Expectation values, one per observable, in the same order as specified in the readout.

Type:: list[Number]

class StateTomographyReadoutResult(state: qilisdk.core.QTensor)[source]

Bases: ReadoutResult[qilisdk.readout.readout.StateTomographyReadout]

Result produced by a StateTomographyReadout.

Contains the full quantum state after execution and, optionally, the computational-basis probability distribution derived from it.

Parameters:

readout (StateTomographyReadout) – The readout configuration that produced this result.
state (QTensor) – The reconstructed quantum state (ket or density matrix).

classmethod from_state(state: qilisdk.core.QTensor) → Self[source]

property state: qilisdk.core.QTensor[source]

The reconstructed quantum state (ket or density matrix).

Type:: QTensor

property probabilities: dict[str, float][source]

Computational-basis probability distribution derived from the state.

Returns:: Mapping of bitstring to probability.
Return type:: dict[str, float]

get_probability(bitstring: str) → float[source]

Return the probability for a single bitstring.

Parameters:: bitstring (str) – The bitstring to look up (e.g. "010").
Returns:: The probability associated with bitstring, or 0.0 if it was not observed.
Return type:: float

get_probabilities(n: int | None = None) → list[tuple[str, float]][source]

Return the most probable bitstrings in descending order.

Parameters:: n (int | None) – Maximum number of entries to return. None (the default) returns all outcomes.
Returns:: Up to n (bitstring, probability) pairs sorted by probability in descending order.
Return type:: list[tuple[str, float]]

S[source]

E[source]

T[source]

has_sampling(obj: ReadoutCompositeResults) → TypeGuard[_HasSampling][source]: Return True if the composite contains a sampling result.

has_expectation_values(obj: ReadoutCompositeResults) → TypeGuard[_HasExpectation][source]: Return True if the composite contains an expectation-value result.

has_state_tomography(obj: ReadoutCompositeResults) → TypeGuard[_HasStateTomography][source]: Return True if the composite contains a state-tomography result.

class ReadoutCompositeResults[source]

Bases: qilisdk.core.result.Result, Generic[S, E, T]

Aggregated container for readout results from a single execution step.

This class is returned internally by the backend and is accessible via FunctionalResult.readout_results. Most users should access results through the convenience properties on FunctionalResult instead.

The three type parameters S, E, T encode at the type level which readout results are present and correspond to the readout types declared in the Readout:

S is SamplingReadoutResult or None
E is ExpectationReadoutResult or None
T is StateTomographyReadoutResult or None

When the concrete type parameter is the result class (not None), the corresponding field is guaranteed to be populated and the type checker can verify access without runtime guards.

sampling: S = None[source]

expectation_values: E = None[source]

state_tomography: T = None[source]

classmethod from_list(results: list) → ReadoutCompositeResults[source]

Construct a ReadoutCompositeResults from a flat list of readout results.

Each element is matched by type to the appropriate field.

Parameters:: results (list) – A list containing any combination of SamplingReadoutResult, ExpectationReadoutResult, and StateTomographyReadoutResult instances.
Returns:: The constructed result container.
Return type:: ReadoutCompositeResults

classmethod from_dict(data: dict) → ReadoutCompositeResults[source]

Construct a ReadoutCompositeResults from a plain dictionary.

Parameters:: data (dict) – Mapping with optional keys "sampling", "expectation_values", and "state_tomography".
Returns:: The constructed result container.
Return type:: ReadoutCompositeResults
Raises:: TypeError – If any provided value has the wrong type.

get_samples() → dict[str, int][source]

get_samples() → Never

Return the sampling results as a bitstring-to-count mapping.

Returns:: Mapping of measured bitstring to count.
Return type:: dict[str, int]
Raises:: ValueError – If no sampling results are present.

get_probabilities() → dict[str, float][source]

get_probabilities() → Never

Return the probability distribution as a bitstring-to-probability mapping.

Returns:: Mapping of bitstring to probability.
Return type:: dict[str, float]
Raises:: ValueError – If no sampling or state-tomography results are present.

get_expectation_values() → list[float][source]

get_expectation_values() → Never

Return the expectation values as a list of numbers.

Returns:: Expectation values, one per observable, in the same order as specified in the readout.
Return type:: list[float]
Raises:: ValueError – If no expectation-value results are present.

get_state() → qilisdk.core.QTensor[source]

get_state() → Never

Return the reconstructed quantum state.

Returns:: The reconstructed quantum state (ket or density matrix).
Return type:: QTensor
Raises:: ValueError – If no state-tomography results are present.