Implement circuit component and vm by david-pl · Pull Request #66 · QuEraComputing/ppvm

david-pl · 2026-04-28T11:57:52Z

Implements a vihaco component for circuit execution with instructions and a simple VM, finally putting the VM into ppvm.

Closes #42.

~~Requires https://github.com/QuEraComputing/stellarscope/pull/51 to be merged.~~
~~Requires https://github.com/QuEraComputing/stellarscope/pull/59 to be merged.~~
~~Requires QuEraComputing/vihaco#3 to be merged.~~

CI fails because of dependency issues (the repo can't pull in vihaco, since that's still private).

stellarscope to support generics

This commit depends on upstream fixes in vihaco-cpu and requires stellarscope#59 to be merged

… booleans to stack

Copilot

Pull request overview

This PR integrates a vihaco-backed circuit execution path into ppvm by introducing a circuit ISA, a ppvm-vihaco virtual machine capable of parsing/running .sst source and .ssb bytecode, plus a small ppvm CLI/REPL/debugger for interacting with programs. It also extends the simulator surface area with an R(axis_angle, θ) (“RotXY”) single-qubit rotation across Rust + Python bindings, and adds tableau-side Pauli expectation/trace utilities to support circuit trace.

Changes:

Add vihaco-circuit-isa and ppvm-vihaco (module parsing/resolution, bytecode container format, shot runner, fixtures) to run circuits/programs via a simple VM model.
Add ppvm-cli with parse/dump/run/debug subcommands and an interactive REPL.
Extend simulators/bindings with RotXY::r(...) and add GeneralizedTableau expectation/trace support.

Reviewed changes

