ket.quantumstate

Quantum state snapshot representation and visualization.

This module provides QuantumState, which captures a complete snapshot of the quantum state from a simulator at a given point in the circuit. The snapshot stores the full probability-amplitude dictionary \(\{|x\rangle : \alpha_x\}\) and exposes utilities for:

• Retrieving amplitudes and probabilities (states, probability).

• Simulating measurement shots from the snapshot (sample).

• Pretty-printing the state in plain text or LaTeX (show).

• Visualizing a single-qubit state on the Bloch sphere (sphere).

• Plotting the probability distribution as an interactive histogram (histogram).

Visualization methods require the optional ket-lang[plot] extras:

pip install ket-lang[plot]

Classes ket.quantumstate

QuantumState

A snapshot of the full quantum state obtained from a simulator.

class QuantumState(*qubits: Quant)

A snapshot of the full quantum state obtained from a simulator.

Captures the probability amplitudes of the current quantum state at the point dump is called. The state is stored as a sparse dictionary mapping non-zero basis state integers to their complex amplitudes.

Note

This class is available only with simulators. It cannot be used with real quantum hardware.

Note

Do not instantiate this class directly. Use dump instead.

Example

from ket import *

p = Process()
q = p.alloc(3)

H(q[0])
CNOT(q[0], q[1])   # GHZ-like partial entanglement

state = dump(q)
print(state.show())
# |000⟩     (50.00%)
# |110⟩     (50.00%)

Parameters:

*qubits – One or more qubit registers to capture. Registers are labeled independently in the output of show.

property states: dict[int, complex]

The quantum state as a sparse amplitude dictionary.

Maps each basis state (an integer whose binary representation gives the qubit values, with the first qubit as the most-significant bit) to its complex probability amplitude.

Returns:

The amplitude dictionary.

Example

from ket import *

p = Process()
q = p.alloc(2)

CNOT(H(q[0]), q[1])    # Bell state

state = dump(q)
print(state.states)
# {0: (0.7071+0j), 3: (0.7071+0j)}

get() → dict[int, complex]

Retrieve the quantum state, executing the process if necessary.

Returns:

The amplitude dictionary (same as states).

property probability: dict[int, float]

Measurement probabilities derived from the quantum state amplitudes.

Maps each basis state to its Born-rule probability \(|\alpha_x|^2\).

Returns:

A {basis_state: probability} dictionary where probabilities sum to approximately 1.0.

sample(shots=4096, seed=None) → dict[int, int]

Simulate measurement sampling directly from the state snapshot.

Generates shots measurement outcomes by weighted random sampling from the probability distribution defined by the stored amplitudes. This is deterministic given the same seed and is faster than re-running the circuit.

Parameters:

• shots – Number of measurement shots to simulate. Defaults to 4096.

• seed – Seed for the random number generator for reproducible results. Defaults to None (random seed).

Returns:

A {basis_state: count} dictionary, or None if the snapshot is not yet available.

Example

from ket import *

p = Process()
q = p.alloc(2)
CNOT(H(q[0]), q[1])    # Bell state

state = dump(q)
counts = state.sample(shots=1000, seed=42)
print(counts)
# {0: 503, 3: 497}

sphere() → Figure

Generate an interactive Bloch sphere plot for a single-qubit state.

Computes the Bloch vector \((\langle X \rangle, \langle Y \rangle, \langle Z \rangle)\) from the state snapshot and renders it as a 3-D Plotly figure with the standard basis labels.

Note

Requires the optional ket-lang[plot] extras:

pip install ket-lang[plot]

Returns:

An interactive 3-D Bloch sphere visualization of the current single-qubit state.

Raises:

ValueError – If the snapshot contains more than 1 qubit.

show(mode: Literal['latex', 'str'] | None = None, polar: bool = False, round_tol: float = 1e-06) → str

Format the quantum state as a human-readable string or LaTeX expression.

Renders each non-negligible basis state with its probability amplitude in Dirac notation (ket notation). In a Jupyter Notebook, the default output is a rendered LaTeX expression; in a terminal it is plain text.

Parameters:

• mode – Output format. 'str' produces a plain-text string; 'latex' produces an Math object for Jupyter rendering. Defaults to 'latex' in notebooks, 'str' otherwise.

• polar – If True, display amplitudes in polar form \(r \cdot e^{i\theta}\). Defaults to False (Cartesian form).

• round_tol – Amplitudes with absolute value below this threshold are considered zero and omitted. Defaults to 1e-6.

Returns:

The formatted state string, or a LaTeX Math object when in a notebook.

Example

from ket import *

p = Process()
q = p.alloc(2)
CNOT(H(q[0]), q[1])   # Bell state

state = dump(q)
print(state.show(mode='str'))
# |00⟩  (50.00%)
#  0.707107        ≅   1/√2
# |11⟩  (50.00%)
#  0.707107        ≅   1/√2

histogram(mode: Literal['bin', 'dec'] = 'dec', **kwargs) → Figure

Generate a histogram representing the quantum state.

This method creates a histogram visualizing the probability distribution of the quantum state.

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".

• **kwargs – Additional keyword arguments passed to plotly.express.bar.

Returns:

Histogram of the quantum state.