Struct StabilizerState 

pub struct StabilizerState {
    pub num_qubits: usize,
    /* private fields */
}

Stabilizer state simulator based on the Aaronson-Gottesman symplectic tableau.

Represents an n-qubit stabilizer state using 2n generator rows, each composed of an X-block and Z-block of packed u64 words, plus a phase per row.

Fields

num_qubits: usize

Number of qubits.

Implementations

impl StabilizerState

pub fn new(n: usize) -> Self

Creates a new stabilizer state initialized to |0…0⟩.

In the Aaronson-Gottesman convention the initial generators are:

• Destabilizer i (row i): X on qubit i, identity elsewhere, phase +1.
• Stabilizer i (row n+i): Z on qubit i, identity elsewhere, phase +1.

Arguments

• n — number of qubits

pub fn apply_cx( &mut self, control: usize, target: usize, ) -> Result<(), QisError>

Applies the CNOT (CX) gate with control as control and target as target.

Aaronson-Gottesman rule (Eq. 11) for each row i:

• phase[i] ^= 2 * x[i][c] * z[i][t] * (x[i][t] ^ z[i][c] ^ 1)
• x[i][t] ^= x[i][c]
• z[i][c] ^= z[i][t]

pub fn apply_swap(&mut self, q0: usize, q1: usize) -> Result<(), QisError>

Applies the SWAP gate between qubits q0 and q1.

Native rule: for each row i, swap (x[i][q0], z[i][q0]) with (x[i][q1], z[i][q1]). No phase change — SWAP maps Paulis without sign.

pub fn apply_cz(&mut self, q0: usize, q1: usize) -> Result<(), QisError>

Applies the CZ gate (controlled-Z) between q0 and q1.

Implemented as (I⊗H)·CNOT·(I⊗H) inlined per-row — no heap allocations.

pub fn apply_cy( &mut self, control: usize, target: usize, ) -> Result<(), QisError>

Applies the CY gate (controlled-Y) between control and target.

Implemented as (I⊗S)·CX·(I⊗S†) inlined per-row, i.e. in time order: S†(target) → CX(control, target) → S(target).

Derivation: Y = SXS†, so CY = (I⊗S)·CX·(I⊗S†).

pub fn num_qubits(&self) -> usize

Returns the number of qubits.

pub fn apply_h(&mut self, qubit: usize) -> Result<(), QisError>

Applies the Hadamard gate to qubit qubit.

Aaronson-Gottesman update rule for each row i (0..2n):

• phase[i] ^= 2 * x[i][qubit] & z[i][qubit] (adds 2 mod 4 when Y, i.e. sign flip)
• swap x[i][qubit] and z[i][qubit]

pub fn apply_s(&mut self, qubit: usize) -> Result<(), QisError>

Applies the S gate (phase gate, √Z) to qubit qubit.

Aaronson-Gottesman rule for each row i:

• phase[i] ^= 2 * x[i][qubit] * z[i][qubit]
• z[i][qubit] ^= x[i][qubit]

Effect: X→Y, Y→-X, Z→Z.

pub fn apply_sdg(&mut self, qubit: usize) -> Result<(), QisError>

Applies the S† gate (S-dagger, inverse phase gate) to qubit qubit.

Native rule for each row i (derived from S†: X→-Y, Y→X, Z→Z):

• phase[i] ^= 2 * x[i][qubit] * (1 - z[i][qubit]) (flip sign when X but not yet Y)
• z[i][qubit] ^= x[i][qubit]

pub fn apply_x(&mut self, qubit: usize) -> Result<(), QisError>

Applies the Pauli-X (bit-flip) gate to qubit qubit.

Effect: X→X, Y→-Y, Z→-Z. Rule per row i: phase[i] ^= 2 * z[i][qubit]. No bit changes.

pub fn apply_z(&mut self, qubit: usize) -> Result<(), QisError>

Applies the Pauli-Z (phase-flip) gate to qubit qubit.

Effect: X→-X, Y→-Y, Z→Z. Rule per row i: phase[i] ^= 2 * x[i][qubit]. No bit changes.

pub fn apply_y(&mut self, qubit: usize) -> Result<(), QisError>

Applies the Pauli-Y gate to qubit qubit.

Effect: X→-X, Y→Y, Z→-Z. Rule per row i: phase[i] ^= 2 * (x[i][qubit] XOR z[i][qubit]). No bit changes.

pub fn apply_x2p(&mut self, qubit: usize) -> Result<(), QisError>

