Crate bloq_vm 

Execute compiled Bloq programs.

run_bloq and its variants retain the noiseless physical-verification path. lower() produces the backend-independent Instruction stream consumed by runtime, which adds dynamic timing, noise, retries, waits, idling, and mock streaming-decoder decisions.

use bloq_compile::compile;
use bloq_graph::GalleryItem;
use bloq_vm::{LoweringConfig, lower};

let ir = compile(&GalleryItem::CNOT.build(), 3)?;
let options = LoweringConfig::default();
let program = lower(&ir, &options)?;
let result = program.run(options.runtime_config(42))?;
assert!(!result.artifact.discarded);

Physical verification executes compiled circuits, independently of bloq_graph’s logical QuiZX verifier. It supports non-Clifford programs; Clifford circuits can also be checked with Stim.

The physical verifier adds no noise and assumes zero decoder flips. It still executes explicit noise instructions already present in a circuit. Its IR-mandated retries are bounded by DEFAULT_RUS_ATTEMPT_CAP. The dynamic runtime uses decoder instead.

CircuitExecutor is the flat counterpart for a single CoordCircuit; ShotRecord is the per-shot measurement outcome map both paths produce.

Where items live

The crate root carries what it takes to drive the VM: lower() and its configuration, run() and its configuration, the run_bloq family, the Program they exchange, and the error types. The public modules carry the full vocabularies a consumer reads results back with, which are too large to flatten into one root namespace:

• instruction — the whole lowered ISA (Task, QuantumOp, BoolOp, MemoryCycle, …).
• runtime — the execution trace vocabulary (ExecutionEvent, MeasurementRecord, WaitReason, …) behind an ExecutionArtifact.
• decoder — the mock streaming-decoder policy model.
• verify — the physical verifier’s report and expectation readouts.

The names that appear in root signatures are re-exported at the root as well, so those have two paths on purpose: a signature stays nameable without reaching into a module. From instruction that is Program, Instruction, SourceRole, SourceSchedule, TaskOrigin, TaskFunction, and DEFAULT_DECODER_LATENCY_ROUNDS; from runtime it is run, RunResult, RunMetadata, RuntimeConfig, RuntimeLimits, RuntimeError, ExecutionArtifact, LogicalInputState, and TaskMetadata. Prefer the root path for those; reach into the module for the rest of the vocabulary. Everything in the private modules has exactly one path.

The engine (ticit) vocabulary is re-exported at the root only, under Engine-prefixed aliases where its names would otherwise collide with this crate’s own (EnginePauli against instruction::Pauli, EngineInstruction against Instruction).

Re-exports

pub use instruction::DEFAULT_DECODER_LATENCY_ROUNDS;

pub use instruction::Instruction;

pub use instruction::Program;

pub use instruction::SourceRole;

pub use instruction::SourceSchedule;

pub use instruction::TaskFunction;

pub use instruction::TaskOrigin;

pub use runtime::ExecutionArtifact;

pub use runtime::LogicalInputState;

pub use runtime::RunMetadata;

pub use runtime::RunResult;

pub use runtime::RuntimeConfig;

pub use runtime::RuntimeError;

pub use runtime::RuntimeLimits;

pub use runtime::TaskMetadata;

pub use runtime::run;

Modules

decoder

Seeded mock streaming decoder for dynamic VM runs.

instruction

Backend-independent instructions executed by the Bloq VM.

runtime

Dynamic execution of lowered VM instruction streams.

verify

Physical verification: run compiled bloq circuits on the Simulator engine and check them.

Structs

BatchOutcome

What one TableauSimulator::apply_batch run produced.

CircuitExecutor

Replays a flattened CoordCircuit against a Simulator.

EnginePauliString

A Pauli operator on nqubits qubits, with a two-bit phase exponent of i.

InputSeed

One private seed qubit prepared before execution and injected at its input Port’s safe schedule cut.

LoweringConfig

Bounded lowering and timing options.

MeasureResult

Outcome of a Pauli measurement.

OutputLogical

Logical X and Z operators for one program output.

PreparationContext

Per-shot private-seed context for run_bloq_with_io.

SavedOutput

A logical output swapped onto a private engine qubit before its physical patch was reused later in the program.

ShotContext

Per-shot context handed to a run_bloq_with_hook hook, evaluated after the program finishes but before the shot’s simulator is dropped.

ShotFrame

One output’s terminal Pauli-frame value for the current shot.

ShotRecord

The measurement outcomes of one shot, indexed by (global) measurement id.

Simulator

A stim-TableauSimulator-style procedural quantum-state simulator.

SourceTiming

Absolute release epochs for independently schedulable source classes.

Enums

EngineInstruction

One step of a TableauSimulator::apply_batch program.

EnginePauli

A single-qubit Pauli operator.

ExecError

Failures on the noiseless physical-verification path.

Gate1Q

A named single-qubit Clifford, identified by the signed Pauli images (X → …, Z → …) of Gate1Q::images.

LowerError

Failure to produce a finite, standalone VM program.

PauliBasis

A Pauli basis — the non-identity Paulis, as an axis to rotate onto or measure along.

SimError

Errors returned by TableauSimulator operations.

Constants

DEFAULT_MAX_QUANTUM_VARIANTS

Default maximum number of reachable alternatives for one guarded quantum stage.

DEFAULT_RUS_ATTEMPT_CAP

Retry bound for a RepeatUntilSuccess region: a shot still restarting after this many attempts is discarded rather than looping forever.

Functions

lower

Lower bloq to a self-contained VM program.

run_bloq

Verify a whole Bloq program over a seeded shot batch.

run_bloq_with_captured_outputs

Run run_bloq_with_hook while preserving reused output patches.

run_bloq_with_hook

Run run_bloq with a per-shot hook.

run_bloq_with_io

run_bloq with private input seeds and a post-shot output hook.