Struct OutcomeCompleteSimulation 

pub struct OutcomeCompleteSimulation { /* private fields */ }

Asymptotically efficient stabilizer simulation tracking all measurement outcomes.

Instead of running separate simulations for each possible measurement outcome, this simulator tracks all 2^n_random outcome branches simultaneously where n_random is the number of random measurements. This admits an asymptotic improvement over outcome-specific simulation for many use cases.

Use Cases

• Exhaustive enumeration: Compute quantities over all possible outcomes
• Exact probability distributions: Calculate measurement statistics without sampling
• Circuit verification: Analyze complete behavior across all measurement branches
• Outcome codes: Study encoding/decoding that depends on measurement outcomes

Performance

• Complexity: O(n_gates × n_qubits²) worst-case, like other simulators
• Key advantage: Simulate once, then sample any number of shots efficiently
• Compared to OutcomeSpecific: Saves a factor of n_random (number of random measurements) when collecting many samples, since the circuit isn’t re-executed per shot
• Sampling cost: O(shots × n_random) to generate outcome samples after simulation
• Space: O(n_qubits² + n_random²) for sign and outcome matrices

Theory

A circuit with n_random with random outcomes has a (worst-case) 2^n_random possible execution paths. This simulator represents all branches implicitly using:

• A Clifford unitary encoding the stabilizer state
• A sign matrix tracking measurement outcome correlations
• An outcome matrix encoding how outcomes depend on n_random random bits
• A deterministic outcome shift vector

The simulation cost is linear in n_random, not exponential. The 2^n_random outcomes are represented compactly and can be sampled efficiently.

Examples

use pauliverse::{OutcomeCompleteSimulation, Simulation};
use paulimer::{UnitaryOp, SparsePauli};

let mut sim = OutcomeCompleteSimulation::new(3);
sim.unitary_op(UnitaryOp::Hadamard, &[0]);
sim.unitary_op(UnitaryOp::ControlledX, &[0, 1]);

let observable: SparsePauli = "ZII".parse().unwrap();
sim.measure(&observable);

// All 2^n_random branches tracked without separate simulation runs
let num_branches = 1 << sim.random_outcome_count();
println!("Tracking {} outcome branches", num_branches);

Alternatives

• Use crate::OutcomeSpecificSimulation for Monte Carlo sampling
• Use crate::OutcomeFreeSimulation when outcomes don’t matter
• Use crate::FaultySimulation for noisy simulations

Outcome-complete stabilizer simulation implementation. See https://arxiv.org/pdf/2309.08676#page=27 for details.

Implementations

impl OutcomeCompleteSimulation

pub fn state_encoder(&self) -> CliffordUnitary

Get the Clifford unitary encoding the current stabilizer state.

This is the unitary R such that R|0⟩ represents the stabilizer state.

pub fn aligned_sign_matrix(&self) -> &AlignedBitMatrix

Get the sign matrix tracking measurement outcome correlations.

The sign matrix A encodes how Pauli signs depend on random outcomes. Returns a cache-aligned reference for efficiency.

pub fn sign_matrix(&self) -> BitMatrix

Get a copy of the sign matrix without alignment constraints.

pub fn aligned_outcome_matrix(&self) -> &AlignedBitMatrix

Get the outcome matrix encoding all 2^k measurement branches.

Each row corresponds to a measurement outcome, each column to a random bit. Returns a cache-aligned reference for efficiency.

pub fn outcome_matrix(&self) -> BitMatrix

Get a copy of the outcome matrix without alignment constraints.

pub fn aligned_outcome_shift(&self) -> &AlignedBitVec

Get the outcome shift vector (deterministic outcome values).

Returns a cache-aligned reference for efficiency.

pub fn outcome_shift(&self) -> BitVec

Get a copy of the outcome shift vector without alignment constraints.

pub fn sample(&self, shots: usize) -> BitMatrix

Sample measurement outcomes from all 2^k branches.

Each shot corresponds to one random selection of the n_random random bits. Returns a matrix where each row is one shot’s outcome vector.

