qpandalite.algorithmics package#

Subpackages#

Submodules#

qpandalite.algorithmics.measurement module#

Measurement module for quantum state characterization.

qpandalite.algorithmics.measurement.basis_rotation_measurement(circuit, qubits=None, basis=None, shots=None)[源代码]

Measure a circuit by applying basis-rotation gates and then measuring in the computational (Z) basis.

For each qubit, the rotation applied before measurement is determined by the corresponding entry in basis:

``"Z"``: no rotation (Z basis, default)

``"X"``: Hadamard gate (H) → measures X basis

``"Y"``: S^dagger H → measures Y basis

``"I"``: no rotation (Z basis, identity)

When shots is None, the statevector simulator is used to return the exact probability distribution. When shots is given, the distribution is estimated from that many samples.

参数:

circuit (Circuit) -- Quantum circuit (must contain MEASURE instructions).
qubits (List[int] | None) -- Indices of qubits to include. None means all qubits.
basis (str | List[str] | None) --
Per-qubit measurement basis. Can be:
- A single string such as "XYZ" (applied left-to-right to qubits), where each character is "I", "X", "Y", or "Z".
- A list of strings such as ["X", "Y", "Z"].
- None (default), which means all qubits use the Z basis.
shots (int | None) -- Number of measurement shots. None returns the exact probability vector from the statevector simulator.

返回:

a dict mapping each computational-basis: outcome string (e.g. "01") to its probability.

If shots is given: a dict mapping outcome strings to integer counts (frequency).

返回类型:

If shots is None

抛出:

ValueError -- len(basis) does not match len(qubits).
ValueError -- shots is not a positive integer.
ValueError -- basis contains invalid characters.

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.measurement import basis_rotation_measurement
>>> c = Circuit()
>>> c.h(0)           # |0⟩ → (|0⟩+|1⟩)/√2
>>> c.cx(0, 1)       # Bell state (|00⟩+|11⟩)/√2
>>> c.measure(0, 1)
>>> # Measure qubit 0 in X basis, qubit 1 in Z basis
>>> probs = basis_rotation_measurement(c, basis="XZ")
>>> abs(probs["00"] - 0.5) < 1e-6   # P(0) in X basis for |+⟩ is 0.5
True

qpandalite.algorithmics.measurement.classical_shadow(circuit, qubits=None, shots=4096, n_shadow=None)[源代码]

Generate classical-shadow snapshots of a quantum state.

Each snapshot is obtained by:

For each qubit, choosing uniformly at random one of the three single-qubit Cliffords {I, H, S·H} — corresponding to measurement in the Z, X, or Y basis.
Injecting the corresponding gates before the existing MEASURE instructions in the circuit QASM.
Simulating the modified circuit once and recording the computational-basis outcomes.
Storing (unitary_indices, outcomes) as one snapshot.

The collection of snapshots enables estimating the expectation value of any Pauli string via shadow_expectation() with sample complexity \(O(\log M / ε^2)\) for M observables.

参数:

circuit (Circuit) -- Quantum circuit (must already contain MEASURE instructions).
qubits (List[int] | None) -- Indices of qubits to include. None means all qubits used by the circuit.
shots (int) -- Number of simulated measurement shots per snapshot. Higher shots reduce per-snapshot variance but are slower.
n_shadow (int | None) -- Number of independent shadow snapshots. None auto-computes as 2 * n * log(2/δ) with δ = 0.01. This bound guarantees fidelity error ≤ ε with high probability for up to M = exp(ε² n / 10) observables.

返回:

List of ShadowSnapshot objects.

抛出:

ValueError -- shots or n_shadow is not a positive integer.

返回类型:

List[ShadowSnapshot]

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.measurement import (
...     classical_shadow, shadow_expectation
... )
>>> c = Circuit()
>>> c.h(0)
>>> c.cx(0, 1)
>>> c.measure(0, 1)
>>> shadows = classical_shadow(c, shots=1024, n_shadow=32)
>>> est_ZZ = shadow_expectation(shadows, "ZZ")
>>> abs(est_ZZ - 1.0) < 0.1
True

qpandalite.algorithmics.measurement.pauli_expectation(circuit, pauli_string, shots=None)[源代码]

Measure the expectation value of a Pauli string on a circuit.

For each qubit i, the measurement basis is determined by pauli_string[i]:

'I': trace out (identity, contributes trivially)
'Z': measure in the computational (Z) basis — no rotation needed
'X': apply Hadamard before Z measurement
'Y': apply Sdag then Hadamard before Z measurement

When shots is None, the statevector simulator is used to compute the exact expectation analytically. When shots is given, the circuit is simulated shots times and the empirical frequency is used.

参数:

circuit (Circuit) -- Quantum circuit. Must contain only gates supported by QASM_Simulator and end with measurement instructions.
pauli_string (str) -- Case-insensitive Pauli string (e.g. "XYZ", "IZI"). Characters must be I, X, Y, or Z.
shots (int | None) -- Number of measurement shots. None uses statevector mode for the exact analytical value.

返回:

Expectation value ⟨psi|P|psi⟩ as a float in the interval [-1, 1].

抛出:

ValueError -- pauli_string contains invalid characters or its length does not match the number of qubits in circuit.
ValueError -- shots is not a positive integer.

返回类型:

float

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.measurement import pauli_expectation
>>> c = Circuit()
>>> c.h(0)
>>> c.cx(0, 1)          # Bell state (|00⟩+|11⟩)/√2
>>> c.measure(0, 1)
>>> pauli_expectation(c, "ZZ", shots=None)   # exact: 1.0
1.0
>>> abs(pauli_expectation(c, "ZZ", shots=10000) - 1.0) < 0.1
True

qpandalite.algorithmics.measurement.shadow_expectation(shadows, pauli_string)[源代码]

Estimate the expectation value of a Pauli string from classical-shadow snapshots.

Computes the mean of single-snapshot HKP estimators. For a single observable the mean is optimal; median-of-means buys robustness only when estimating many Paulis with uniform tail-bound guarantees.

For each snapshot the single-qubit estimator is (Huang-Kueng-Preskill, single-qubit Clifford shadow inverse channel M^{-1}(X) = 3X - I):

s_i = 1 if Pauli_i = I s_i = 3 * (-1)^outcome_i if Pauli_i ≠ I and aligned with measured basis s_i = 0 if Pauli_i ≠ I and misaligned with measured basis

The n-qubit estimator is the product \(\hat{P}=\prod_i s_i\).

参数:

shadows (List[ShadowSnapshot]) -- List of ShadowSnapshot from classical_shadow().
pauli_string (str) -- Case-insensitive Pauli string (e.g. "XYZ", "IZI").

返回:

Estimated expectation value <P>.

抛出:

ValueError -- pauli_string length does not match snapshot size.
ValueError -- pauli_string contains invalid characters.

返回类型:

float

示例

>>> shadows = classical_shadow(circuit, shots=1024, n_shadow=32)
>>> shadow_expectation(shadows, "ZZ")   # estimate <ZZ>

qpandalite.algorithmics.measurement.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.

参数:

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.

返回:

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

抛出:

ValueError -- shots is not a positive integer.
ValueError -- len(qubits) is zero or exceeds the circuit qubit count.

返回类型:

ndarray

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.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

qpandalite.algorithmics.measurement.tomography_summary(rho, label='ρ', reference_state=None)[源代码]

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\).

参数:

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.

返回类型:

None

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.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)

Module contents#

Algorithmics module — reusable quantum algorithm components.