feat(ppvm-cli): add the ppvm command-line binary

.github/workflows/ci.yml

@@ -70,9 +70,11 @@ jobs:
         run: cargo test -p ppvm-stim --features rayon
 
   # Cross-compile the whole workspace for browser wasm so a wasm regression
-  # surfaces in CI. `ppvm-python-native` is a CPython extension (never a wasm
-  # target) and is excluded. Native-only acceleration deps (gxhash, dashmap →
-  # rayon, ahash) are pruned automatically by the `cfg(not(target_arch =
+  # surfaces in CI. `ppvm-python-native` (a CPython extension) and `ppvm-cli`
+  # (a terminal binary using clap and forcing the rayon feature) are never
+  # browser-wasm targets and are excluded; the reusable engine lives in the
+  # library crates, which stay covered. Native-only acceleration deps (gxhash,
+  # dashmap → rayon, ahash) are pruned automatically by the `cfg(not(target_arch =
   # "wasm32"))` dependency tables, and `rand`'s entropy uses the getrandom
   # `wasm_js` backend wired in `.cargo/config.toml` — so no extra flags here.
   wasm-build:
@@ -89,7 +91,7 @@ jobs:
       - uses: Swatinem/rust-cache@v2
 
       - name: Build workspace for wasm32-unknown-unknown
-        run: cargo build --target wasm32-unknown-unknown --workspace --exclude ppvm-python-native
+        run: cargo build --target wasm32-unknown-unknown --workspace --exclude ppvm-python-native --exclude ppvm-cli
 
   python-tests:
     name: Python tests

Cargo.toml