Applies the √X gate (X2P, SX, Rx(π/2)) to qubit qubit.

Conjugation: X→X, Y→Z, Z→−Y. Rule per row i:

• phase[i] ^= 2 * (!x[i][qubit] & z[i][qubit]) (flip for Z→−Y)
• x[i][qubit] ^= z[i][qubit]

pub fn apply_x2m(&mut self, qubit: usize) -> Result<(), QisError>

Applies the √X† gate (X2M, SXdg, Rx(−π/2)) to qubit qubit.

Conjugation: X→X, Y→−Z, Z→Y. Rule per row i:

• phase[i] ^= 2 * (x[i][qubit] & z[i][qubit]) (flip for Y→−Z)
• x[i][qubit] ^= z[i][qubit]

pub fn apply_y2p(&mut self, qubit: usize) -> Result<(), QisError>

Applies the √Y gate (Y2P, SY, Ry(π/2)) to qubit qubit.

Conjugation U P U†: X→−Z, Y→Y, Z→X. Rule per row i:

• phase[i] ^= 2 * (x[i][qubit] & !z[i][qubit]) (flip for X→−Z)
• swap x[i][qubit] ↔ z[i][qubit]

pub fn apply_y2m(&mut self, qubit: usize) -> Result<(), QisError>

Applies the √Y† gate (Y2M, SYdg, Ry(−π/2)) to qubit qubit.

Conjugation U P U†: X→Z, Y→Y, Z→−X. Rule per row i:

• phase[i] ^= 2 * (!x[i][qubit] & z[i][qubit]) (flip for Z→−X)
• swap x[i][qubit] ↔ z[i][qubit]

pub fn measure(&mut self, qubit: usize) -> Result<bool, QisError>

Measures qubit qubit in the Z basis, collapsing the state.

Returns false for outcome 0 (+1 eigenvalue) and true for outcome 1 (-1 eigenvalue).

Algorithm (Aaronson-Gottesman §IV)

Random case — some stabilizer generator has X or Y on qubit qubit:

1. Find any stabilizer row p (index n..2n) with x[p][qubit] = 1.
2. XOR row p into every other row that also has x[.][qubit] = 1.
3. Move row p to its paired destabilizer row p - n.
4. Replace stabilizer row p with ±Z_qubit, where the sign is random.

Deterministic case — all stabilizers commute with Z_qubit:

1. Compute the product of destabilizer rows i (for which the paired stabilizer n+i has x[n+i][qubit] = 1) into a scratch accumulator.
2. The measurement outcome is the phase of the scratch row.

pub fn measure_all(&mut self) -> Outcome

Measures all qubits in order, returning a bit-packed Outcome.

Qubit q’s result is stored at bit q inside the Outcome. Use Outcome::is_one(q) to read it.

pub fn reset(&mut self, qubit: usize) -> Result<(), QisError>

Resets qubit to the |0⟩ state.

Implemented by measuring in the Z basis and applying X if the outcome is |1⟩. This correctly handles both deterministic and random measurement cases.

Example

use cqlib_core::qis::StabilizerState;

let mut s = StabilizerState::new(2);
s.apply_x(0).unwrap();  // |0⟩ → |1⟩
s.reset(0).unwrap();    // back to |0⟩
assert_eq!(s.probabilities().unwrap()[0], 1.0); // P(|00⟩) = 1

pub fn probability_of(&self, bits: &[bool]) -> Result<f64, QisError>

Returns the probability of measuring the given computational basis state.

Performs O(n²) work per qubit, O(n³) total, on a cloned (non-destructive) copy.

Returns

• Ok(0.0) if the bitstring is inconsistent with the stabilizer state.
• Ok(1.0 / 2.0^k) where k is the number of qubits with random outcomes, if the bitstring is in the support.
• Err(QubitMismatch) if bits.len() != n.

Example

use cqlib_core::qis::StabilizerState;

let mut s = StabilizerState::new(2);
s.apply_h(0).unwrap();
s.apply_cx(0, 1).unwrap(); // Bell state |Φ⁺⟩

// Only |00⟩ and |11⟩ are possible, each with probability 0.5
assert!((s.probability_of(&[false, false]).unwrap() - 0.5).abs() < 1e-10);
assert!((s.probability_of(&[true,  true ]).unwrap() - 0.5).abs() < 1e-10);
assert_eq!(s.probability_of(&[false, true]).unwrap(), 0.0);
assert_eq!(s.probability_of(&[true,  false]).unwrap(), 0.0);

