Implement circuit component and vm#66
Open
david-pl wants to merge 100 commits into
Open
Conversation
stellarscope to support generics
This commit depends on upstream fixes in vihaco-cpu and requires stellarscope#59 to be merged
… booleans to stack
|
There was a problem hiding this comment.
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-isaandppvm-vihaco(module parsing/resolution, bytecode container format, shot runner, fixtures) to run circuits/programs via a simple VM model. - Add
ppvm-cliwithparse/dump/run/debugsubcommands and an interactive REPL. - Extend simulators/bindings with
RotXY::r(...)and addGeneralizedTableauexpectation/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.
Comment on lines
+52
to
+58
| match header { | ||
| PPVMHeader::NumQubits(n) => { | ||
| info.n_qubits = n; | ||
| } | ||
| PPVMHeader::CoefficientThrehsold(t) => { | ||
| info.coefficient_threshold = t; | ||
| } |
Comment on lines
+27
to
+30
| strategies, Python / Rust call sites for both backends, and the `.sst` | ||
| textual program format run by `ppvm-cli` (backend selection, multi-term | ||
| observables, `gate trace` / `gate truncate`). Read it before the Developer | ||
| Guide if your task is *using* ppvm rather than modifying its internals. |
Comment on lines
+4
to
+6
| // 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. |
Comment on lines
+14
to
+15
| const.u64 0 | ||
| circuit measure |
Comment on lines
+146
to
+150
| // One measurement event, one qubit, deterministically |0>. | ||
| assert_eq!(shot.measurements.len(), 1); | ||
| assert_eq!(shot.measurements[0].as_slice(), [MeasurementOutcome::Zero]); | ||
| assert!(shot.traces.is_empty(), "Tableau backend emits no traces"); | ||
| } |
Comment on lines
+4
to
+6
| // 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. |
Comment on lines
+3
to
+5
| // 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. |
Comment on lines
+81
to
+83
| // `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. |
Comment on lines
+8
to
+13
| /// Measurement results are represent as an integer enum | ||
| /// 0: state |0> | ||
| /// 1: state |1> | ||
| /// 2: qubit has been lost prior to measurement | ||
| /// In byte-code, this is represented as a u32 integer, which is simpler than | ||
| /// e.g. two boolean values and matches semantics elsewhere |
Comment on lines
+475
to
+482
| impl<T> vihaco::Reset for PauliSumExecutor<T> | ||
| where | ||
| T: Config<Coeff = f64>, | ||
| { | ||
| fn reset(&mut self) { | ||
| // TODO(Task 5/6): rebuild self.state from the seeded observable. | ||
| } | ||
| } |
Comment on lines
+541
to
+548
| impl<T> vihaco::Reset for LossyPauliSumExecutor<T> | ||
| where | ||
| T: Config<Coeff = f64>, | ||
| { | ||
| fn reset(&mut self) { | ||
| // TODO(Task 5/6): rebuild self.state from the seeded observable. | ||
| } | ||
| } |
Comment on lines
+24
to
+26
| #[token = "circuit.coefficient_threshold"] | ||
| #[delimiters(open = "", close = "", separator = "")] | ||
| CoefficientThrehsold(f64), |
Comment on lines
+56
to
+58
| PPVMHeader::CoefficientThrehsold(t) => { | ||
| info.coefficient_threshold = t; | ||
| } |
Comment on lines
+447
to
+450
| #[test] | ||
| PPVMResolver::apply_header(&mut info, PPVMHeader::CoefficientThreshold(5e-6)).unwrap(); | ||
| } | ||
|
|
Comment on lines
+27
to
+30
| strategies, Python / Rust call sites for both backends, and the `.sst` | ||
| textual program format run by `ppvm-cli` (backend selection, multi-term | ||
| observables, `gate trace` / `gate truncate`). Read it before the Developer | ||
| Guide if your task is *using* ppvm rather than modifying its internals. |
Comment on lines
+14
to
+15
| const.u64 0 | ||
| circuit.measure |
Comment on lines
+4
to
+6
| // 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. |
Comment on lines
+3
to
+5
| // 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. |
Comment on lines
+6
to
+9
| [dependencies] | ||
| chumsky = "0.10" | ||
| eyre = "0.6.12" | ||
| smallvec = "1.15.1" |
Comment on lines
+698
to
+700
| for l in self.is_lost.iter_mut() { | ||
| *l &= false; | ||
| } |
david-pl
force-pushed
the
david/42-circuit-component
branch
from
893211d to
5a3765d
Compare
Comment on lines
+698
to
+700
| for l in self.is_lost.iter_mut() { | ||
| *l &= false; | ||
| } |
Comment on lines
+27
to
+30
| strategies, Python / Rust call sites for both backends, and the `.sst` | ||
| textual program format run by `ppvm-cli` (backend selection, multi-term | ||
| observables, `gate trace` / `gate truncate`). Read it before the Developer | ||
| Guide if your task is *using* ppvm rather than modifying its internals. |
Comment on lines
+11
to
+17
| /// Output format for `parse`. | ||
| #[derive(Clone, Debug, clap::ValueEnum)] | ||
| pub enum Format { | ||
| Pretty, | ||
| Debug, | ||
| Json, | ||
| } |
Comment on lines
+475
to
+481
| impl<T> vihaco::Reset for PauliSumExecutor<T> | ||
| where | ||
| T: Config<Coeff = f64>, | ||
| { | ||
| fn reset(&mut self) { | ||
| // TODO(Task 5/6): rebuild self.state from the seeded observable. | ||
| } |
Comment on lines
+541
to
+547
| impl<T> vihaco::Reset for LossyPauliSumExecutor<T> | ||
| where | ||
| T: Config<Coeff = f64>, | ||
| { | ||
| fn reset(&mut self) { | ||
| // TODO(Task 5/6): rebuild self.state from the seeded observable. | ||
| } |
Comment on lines
+14
to
+15
| const.u64 0 | ||
| circuit.measure |
Comment on lines
+4
to
+6
| // 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. |
Comment on lines
+3
to
+5
| // 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. |
| const.u64 0 | ||
| circuit.measure | ||
|
|
||
| const.u64 0 |
Comment on lines
+4
to
+6
| // 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. |
Comment on lines
+3
to
+5
| // 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. |
Comment on lines
+18
to
+29
| ppvm-tableau = { version = "0.1.0", path = "../ppvm-tableau" } | ||
| smallvec = "1.15.1" | ||
| vihaco = "0.1.1" | ||
| vihaco-cpu = "0.1.1" | ||
| vihaco-parser = "0.1.1" | ||
| vihaco-parser-core = "0.1.1" | ||
| vihaco-circuit-isa = { version = "0.1.0", path = "../vihaco-circuit-isa" } | ||
| ppvm-pauli-sum = { version = "0.1.0", path = "../ppvm-pauli-sum" } | ||
|
|
||
| # enable rayon if not on wasm | ||
| [target.'cfg(not(target_arch = "wasm32"))'.dependencies] | ||
| ppvm-tableau = { version = "0.1.0", path = "../ppvm-tableau", features = ["rayon"] } |
Comment on lines
+93
to
+97
| // Term: coefficient [*] word | bare word. | ||
| let term_with_coeff = coefficient | ||
| .then_ignore(just('*').padded().or_not()) | ||
| .then(pauli_word) | ||
| .map(|(c, w)| (w, c)); |
Comment on lines
+698
to
+700
| for l in self.is_lost.iter_mut() { | ||
| *l &= false; | ||
| } |
Comment on lines
79
to
83
| id = "hawkeye" | ||
| name = "hawkeye license header check" | ||
| language = "system" | ||
| entry = "mise exec -- hawkeye check" | ||
| entry = "hawkeye check" | ||
| pass_filenames = false |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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).