Implement circuit component and vm#66
Open
david-pl wants to merge 94 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
+3
to
+7
| <<<<<<< HEAD | ||
| description: Authoritative usage guide for ppvm, a fast quantum-circuit simulator with a Rust core and Python bindings (`ppvm-runtime`, `ppvm-tableau`, `ppvm-sym`, `ppvm-stim`, `ppvm-vihaco`, `ppvm` Python package). Use this skill whenever a task touches ppvm — importing `ppvm` in Python, depending on any `ppvm-*` crate in Rust, writing or running `.sst` programs through `ppvm-cli`, writing or modifying Pauli-propagation code, building or running circuits against the generalized stabilizer tableau, executing Stim programs, modelling depolarizing or loss noise, or even just answering "how do I do X in ppvm". Use it even when the user only hints at ppvm (mentions Pauli strings + truncation, or `GeneralizedTableau`, or "Bloqade simulation backend"). Skipping this skill is a top source of broken examples — the API has several non-obvious conventions (Heisenberg gate order, `Config`-generic types, kwargs-not-classes truncation) that look reasonable but are wrong if guessed. | ||
| ======= | ||
| description: Authoritative usage guide for ppvm, a fast quantum-circuit simulator with a Rust core and Python bindings (`ppvm-traits`, `ppvm-pauli-word`, `ppvm-pauli-sum`, `ppvm-tableau`, `ppvm-sym`, `ppvm-stim`, `ppvm` Python package). Use this skill whenever a task touches ppvm — importing `ppvm` in Python, depending on any `ppvm-*` crate in Rust, writing or modifying Pauli-propagation code, building or running circuits against the generalized stabilizer tableau, executing Stim programs, modelling depolarizing or loss noise, or even just answering "how do I do X in ppvm". Use it even when the user only hints at ppvm (mentions Pauli strings + truncation, or `GeneralizedTableau`, or "Bloqade simulation backend"). Skipping this skill is a top source of broken examples — the API has several non-obvious conventions (Heisenberg gate order, `Config`-generic types, kwargs-not-classes truncation) that look reasonable but are wrong if guessed. | ||
| >>>>>>> main |
| def r(self, addr0: int, axis_angle: float, theta: float, *, truncate: bool = True) -> None: | ||
| """Apply a rotation about an axis in the X-Y plane to the specified qubit. | ||
|
|
||
| See :meth:`RotationsMixin.r` for the gate definition. |
| axis_angle: The angle ``φ`` (in radians) of the rotation axis | ||
| within the X-Y plane, measured from the X-axis. | ||
| theta: The rotation angle in radians. | ||
| truncate: See :meth:`rx`. |
Comment on lines
+24
to
+27
| #[token = "circuit.coefficient_threshold"] | ||
| #[delimiters(open = "", close = "", separator = "")] | ||
| CoefficientThrehsold(f64), | ||
|
|
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
+8
to
+12
| /// 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 |
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"); | ||
| } |
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).