pub fn probabilities(&self) -> Result<Vec<f64>, QisError>

Returns the full probability distribution over all computational basis states.

Returns a Vec<f64> of length 2^n where entry i is the probability of measuring the state whose binary representation is i (qubit 0 = LSB).

Limitations

Only feasible for small systems. Returns Err(InvalidParameterValue) if n > 20 (which would require a 8 MB vector and O(2^20 × n³) computation).

Example

use cqlib_core::qis::StabilizerState;

let mut s = StabilizerState::new(2);
s.apply_h(0).unwrap();
s.apply_cx(0, 1).unwrap(); // Bell state

let probs = s.probabilities().unwrap();
assert_eq!(probs.len(), 4);
assert!((probs[0b00] - 0.5).abs() < 1e-10); // |00⟩
assert_eq!(probs[0b01], 0.0);                // |10⟩ (qubit-0 is LSB)
assert_eq!(probs[0b10], 0.0);                // |01⟩
assert!((probs[0b11] - 0.5).abs() < 1e-10); // |11⟩

pub fn sample_shots(&self, shots: usize) -> Vec<Outcome>

Runs shots independent measurements in parallel using Rayon.

Returns a Vec<Outcome> of bit-packed measurement results, one per shot. Each Rayon worker thread reuses a single pre-allocated working copy of the state (via reset_from), avoiding per-shot heap allocation.

Seeds for each shot are derived sequentially from the primary RNG (ensuring reproducibility), then each shot runs on an independently-seeded clone in parallel. This produces the correct marginal distribution while being deterministic: the same initial state always yields the same joint sample set.

Example

use cqlib_core::qis::StabilizerState;
let mut s = StabilizerState::new(2);
s.apply_h(0).unwrap();
s.apply_cx(0, 1).unwrap(); // Bell state
let results = s.sample_shots(1000);
assert_eq!(results.len(), 1000);
for shot in &results { assert_eq!(shot.is_one(0), shot.is_one(1)); }

pub fn sample_shots_with_seed( &self, shots: usize, seed: Option<u64>, ) -> Vec<Outcome>

Samples using per-shot random streams independent of Rayon scheduling. With no seed, preserves the state’s existing random stream.

pub fn sample( &self, measurement: &Measurement, shots: usize, ) -> Result<ExecutionResult, QisError>

Samples the state using a circuit Measurement as the output contract.

Unlike apply_circuit, this method does not read or execute the circuit IR. The Measurement already carries the qubits and their result bit order:

• measurement.qubits()[i] becomes bit i in each Outcome.
• Outcome::to_bitstring displays the most-significant result bit first, so string order is the reverse of measurement.qubits().

Example

use cqlib_core::circuit::{Circuit, Qubit};
use cqlib_core::qis::StabilizerState;

let mut c = Circuit::new(2);
c.h(Qubit::new(0)).unwrap();
c.cx(Qubit::new(0), Qubit::new(1)).unwrap();
let out = c.measure_bits([Qubit::new(1), Qubit::new(0)]).unwrap();

// `from_circuit` ignores terminal measurements and keeps the Bell state.
let state = StabilizerState::from_circuit(&c).unwrap();
let result = state.sample(&out, 1000).unwrap();

assert_eq!(result.shots(), 1000);
assert!(result
    .counts()
    .keys()
    .all(|bits| bits.to_bitstring(out.width()) == "00"
        || bits.to_bitstring(out.width()) == "11"));

pub fn sample_with_seed( &self, measurement: &Measurement, shots: usize, seed: Option<u64>, ) -> Result<ExecutionResult, QisError>

Projects seeded full-state samples onto the requested measurement.

pub fn probs( &self, measurement: &Measurement, ) -> Result<HashMap<Outcome, f64>, QisError>

Returns the probability distribution selected by a circuit Measurement.

This is a marginal distribution over measurement.qubits(), not the full 2^n state distribution. The returned Outcome keys use the same bit order as sample.

v1 intentionally reuses probabilities, so it has the same n <= 20 limit. Use sample for larger states.

pub fn from_circuit(circuit: &Circuit) -> Result<Self, QisError>

Constructs a StabilizerState by simulating a Clifford circuit.

This state-level entry point only performs quantum state evolution. Terminal measurement and store operations produced by Circuit::measure* are treated as output declarations and ignored here: they do not collapse the state and do not populate runtime classical data.

Use sample or probs with the returned Measurement to query measurement distributions from the final state. Use run_circuit when you need execution semantics where measurements collapse the state and write classical data.