Copilot reviewed 62 out of 65 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
skills/ppvm-usage/SKILL.md	Updates skill docs for `.sst`/CLI usage (currently contains unresolved merge-conflict markers).
prek.toml	Adjusts hawkeye pre-commit hook invocation.
ppvm-python/test/test_basics.py	Adds PauliSum tests for `r(axis_angle, θ)` behavior.
ppvm-python/test/generalized_tableau/test_basics.py	Adds tableau tests for `r(axis_angle, θ)` equivalences.
ppvm-python/src/ppvm/mixins.py	Exposes `r(...)` on Python mixins (docstring cross-reference needs Markdown-style).
crates/vihaco-circuit-isa/src/lib.rs	New circuit instruction set + message types + codec/parse/display tests.
crates/vihaco-circuit-isa/Cargo.toml	New crate manifest for the circuit ISA.
crates/ppvm-vihaco/tests/tableau_ry_z_trace.sst	New `.sst` fixture for tableau `trace` on RY-prepared state.
crates/ppvm-vihaco/tests/tableau_ghz_xxx_trace.sst	New `.sst` fixture for tableau GHZ `trace`.
crates/ppvm-vihaco/tests/tableau_bell_trace.sst	New `.sst` fixture for tableau Bell `trace`.
crates/ppvm-vihaco/tests/sst_fixtures.rs	End-to-end tests: compile/resolve/run `.sst`, dump/load `.ssb`, cross-backend trace agreement.
crates/ppvm-vihaco/tests/rotxy.sst	New `.sst` fixture for `circuit r` end-to-end.
crates/ppvm-vihaco/tests/paulisum_trotter_truncate.sst	New `.sst` fixture exercising PauliSum + explicit truncation.
crates/ppvm-vihaco/tests/paulisum_ry_z_trace.sst	New `.sst` fixture for PauliSum `trace` under `ry`.
crates/ppvm-vihaco/tests/paulisum_multi_term_trace.sst	New `.sst` fixture for multi-term observable parsing + trace.
crates/ppvm-vihaco/tests/paulisum_measure_error.sst	New `.sst` fixture ensuring measure errors on PauliSum backend.
crates/ppvm-vihaco/tests/paulisum_ghz_xxx_trace.sst	New `.sst` fixture for PauliSum GHZ trace path.
crates/ppvm-vihaco/tests/paulisum_bell_trace.sst	New `.sst` fixture for PauliSum Bell trace path.
crates/ppvm-vihaco/tests/lossy_paulisum_loss_trace.sst	New `.sst` fixture for LossyPauliSum loss channel + trace.
crates/ppvm-vihaco/tests/hello_circuit.sst	New `.sst` smoke fixture for a small circuit.
crates/ppvm-vihaco/tests/function_call.sst	New `.sst` fixture exercising `call`/`ret` (comment currently mismatches code).
crates/ppvm-vihaco/tests/function_call_ret.sst	New `.sst` fixture for return-value behavior with branching.
crates/ppvm-vihaco/tests/function_call_branch_both.sst	New `.sst` fixture for tri-state outcome branching (lost vs kept).
crates/ppvm-vihaco/tests/branch_on_outcome.sst	New `.sst` fixture for measurement-conditioned branching.
crates/ppvm-vihaco/tests/branch_on_outcome_x.sst	New `.sst` fixture for deterministic branch path.
crates/ppvm-vihaco/tests/bell.sst	New `.sst` Bell fixture (currently measures q0 twice).
crates/ppvm-vihaco/src/syntax.rs	New parser/resolver for `.sst` into `PPVMInstruction` + header handling (typo in header variant name).
crates/ppvm-vihaco/src/shots.rs	New multi-shot runner with optional rayon parallelism + determinism tests.
crates/ppvm-vihaco/src/observable.rs	New parser for `device circuit.observable` multi-term Pauli-sum strings.
crates/ppvm-vihaco/src/measurements.rs	New observers/effects for measurement and trace streams (doc comment spelling).
crates/ppvm-vihaco/src/lib.rs	Public API for parse/compile/run/dump/load module and re-export of `CircuitInstruction`.
crates/ppvm-vihaco/src/bytecode.rs	New `.ssb` bytecode container writer/reader with device-info framing and tests.
crates/ppvm-vihaco/Cargo.toml	New crate manifest and feature flags (rayon).
crates/ppvm-traits/src/traits/mod.rs	Re-exports new `RotXY` trait.
crates/ppvm-traits/src/traits/branch/rot1.rs	Defines new `RotXY` trait.
crates/ppvm-traits/src/traits/branch/mod.rs	Exports `RotXY` from branch trait module.
crates/ppvm-tableau/src/lib.rs	Exposes new `expectation` module.
crates/ppvm-tableau/src/gates/rot1.rs	Implements `RotXY` for tableau via `RZ(-φ) RX(θ) RZ(φ)` decomposition + tests.
crates/ppvm-tableau/src/expectation.rs	Adds `GeneralizedTableau::{expectation, trace}` for Pauli expectations/pattern traces + tests.
crates/ppvm-tableau/src/data.rs	Adds reset helpers, word decomposition helper, and avoids nested rayon in coefficient branching.
crates/ppvm-tableau/Cargo.toml	Adds dependency on `ppvm-pauli-word` for pattern support.
crates/ppvm-runtime/src/traits/branch/rot1.rs	Adds `RotXY` trait in runtime traits module.
crates/ppvm-python-native/src/interface.rs	Exposes PauliSum-side `r(...)` in the PyO3 interface with optional truncation.
crates/ppvm-python-native/src/interface_tableau.rs	Exposes tableau-side `r(...)` in the PyO3 interface.
crates/ppvm-python-native/ppvm_python_native.pyi	Adds type stubs including `r(...)` for PauliSum and GeneralizedTableau.
crates/ppvm-pauli-sum/src/sum/rot1.rs	Implements `RotXY` for PauliSum with correct Heisenberg ordering + tests.
crates/ppvm-cli/src/repl.rs	New REPL for interactive circuit stepping via `PPVM`.
crates/ppvm-cli/src/main.rs	New CLI entry point wiring subcommands + global thread pool sizing.
crates/ppvm-cli/src/commands.rs	Implements `parse`/`dump`/`run`/`debug` commands and formatting/tests.
crates/ppvm-cli/README.md	Documents installing and using `ppvm` CLI and debugger.
crates/ppvm-cli/examples/simple_loop.sst	Example `.sst` showing loops + breakpoint.
crates/ppvm-cli/examples/loop_feedforward.sst	Example `.sst` showing looping feed-forward control.
crates/ppvm-cli/examples/loop_feedforward.pseudo	Pseudocode companion for feed-forward example.
crates/ppvm-cli/examples/heisenberg_zz.sst	Example `.sst` for PauliSum Heisenberg trace of seeded observable.
crates/ppvm-cli/examples/ghz.sst	Example `.sst` for GHZ prep and measurement.
crates/ppvm-cli/examples/bit_flip_correction.sst	Example `.sst` for a simple bit-flip correction flow.
crates/ppvm-cli/Cargo.toml	New CLI crate manifest.
Cargo.toml	Adds new crates to the workspace members list.
AGENTS.md	Mentions `.sst` format in agent guide (uses wrong instruction prefix terminology).
.gitignore	Ignores `debug/` directory.
.github/workflows/ci.yml	Excludes `ppvm-cli` from wasm build job.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 61 out of 64 changed files in this pull request and generated 10 comments.

Copilot

Pull request overview

Copilot reviewed 61 out of 64 changed files in this pull request and generated 10 comments.

Copilot

Pull request overview

Copilot reviewed 61 out of 64 changed files in this pull request and generated 10 comments.

