ppvm_stim (crate)

ppvm_stim¶

ppvm_stim

Parse and execute Stim circuits against a [`GeneralizedTableau`].

Two-stage pipeline:

1. parse_extended — `&str` → [`ExtendedProgram`] (re-exported from `stim_parser`).
2. execute / sample — call validate to validate the [`ExtendedProgram`], then apply it to a [`GeneralizedTableau`].

Multi-shot usage should call parse_extended once and pass the parsed program to sample. The run_string / run_file convenience helpers re-parse on every call and are intended for single-shot demos only.

Multi-shot pattern (recommended)

```ignore use ppvm_stim::{parse_extended, sample}; use ppvm_tableau::prelude::*;

let prog = parse_extended(circuit_src)?; let shots = sample(&prog, 10_000, || { GeneralizedTableau::<, usize, _>::new(n_qubits, 1e-10) })?;

Ok::<(), ppvm_stim::Error>(())

```

run_string / run_file re-parse on every call and exist only for single-shot demos — never call them from a shot loop.

Modules

• executor
• validate

classError¶source

ppvm_stim::Error

Bases: Debug, Error, Display, From<Diagnostics>, From<ExecError>

Rust enum.

pub enum Error

Variants

Name	Type	Description
Parse	(Diagnostics)	A parse/validate/lower failure from `stim_parser`, reported as a [`Diagnostics`] aggregate.
Exec	(ExecError)
Io	{ ... }

source

classExecError¶source

ppvm_stim::ExecError

Bases: Debug, Error, Display, StructuralPartialEq, PartialEq, From<ExecError>

Rust enum.

pub enum ExecError

Variants

Name	Type	Description
Unsupported	{ ... }
InvalidProbability	{ ... }
InvalidRecordControl	{ ... }
InvalidPauliProduct	{ ... }

source

functionexecute¶source

ppvm_stim::execute

Signature

pub fn execute<T, I, C>(program: &ExtendedProgram, tab: &mut GeneralizedTableau<T, I, C>) -> Result<Vec<Option<bool>>, ExecError>

Parameters

Name	Type	Description
program	&ExtendedProgram
tab	&mut GeneralizedTableau<T, I, C>

Returns

Result<Vec<Option<bool>>, ExecError>

Validate and execute a parsed extended Stim program against a tableau, returning the per-measurement results in circuit order.

source

functionexecute_validated¶source

ppvm_stim::execute_validated

Signature

pub fn execute_validated<T, I, C>(instructions: &[ExtendedInstruction], tab: &mut GeneralizedTableau<T, I, C>, results: &mut Vec<Option<bool>>)

Parameters

Name	Type	Description
instructions	&[ExtendedInstruction]
tab	&mut GeneralizedTableau<T, I, C>
results	&mut Vec<Option<bool>>

Dispatch a slice of validated instructions onto a tableau, appending measurement bits to `results`. Skips validation — the caller is responsible for having run validate on the originating program. Used by execute / sample internally and by the Python `tab.run()` path where `StimProgram` already cached the validate step.

source

functionrun_file¶source

ppvm_stim::run_file

Signature

pub fn run_file<T, I, C>(path: &Path, tab: &mut GeneralizedTableau<T, I, C>) -> Result<Vec<Option<bool>>, Error>

Parameters

Name	Type	Description
path	&Path
tab	&mut GeneralizedTableau<T, I, C>

Returns

Result<Vec<Option<bool>>, Error>

source

functionrun_string¶source

ppvm_stim::run_string

Signature

pub fn run_string<T, I, C>(src: &str, tab: &mut GeneralizedTableau<T, I, C>) -> Result<Vec<Option<bool>>, Error>

Parameters

Name	Type	Description
src	&str
tab	&mut GeneralizedTableau<T, I, C>

Returns

Result<Vec<Option<bool>>, Error>

Parse → validate → execute in one shot. Re-parses each call; do not use in shot loops — use parse_extended + sample instead.

source

functionsample¶source

ppvm_stim::sample

Signature

pub fn sample<T, I, C, F>(program: &ExtendedProgram, num_shots: usize, make_tableau: F) -> Result<Vec<Vec<Option<bool>>>, ExecError>

Parameters

Name	Type	Description
program	&ExtendedProgram
num_shots	usize
make_tableau	F

Returns

Result<Vec<Vec<Option<bool>>>, ExecError>

Execute many shots, building a fresh tableau for shot `i` via `make_tableau(i)`.

Without the `rayon` feature execution is always serial. Enable the `rayon` feature to get a version that can dispatch to parallel execution for large batches. Use sample_serial to force serial execution regardless of the feature.

source

functionsample_serial¶source

ppvm_stim::sample_serial

Signature

pub fn sample_serial<T, I, C, F>(program: &ExtendedProgram, num_shots: usize, make_tableau: F) -> Result<Vec<Vec<Option<bool>>>, ExecError>

Parameters

Name	Type	Description
program	&ExtendedProgram
num_shots	usize
make_tableau	F

Returns

Result<Vec<Vec<Option<bool>>>, ExecError>

Execute many shots serially, building a fresh tableau for shot `i` via `make_tableau(i)`.

The shot index lets callers derive a deterministic per-shot seed (e.g. `seed + i`) so results are independent of evaluation order — the same factory then yields identical results from `sample_parallel` (when the `rayon` feature is enabled).

source

functionsample_serial_validated¶source

ppvm_stim::sample_serial_validated

Signature

pub fn sample_serial_validated<T, I, C, F>(instructions: &[ExtendedInstruction], measurement_count: usize, num_shots: usize, make_tableau: F) -> Vec<Vec<Option<bool>>>

Parameters

Name	Type	Description
instructions	&[ExtendedInstruction]
measurement_count	usize
num_shots	usize
make_tableau	F

Returns

Vec<Vec<Option<bool>>>

Like sample_serial but skips validation — call only when the program has already been validated (e.g. via validate).

source

functionsample_validated¶source

ppvm_stim::sample_validated

Signature

pub fn sample_validated<T, I, C, F>(instructions: &[ExtendedInstruction], measurement_count: usize, num_shots: usize, make_tableau: F) -> Vec<Vec<Option<bool>>>

Parameters

Name	Type	Description
instructions	&[ExtendedInstruction]
measurement_count	usize
num_shots	usize
make_tableau	F

Returns

Vec<Vec<Option<bool>>>

Like sample but skips validation — call only when the program has already been validated (e.g. via validate). Without the `rayon` feature this always runs serially.

source

functionvalidate¶source

ppvm_stim::validate

pub fn validate(program: &ExtendedProgram) -> Result<(), ExecError>

Parameters

Name	Type	Description
program	&ExtendedProgram

Returns

Result<(), ExecError>

source