Supported instructions

• Gates: I, H, X, Y, Z, S, SDG, X2P, X2M, Y2P, Y2M, CX, CY, CZ, SWAP
• Classical data: MeasureBit, MeasureBits, Store are ignored
• Directives: Reset (returns qubit to |0⟩), Barrier/Delay (no-op)

Example

use cqlib_core::circuit::{Circuit, Qubit};
use cqlib_core::qis::StabilizerState;

let mut c = Circuit::new(2);
c.h(Qubit::new(0)).unwrap();
c.cx(Qubit::new(0), Qubit::new(1)).unwrap();
let out = c
    .measure_bits([Qubit::new(1), Qubit::new(0)])
    .unwrap();

// The measurement above is an output declaration for state sampling.
// It does not collapse the Bell state during `from_circuit`.
let stab = StabilizerState::from_circuit(&c).unwrap();
let probs = stab.probs(&out).unwrap();
assert!((probs.values().sum::<f64>() - 1.0).abs() < 1e-10);

pub fn apply_circuit(&mut self, input_circuit: &Circuit) -> Result<(), QisError>

Applies a Clifford circuit to this stabilizer state in-place.

Once bound to circuit qubit IDs, subsequent circuits must have the same IDs in the same order. The mapping is committed only on success; gates completed before an error are not rolled back.

As in from_circuit, terminal measurements are ignored. A measured qubit used by a later gate or Reset is rejected before the state is changed. Independent gates, repeated measurements, Barrier, Delay, and Store are allowed.

This state-level entry point ignores terminal measurement declarations, matching from_circuit. Use run_circuit when runtime classical measurement values are required.

pub fn run_circuit( circuit: &Circuit, ) -> Result<CircuitExecutionResult, QisError>

Executes a Clifford circuit and returns both the final state and runtime classical data.

Returns a CircuitExecutionResult containing:

• state: the final StabilizerState after all operations
• classical: measurement results and mutable variables indexed by crate::circuit::ClassicalValue and crate::circuit::ClassicalVar

Supported instructions

Same quantum gates as from_circuit. Unlike from_circuit, this method executes MeasureBit, MeasureBits, and Store: measurements collapse the state immediately and write runtime classical data. Control-flow gates are not supported.

Example

use cqlib_core::circuit::{Circuit, ClassicalExpr, ClassicalType, Qubit};
use cqlib_core::qis::{RuntimeValue, StabilizerState};

let mut c = Circuit::new(1);
c.x(Qubit::new(0)).unwrap();

// `measure` creates an immutable runtime value.
let measured = c.measure(Qubit::new(0)).unwrap();

// `store` can copy or transform measured values into mutable variables.
let flag = c.var(ClassicalType::Bool);
c.store(flag, ClassicalExpr::bit_to_bool(measured.expr()).unwrap()).unwrap();

let result = StabilizerState::run_circuit(&c).unwrap();
assert_eq!(result.classical.value(measured.value()), Some(&RuntimeValue::Bit(true)));
assert_eq!(result.classical.var(flag), Some(&RuntimeValue::Bool(true)));

pub fn apply_standard_gate( &mut self, gate: StandardGate, qubits: &[usize], params: &[f64], ) -> Result<(), QisError>

Applies a standard gate to the stabilizer tableau.

Returns QisError::NonCliffordGate for gates outside the Clifford set.

pub fn get_stabilizers(&self) -> Vec<PauliString>

There are n stabilizer generators (rows n..2n).

pub fn get_destabilizers(&self) -> Vec<PauliString>

Returns the destabilizer generators as PauliStrings.

pub fn pauli_expectation(&self, pauli: &PauliString) -> Result<i32, QisError>

Returns the expectation value ⟨ψ|P|ψ⟩ for a Pauli string pauli.

Uses GF(2) Gaussian elimination over the symplectic representation of the stabilizer generators to determine whether pauli is in the stabilizer group (expectation +1), the negative stabilizer group (expectation -1), or neither (expectation 0).

This correctly handles products of generators, not just individual generators.

pub fn to_stim_format(&self) -> String

Exports the stabilizer tableau in Stim-compatible text format.

Trait Implementations

impl Clone for StabilizerState

fn clone(&self) -> Self

O(n²) deep copy — clones the flat tableau, phases, and RNG state.

The RNG is cloned (not re-seeded) so that parallel samples produced from independent clones diverge deterministically from the same seed, which is required for reproducible multi-shot sampling with Rayon.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StabilizerState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.