Copilot

Pull request overview

Copilot reviewed 63 out of 66 changed files in this pull request and generated 7 comments.

Copilot

Pull request overview

Copilot reviewed 61 out of 64 changed files in this pull request and generated 8 comments.

Copilot

Pull request overview

Copilot reviewed 61 out of 64 changed files in this pull request and generated 5 comments.

+    const.u64 0
+    circuit.measure
+
+    const.u64 0


+    // Jump into the helper, which finishes the program with `halt`.
+    // Using `halt` instead of `ret` from the callee avoids depending on
+    // vihaco-cpu restoring a return PC, which it doesn't track today.


+// TODO: aspirational — depends on `ret <n>` restoring the caller's PC and
+// leaving the top `n` values on the caller's stack. The runtime doesn't do
+// this today (Frame has no return_pc), so this fixture currently fails.


+    // `function_call.sst` has main `call` into `@run_circuit`, which puts q1
+    // in |+>, measures it, and `halt`s. Verifies CallPatch resolves the
+    // symbolic target and op_call actually transfers control there.


+            }
+            PPVMEffect::Measurement(effect) => {
+                let follow_ups = Observe::<MeasurementEffect>::observe(self, &effect)?;
+                // NOTE: push measurements to stack; two booleans: outcome, is_lost


david-pl and others added 27 commits April 20, 2026 13:55

Start implementing vihaco component

37ef32c

Implement batched instructions

78ebef2

Make measurement result an outcome

a46ecb2

Simplify outcome type

8a9071f

Fix generic types, hardcode f64 coeffs; temporarily switch to local

71c1703

stellarscope to support generics

Draft machine impl

02c8135

Add TODO

931cb12

Start refactoring to new vihaco

1ed6da3

Rename Circuit component

75a5c11

Merge branch 'main' into david/42-circuit-component

c6af3db

Also reset loss state

e493165

Add a component that dispatches and make components observe effects

1394c57

More prelude exports

91f7c41

Refactor machine into composite

4e65f33

Fix measurement effect return and don't manually push const

6c56b58

Delete some old code

5ce25ee

Device info for PPVM

939d812

Merge branch 'main' into david/42-circuit-component

75047f9

Implement parsing for PPVM

3d3fb82

Add tests and fix some bugs

71d50d3

Unused import

b16ffa9

Push measurement and is_lost to stack; test control flow

3ebf0db

Implement function call support

5734844

Add magic number to header

b88859f

Handle function calls and returns properly

6b236c3

This commit depends on upstream fixes in vihaco-cpu and requires stellarscope#59 to be merged

Remove magic number from text format

981b1a7

Make MeasurementOutcome an enum and push a single u32 rather than two…

5ad1f54

… booleans to stack

david-pl mentioned this pull request May 22, 2026

Bytecode and VM Integration #40

Closed

david-pl requested review from Roger-luo and kaihsin May 29, 2026 13:27

Copilot AI reviewed Jun 26, 2026

View reviewed changes

david-pl added 4 commits June 29, 2026 09:07

Fix skill merge conflict

0cd5bc1

Fix :meth: docstrings

c16a066

Syntax: "circuit h" -> "circuit.h"

5152646

Remove the REPL

8beb96a

Copilot AI review requested due to automatic review settings June 30, 2026 09:05

Copilot started reviewing on behalf of david-pl June 30, 2026 09:05 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 30, 2026 10:23

Copilot started reviewing on behalf of david-pl June 30, 2026 10:23 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 30, 2026 10:29

Copilot started reviewing on behalf of david-pl June 30, 2026 10:29 View session

david-pl added 2 commits June 30, 2026 12:32

Fix copilot's dumb changes

7fa85d0

Clean up some dependencies

5a3765d

david-pl force-pushed the david/42-circuit-component branch from 893211d to 5a3765d Compare June 30, 2026 10:36

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 30, 2026 10:36

Copilot started reviewing on behalf of david-pl June 30, 2026 10:36 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

david-pl added 2 commits July 1, 2026 09:13

Merge branch 'main' into david/42-circuit-component

3c9a51a

Fix machete

f7df680

Copilot AI review requested due to automatic review settings July 1, 2026 07:24

Copilot started reviewing on behalf of david-pl July 1, 2026 07:24 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

david-pl added 2 commits July 1, 2026 10:47

Add back eyre

9de97d8

Implement PauliSum resets

a12c623

Copilot AI review requested due to automatic review settings July 1, 2026 13:43

Copilot started reviewing on behalf of david-pl July 1, 2026 13:44 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

Uh oh!

Conversation

david-pl commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

david-pl commented Apr 28, 2026 •

edited

Loading