@@ -20,6 +20,7 @@ members = [
     "crates/ppvm-tableau-sum",
     "crates/vihaco-circuit-isa",
     "crates/ppvm-vihaco",
+    "crates/ppvm-cli",
     # Runnable copies of the Rust code blocks in skills/ppvm-usage/SKILL.md.
     # Built by `cargo build --workspace --all-targets` in CI so the skill
     # can't silently drift away from the public API.

crates/ppvm-cli/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "ppvm-cli"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+clap = { version = "4.6.1", features = ["derive"] }
+eyre = "0.6.12"
+ppvm-vihaco = { version = "0.1.0", path = "../ppvm-vihaco", features = ["rayon"] }
+
+[[bin]]
+name = "ppvm"
+path = "src/main.rs"

crates/ppvm-cli/README.md

@@ -0,0 +1,137 @@
+# ppvm-cli
+
+Command-line front-end for the Pauli-propagation virtual machine. Parses,
+dumps, runs, and steps through `.sst` programs (and their compiled `.ssb`
+bytecode).
+
+## Install
+
+From this crate directory:
+
+```sh
+cargo install --path crates/ppvm-cli
+```
+
+This builds the release binary and copies it to `~/.cargo/bin/ppvm`. As long as
+`~/.cargo/bin` is on your `PATH`, you can then invoke `ppvm` from anywhere.
+
+During development you can skip the install and use `cargo run` instead — just
+put CLI arguments after `--`:
+
+```sh
+cargo run -p ppvm-cli -- run examples/ghz.sst
+```
+
+## Run
+
+`run` executes a program for one or more shots and prints the measurement
+results. The example [`examples/ghz.sst`](examples/ghz.sst) prepares a 3-qubit
+GHZ state and measures every qubit, so each shot reads `000` or `111`:
+
+```sh
+$ ppvm run examples/ghz.sst
+000
+```
+
+Each shot is printed as a single flat bit string — `0`/`1`, with a lost qubit
+shown as `2` — and shots are separated by newlines. Use `-s`/`--shots` to run
+more than one:
+
+```sh
+$ ppvm run examples/ghz.sst --shots 5
+000
+000
+111
+000
+111
+```
+
+Other options:
+
+- `-t`/`--threads <N>` — run shots across `N` threads. More than one enables
+  parallel execution (defaults to 1).
+- `--seed <N>` — seed the RNG for reproducible results. The same seed yields the
+  same shots regardless of the thread count.
+- `-o`/`--output <FILE>` — write the results to a file (one shot per line)
+  instead of stdout.
+- `-f debug` — print the raw record for every shot instead of bit strings.
+- `-q`/`--quiet` — run without printing anything.
+
+```sh
+$ ppvm run examples/ghz.sst --shots 2 -f debug
+[[[Zero], [Zero], [Zero]], [[One], [One], [One]]]
+
+$ ppvm run examples/ghz.sst --shots 1000 --threads 8 -o results.txt
+Results written to results.txt
+```
+
+## Dump
+
+`dump` compiles a `.sst` program to `.ssb` bytecode. With no `-o`, it writes
+next to the input (`ghz.sst` → `ghz.ssb`):
+
+```sh
+$ ppvm dump examples/ghz.sst
+Bytecode written to examples/ghz.ssb
+```
+
+`run` auto-detects the format from the file's contents, so the bytecode runs the
+same way as the source:
+
+```sh
+$ ppvm run examples/ghz.ssb
+000
+```
+
+`dump` refuses to overwrite an existing file unless you pass `-f`/`--force`.
+
+## Debug
+
+`debug` steps through a program interactively. At each pause it prints the
+program counter, the next instruction, and the measurements so far, then waits
+for a command (type the letter and press Enter; a bare Enter steps):
+
+- `s` — step one instruction
+- `c` — continue to the next breakpoint (or the end)
+- `q` — quit
+
+By default it pauses at `breakpoint` instructions in the program. Add one
+wherever you want execution to stop:
+
+```
+fn @main() {
+    const.u64 0
+    circuit.h
+
+    // execution pauses here
+    breakpoint
+
+    const.u64 0
+    circuit.measure
+    ret
+}
+```
+
+```sh
+$ printf 's\nc\n' | ppvm debug program.sst
+-- breakpoint hit --
+pc=3  next: const.u64 0
+measurements:
+> s step | c continue | q quit: pc=4  next: Measure
+measurements:
+> s step | c continue | q quit: Program finished.
+Measurements: 0
+```
+
+To step through a program that has no breakpoints, pass `-b`/`--break-at-start`
+to pause before the very first instruction:
+
+```sh
+$ ppvm debug examples/ghz.sst -b
+pc=0  next: const.u64 0
+measurements:
+> s step | c continue | q quit:
+```
+
+Batch `run` ignores `breakpoint` instructions entirely, so the same file still
+runs straight through with `ppvm run`.

crates/ppvm-cli/examples/bit_flip_correction.sst

@@ -0,0 +1,66 @@
+device circuit.n_qubits 5;
+
+// Data: q0, q1, q2.
+// Syndrome ancillas: q3, q4.
+fn @main() {
+    const.u64 1
+    const.f64 0.25
+    const.f64 0.0
+    const.f64 0.0
+    circuit.paulierror
+
+    const.u64 0
+    const.u64 3
+    circuit.cnot
+    const.u64 1
+    const.u64 3
+    circuit.cnot
+    const.u64 3
+    circuit.measure
+
+    const.u64 1
+    const.u64 4
+    circuit.cnot
+    const.u64 2
+    const.u64 4
+    circuit.cnot
+    const.u64 4
+    circuit.measure
+
+    const.u32 1
+    eq.u32
+    cond_br @s12_one, @s12_zero
+
+@s12_one:
+    const.u32 1
+    eq.u32
+    cond_br @correct_q1, @correct_q2
+
+@s12_zero:
+    const.u32 1
+    eq.u32
+    cond_br @correct_q0, @readout
+
+@correct_q0:
+    const.u64 0
+    circuit.x
+    br @readout
+
+@correct_q1:
+    const.u64 1
+    circuit.x
+    br @readout
+
+@correct_q2:
+    const.u64 2
+    circuit.x
+
+@readout:
+    const.u64 0
+    circuit.measure
+    const.u64 1
+    circuit.measure
+    const.u64 2
+    circuit.measure
+    ret
+}

crates/ppvm-cli/examples/ghz.sst

@@ -0,0 +1,27 @@
+device circuit.n_qubits 3;
+
+// Prepare a 3-qubit GHZ state (|000> + |111>)/sqrt(2) and measure every qubit.
+// The three outcomes are perfectly correlated, so each shot reads 0 0 0 or 1 1 1.
+fn @main() {
+    const.u64 0
+    circuit.h
+
+    const.u64 0
+    const.u64 1
+    circuit.cnot
+
+    const.u64 1
+    const.u64 2
+    circuit.cnot
+
+    const.u64 0
+    circuit.measure
+
+    const.u64 1
+    circuit.measure
+
+    const.u64 2
+    circuit.measure
+
+    ret
+}

crates/ppvm-cli/examples/heisenberg_zz.sst

@@ -0,0 +1,17 @@
+device circuit.n_qubits 2;
+device circuit.backend paulisum;
+device circuit.observable 1.0*ZZ+0.5*XX;
+device circuit.coefficient_threshold 1e-10;
+
+// Heisenberg-picture run on a PauliSum target. The header observable
+// `1.0*ZZ + 0.5*XX` seeds two terms; tracing `[XZ]?*` filters both ZZ
+// (coef 1.0) and XX (coef 0.5), so the trace is their coefficient sum.
+//
+// No gates here, so the trace returns the seeded observable's coefficient
+// sum directly: 1.0 + 0.5 = 1.5. Add `circuit.cnot; circuit.h; circuit.truncate`
+// in textbook-reversed order to evolve before tracing.
+fn @main() {
+    const.str "[XZ]?*"
+    circuit.trace
+    ret
+}