Struct MeasurementSampler 

pub struct MeasurementSampler { /* private fields */ }

Fast repeated measurement sampling from a compiled Stim circuit.

An analyzed stabilizer circuit whose measurements can be sampled quickly. The sampler uses a noiseless reference sample, collected from the circuit using Stim’s Tableau simulator during initialization, as a baseline for deriving more samples using an error-propagation simulator.

This is the Rust equivalent of Python’s stim.CompiledMeasurementSampler. Obtain one via Circuit::compile_sampler.

Examples

let circuit: stim::Circuit = "X 0\nM 0 1".parse().unwrap();
let mut sampler = circuit.compile_sampler(false);
let results = sampler.sample(4);
assert_eq!(results.ncols(), 2);
assert_eq!(results.nrows(), 4);
// Qubit 0 was flipped by X, qubit 1 was not.
assert!(results[[0, 0]]);
assert!(!results[[0, 1]]);

Implementations

impl MeasurementSampler

pub fn num_measurements(&self) -> u64

Creates a measurement sampler for the given circuit.

The sampler uses a noiseless reference sample, collected from the circuit using Stim’s Tableau simulator during initialization, as a baseline for deriving more samples using an error-propagation simulator.

Arguments

• circuit - The stabilizer circuit to sample measurements from.
• skip_reference_sample - When true, the reference sample is set to all zeros instead of being collected from the circuit. This means returned results represent whether each measurement was flipped, rather than actual measurement outcomes. Useful when you only care about error propagation or when you know the all-zero result is a valid noiseless outcome. Computing the reference sample is the most expensive part of initialization, so skipping it is an effective optimization.
• seed - Deterministically seeds the random number generator. Making the exact same series of calls on the same machine with the same Stim version will produce the same results. Results are not guaranteed to be consistent across Stim versions, SIMD widths, or varying shot counts.

Examples

Returns the number of measurement bits produced per shot.

This equals the total number of M (and similar measurement) operations in the compiled circuit.

pub fn sample_bit_packed(&mut self, shots: u64) -> Vec<u8>

Samples measurement data in bit-packed form.

Returns a flat Vec<u8> where each shot occupies ceil(num_measurements / 8) bytes. Within each byte, bits are packed in little-endian order, matching Stim’s b8 data layout: the bit for measurement m in shot s is at result[s * row_bytes + m / 8] >> (m % 8) & 1.

pub fn sample(&mut self, shots: u64) -> Array2<bool>

Samples a batch of measurement results as an unpacked boolean matrix.

Returns an Array2<bool> with shape (shots, num_measurements). The bit for measurement m in shot s is at result[[s, m]].

Examples

let circuit: stim::Circuit = "X 0\nM 0".parse().unwrap();
let mut sampler = circuit.compile_sampler(false);
assert_eq!(sampler.sample(3), ndarray::array![[true], [true], [true]]);

pub fn sample_write( &mut self, shots: u64, filepath: impl AsRef<Path>, format_name: ShotDataFormat, ) -> Result<()>

Samples measurements from the circuit and writes them directly to a file.

This is more memory-efficient than calling sample and then writing the result, because the data is streamed to disk without ever being fully materialized in memory.

Arguments

• shots - The number of times to sample every measurement.
• filepath - The file path to write results to.
• format_name - The output format.

Errors

Returns a StimError if the file path is not valid UTF-8 or the file cannot be written.

Examples

let circuit: stim::Circuit = "X 0\nM 0".parse().unwrap();
let path = std::env::temp_dir().join("stim-rs-measurement-sampler-write.01");
let mut sampler = circuit.compile_sampler(false);
sampler
    .sample_write(2, &path, stim::ShotDataFormat::Bits01)
    .unwrap();
assert_eq!(std::fs::read_to_string(&path).unwrap(), "1\n1\n");
std::fs::remove_file(path).unwrap();

Trait Implementations

impl Debug for MeasurementSampler

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

Formats the value using the given formatter.