uniqc.algorithms.core.measurement.state_tomography module

Full density-matrix state tomography via basis rotations.

class uniqc.algorithms.core.measurement.state_tomography.StateTomography(circuit, qubits=None, shots=8192)

Bases: object

Class-based interface for full quantum-state tomography.

The constructor takes a clean state-preparation circuit (no measurements); the class adds basis rotations and measurements internally.

Parameters:

• circuit (Circuit)

• qubits (list[int] | None)

• shots (int)

execute(backend='statevector', *, program_type='qasm', **kwargs)

Run tomography and return the reconstructed density matrix.

Return type:

ndarray

get_readout_circuits()

Return one circuit per Pauli measurement basis (3^n total).

Return type:

list[Circuit]

uniqc.algorithms.core.measurement.state_tomography.state_tomography(circuit, qubits=None, shots=8192)

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.algorithms.core.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.algorithms.core.measurement.state_tomography.state_tomography_example()

Tiny tomography demo on a |+⟩ state.

Return type:

ndarray

uniqc.algorithms.core.measurement.state_tomography.tomography_summary(rho, label='ρ', reference_state=None, *, print_summary=True)

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

Returns a dict with the eigenvalues, purity (\(\mathrm{Tr}(\rho^2)\)), trace, and (when reference_state is provided) the fidelity \(F(\rho, \sigma) = (\mathrm{Tr} \sqrt{\sqrt{\rho}\,\sigma\sqrt{\rho}})^2\).

Implementation is pure NumPy/SciPy (no qutip dependency).

Parameters:

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

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

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

• print_summary (bool) – If True (default) also print the formatted summary to stdout for interactive use.

Returns:

Dict with keys:

{
    "label":       str,         # the label argument
    "n_qubits":    int,
    "eigenvalues": np.ndarray,  # real, sorted descending
    "purity":      float,       # Tr(ρ²)
    "trace":       float,       # Tr(ρ)
    "is_pure":     bool,        # |purity-1| < 1e-4
    "fidelity":    float | None # F(ρ, σ) if reference given
}

Return type:

dict

Example

>>> from uniqc.circuit_builder import Circuit
>>> from uniqc.algorithms.core.measurement import (
...     state_tomography, tomography_summary
... )
>>> c = Circuit()
>>> c.h(0)
>>> c.cx(0, 1)
>>> c.measure(0); c.measure(1)
>>> rho = state_tomography(c, shots=4096)
>>> info = tomography_summary(rho)
>>> info["purity"]
0.987