uniqc.algorithmics.measurement.state_tomography module#

Full density-matrix state tomography via basis rotations.

uniqc.algorithmics.measurement.state_tomography.state_tomography(circuit, qubits=None, shots=8192)[source]#

Reconstruct the density matrix of a quantum state via complete tomography.

The method measures the circuit in all 3^n combinations of the single-qubit bases (X, Y, Z), then uses linear inversion over the Pauli basis to reconstruct the d × d density matrix, where d = 2^n and n is the number of qubits being tomographied.

Parameters:

  • circuit (Circuit) – Quantum circuit (must already contain MEASURE instructions).

  • qubits (List[int] | None) – Indices of qubits to include in the tomography. None means all qubits used by the circuit, in their natural order.

  • shots (int) – Number of measurement shots per basis setting. Higher shots reduce statistical noise in the reconstruction.

Returns:

A (d, d) NumPy complex array representing the reconstructed density matrix ρ, where d = 2**len(qubits). The matrix is always Hermitian (ρ = ρ†) and normalised (Tr(ρ) = 1).

Raises:

  • ValueError – shots is not a positive integer.

  • ValueError – len(qubits) is zero or exceeds the circuit qubit count.

Return type:

ndarray

Example

>>> from uniqc.circuit_builder import Circuit
>>> from uniqc.algorithmics.measurement import state_tomography
>>> c = Circuit()
>>> c.h(0)           # |0⟩ → (|0⟩+|1⟩)/√2
>>> c.cx(0, 1)       # Bell state (|00⟩+|11⟩)/√2
>>> c.measure(0, 1)
>>> rho = state_tomography(c, shots=4096)
>>> rho.shape
(4, 4)
>>> abs(rho[0, 0])   # ≈ 0.5 (population of |00⟩)
0.5
uniqc.algorithmics.measurement.state_tomography.tomography_summary(rho, label='ρ', reference_state=None)[source]#

Print a human-readable summary of a density matrix tomography result.

Shows eigenvalues, purity (:math:` mathrm{Tr}( rho^2)`), trace, and, if reference_state is provided, the fidelity \(F( rho, \sigma) = ( mathrm{Tr}sqrt{sqrt{ rho}\sigmasqrt{ rho}})^2\).

Parameters:

  • rho (ndarray) – Density matrix from state_tomography().

  • label (str) – Label to print alongside the matrix (e.g. "ρ").

  • reference_state (ndarray | None) – Optional reference density matrix for fidelity computation. If None the fidelity is skipped.

Return type:

None

Example

>>> from uniqc.circuit_builder import Circuit
>>> from uniqc.algorithmics.measurement import (
...     state_tomography, tomography_summary
... )
>>> c = Circuit()
>>> c.h(0)
>>> c.cx(0, 1)
>>> c.measure(0, 1)
>>> rho = state_tomography(c, shots=4096)
>>> tomography_summary(rho)