ket.measurement¶

Quantum measurement result classes.

This module provides Measurement and Samples, the two primary result handles for collecting classical data from a quantum circuit:

Measurement stores the outcome of a single projective measurement in the computational basis.
Samples accumulates counts over many shots, producing an empirical probability distribution over basis states.

Samples class is lazy: in batch execution mode the results are deferred until the process executes, which happens automatically when .get() is accessed.

Prefer using the top-level functions measure and sample to create these objects.

Classes `ket.measurement`¶

`Measurement`	Quantum measurement result.
`Samples`	Quantum state measurement samples.

class Measurement(qubits: Quant, postprocessing: Callable[[int], Any] | None = None)¶

Quantum measurement result.

This class holds a reference for a measurement result. The result may not be available right after the measurement call, especially in batch execution.

To read the value, access the attribute value.

You can instantiate this class by calling the measure function.

Example

from ket import *

p = Process()
q = p.alloc(2)
CNOT(H(q[0]), q[1])
result = measure(q)
print(result.value)  # 0 or 3

property value: Any¶

The measurement outcome as a (possibly post-processed) value.

If a postprocessing callable was supplied at construction (e.g., for Qint conversion), it is applied to the raw integer outcome before returning.

Returns:: The post-processed measurement outcome.

property raw_value: int¶

The raw (pre-postprocessing) measurement outcome as an unsigned integer.

Returns:: The measurement result as a plain integer.

property bitstring: str¶

The measurement outcome as a zero-padded binary string.

Converts the raw integer outcome to a binary string of length len(qubits), with the most-significant bit corresponding to the first qubit in the register.

Returns:: A binary string such as '0101'.

get() → Any¶

The measurement outcome as a (possibly post-processed) value.

If a postprocessing callable was supplied at construction (e.g., for Qint conversion), it is applied to the raw integer outcome before returning.

Returns:: The post-processed measurement outcome.

class Samples(qubits: Quant, shots: int = 2048, postprocessing: Callable[[int], Any] | None = None)¶

Quantum state measurement samples.

This class holds a reference for a measurement sample result. The result may not be available right after the sample call, especially in batch execution.

To read the value, access the attribute value. If the value is not available, the measurement will return None; otherwise, it will return a dictionary mapping measurement outcomes to their respective counts.

You can instantiate this class by calling the sample function.

Example

from ket import *

p = Process()
q = p.alloc(2)
CNOT(H(q[0]), q[1])
results = sample(q)

print(results.value)
# {0: 1042, 3: 1006}

Parameters:

qubits – Qubits for which the measurement samples are obtained.
shots – Number of measurement shots (default is 2048).

property value: dict[Any, int] | None¶

The measurement sample distribution as a dictionary.

Maps each observed measurement outcome to its count over shots repetitions. If a postprocessing callable was supplied, the keys are the post-processed outcomes (e.g., signed integers for Qint).

Returns:: A {outcome: count} dictionary, or None if the result is not yet available (batch mode).

property raw_value: dict[int, int] | None¶

The raw sample distribution without postprocessing.

Returns:: A {raw_integer_outcome: count} dictionary, or None if not yet available.

property bitstring: dict[str, int] | None¶

The sample distribution with outcomes formatted as binary strings.

Each key is a zero-padded binary string of length len(qubits).

Returns:: A {'0101': count, ...} dictionary, or None if not yet available.

property probability: dict[int, float] | None¶

The sample distribution normalized to empirical probabilities.

Each value is the fraction of shots that produced the corresponding outcome, in the range [0.0, 1.0].

Returns:: A {outcome: probability} dictionary, or None if not yet available.

get() → dict[int, int]¶

Retrieve the sample distribution, executing the process if necessary.

Returns:: A {outcome: count} dictionary (with postprocessing applied if configured).

most_frequent_state(raw: bool = False) → int | Any¶

Return the most frequently observed measurement outcome.

Triggers process execution if results are not yet available.

Parameters:: raw – If True, ignores the postprocessing function and returns the raw integer state.
Returns:: The outcome that appeared most often across all shots. Ties are broken arbitrarily.

Example

from ket import *
p = Process()
q = p.alloc(2)
X(q[0]) # Prepare state |01> (decimal 1)
m = measure(q, shots=100)
print(m.most_frequent_state())

histogram(mode: Literal['bin', 'dec'] = 'dec', data: Literal['probability', 'count'] = 'count', hamiltonian: Callable[[Quant], Hamiltonian] | None = None, plot_filter: Callable[[int, float | int], bool] | None = None, categorical_x: bool | None = None, **kwargs) → Figure¶

Generate a histogram representing the sample.

This method creates a histogram visualizing the sample distribution.

Note

This method requires additional dependencies from ket-lang[plot].

Install with: pip install ket-lang[plot].

Parameters:

mode – If "bin", display the states in binary format. If "dec", display the states in decimal format. Defaults to "dec".
data – Specify whether to plot "probability" or "count". Defaults to "count".
hamiltonian – Optional function mapping a Quant to a Hamiltonian to calculate energy.
plot_filter – Optional function to filter the plotted data. Takes a state (int) and its value (probability or count, depending on the data parameter) and returns True to keep the state or False to exclude it.
categorical_x – If True, plots bars side-by-side ignoring numeric gaps. If False, spaces bars out based on their integer value. If None (default), automatically switches to categorical if the state spread is too large.
**kwargs – Additional keyword arguments passed to plotly.express.bar.

Returns:

Histogram of sample measurement.

ket.measurement¶

Classes ket.measurement¶

Classes `ket.measurement`¶