ket.measurement

Measurement classes.

This module provides classes for storing measurement results.

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. If the value is not available, the measurement will return None; otherwise, it will return an unsigned integer.

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 | None

Retrieve the measurement value if available.

property raw_value: int | None

Retrieve the measurement value if available (without postprocessing).

property bitstring: str | None

Retrieve the measurement bitstring if available.

get() → Any

Retrieve the measurement value.

If the value is not available, the quantum process will execute to get the result.

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

Retrieve the measurement samples if available.

property raw_value: dict[int, int] | None

Retrieve the measurement samples if available (without postprocessing).

property bitstring: dict[str, int] | None

Retrieve the bitstring samples if available.

property probability: dict[int, float] | None

Retrieve the measurement probabilities if available.

get() → dict[int, int]

Retrieve the measurement samples.

If the value is not available, the quantum process will execute to get the result.

most_frequent_state() → int

Retrieve the most frequent state.

If the value is not available, the quantum process will execute to get the result.

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) → go.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.