pub fn sample_with_rng<R: Rng>( &self, num_shots: usize, rng: &mut R, ) -> BitMatrix

Sample measurement outcomes using a provided random number generator.

Useful for reproducible sampling with a seeded RNG.

pub fn with_capacity( qubit_count: usize, outcome_count: usize, random_outcome_count: usize, ) -> Self

pub fn measure_pauli_with_hint_generic<HintBits: PauliBits, HintPhase: PhaseExponent>( &mut self, observable: &SparsePauli, hint: &PauliUnitary<HintBits, HintPhase>, )

Measures a Pauli observable using an anti-commuting hint operator.

Panics

Panics if hint does not anti-commute with observable.

pub fn random_outcome_count(&self) -> usize

Get the number of random (non-deterministic) measurement outcomes.

pub fn random_outcome_indicator(&self) -> &[bool]

Get indicators for which outcomes are random.

Returns a slice where [i] is true if outcome i was random.

Trait Implementations

impl Debug for OutcomeCompleteSimulation

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

Formats the value using the given formatter.

impl Default for OutcomeCompleteSimulation

fn default() -> Self

Returns the “default value” for a type.

impl Simulation for OutcomeCompleteSimulation

fn allocate_random_bit(&mut self) -> usize

Allocate a new measurement outcome with a random value.

fn clifford(&mut self, clifford: &CliffordUnitary, support: &[QubitId])

Apply a Clifford unitary to specified qubits.

fn unitary_op(&mut self, unitary_op: UnitaryOp, support: &[QubitId])

Apply a standard Clifford gate operation.

fn permute(&mut self, permutation: &[usize], support: &[QubitId])

Permute qubit indices according to the given permutation.

fn controlled_pauli( &mut self, observable1: &SparsePauli, observable2: &SparsePauli, )

Apply a controlled-Pauli operation.

fn pauli(&mut self, observable: &SparsePauli)

Apply a Pauli operator to the state.

fn pauli_exp(&mut self, observable: &SparsePauli)

Apply a Pauli exponential (Pauli rotation by π).

fn is_stabilizer_up_to_sign(&self, observable: &SparsePauli) -> bool

Check if a Pauli operator is a stabilizer up to a global phase.

fn qubit_count(&self) -> usize

Get the number of qubits in the simulation.

fn conditional_pauli( &mut self, observable: &SparsePauli, outcomes: &[usize], parity: bool, )

Apply a Pauli operator conditioned on measurement outcome parity.

fn is_stabilizer(&self, observable: &SparsePauli) -> bool

Check if a Pauli operator is a stabilizer of the current state.

fn is_stabilizer_with_conditional_sign( &self, observable: &SparsePauli, outcomes: &[OutcomeId], ) -> bool

Check if a Pauli operator is a stabilizer with outcome-dependent sign.

fn measure(&mut self, observable: &SparsePauli) -> usize

Measure a Pauli observable and return the outcome ID.

fn measure_with_hint( &mut self, observable: &SparsePauli, hint: &SparsePauli, ) -> usize

Measure a Pauli observable with a hint for optimization.

fn outcome_count(&self) -> usize

Get the total number of measurement outcomes (deterministic + random).

fn with_capacity( qubit_count: usize, outcome_count: usize, random_outcome_count: usize, ) -> Self

where Self: Sized,

Create a new simulator with pre-allocated capacity.

fn qubit_capacity(&self) -> usize

Get the current qubit capacity (may be larger than qubit count).

fn outcome_capacity(&self) -> usize

Get the current outcome capacity.

fn random_outcome_capacity(&self) -> usize

Get the current random outcome capacity.

fn reserve_qubits(&mut self, new_capacity: usize)

Reserve capacity for additional qubits.

fn reserve_outcomes( &mut self, new_outcome_capacity: usize, new_random_outcome_capacity: usize, )

Reserve capacity for additional outcomes.

fn new(qubit_count: usize) -> Self

where Self: Sized,

Create a new simulator with the specified number of qubits.