Circuit component and VM — cherry-pick source (re-opening #66)#168
Open
Roger-luo wants to merge 104 commits into
Open
Circuit component and VM — cherry-pick source (re-opening #66)#168Roger-luo wants to merge 104 commits into
Roger-luo wants to merge 104 commits into
Conversation
stellarscope to support generics
This commit depends on upstream fixes in vihaco-cpu and requires stellarscope#59 to be merged
… booleans to stack
|
Contributor
There was a problem hiding this comment.
Pull request overview
Re-opens the original “circuit component and VM” change set (from reverted PR #66) as a cherry-pick source, adding a .sst/.ssb-driven PPVM virtual machine layer (ppvm-vihaco), a CLI (ppvm-cli), and supporting runtime + Python API surface (notably the RotXY / r gate and tableau expectation/trace support).
Changes:
- Introduces a vihaco-backed circuit ISA + VM runtime (
vihaco-circuit-isa,ppvm-vihaco) with observable parsing, bytecode format, shot execution, and extensive.sstfixtures. - Adds
ppvm-clifor parsing/dumping/running/debugging.sst/.ssbprograms and updates docs/skill references. - Extends core simulation APIs with
RotXY(r) across traits/tableau/PauliSum and wires it through Python bindings and tests.
Reviewed changes
Copilot reviewed 61 out of 64 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/ppvm-usage/SKILL.md | Documents .sst usage, backend selection, and trace/truncate semantics; updates crate list. |
| prek.toml | Adjusts hawkeye pre-commit hook invocation. |
| ppvm-python/test/test_basics.py | Adds PauliSum tests for the new r gate behavior. |
| ppvm-python/test/generalized_tableau/test_basics.py | Adds GeneralizedTableau tests for r equivalence to rx/ry. |
| ppvm-python/src/ppvm/mixins.py | Exposes r in Python mixins (tableau + PauliSum variants) and tweaks rxx docstring. |
| crates/vihaco-circuit-isa/src/lib.rs | Defines circuit instruction set + message shapes + codec/parse tests. |
| crates/vihaco-circuit-isa/Cargo.toml | New crate manifest for the circuit ISA. |
| crates/ppvm-vihaco/tests/tableau_ry_z_trace.sst | Adds tableau trace fixture for RY and Z expectation. |
| crates/ppvm-vihaco/tests/tableau_ghz_xxx_trace.sst | Adds tableau GHZ trace fixture. |
| crates/ppvm-vihaco/tests/tableau_bell_trace.sst | Adds tableau Bell trace fixture. |
| crates/ppvm-vihaco/tests/sst_fixtures.rs | End-to-end fixture runner for .sst/.ssb round-trips and backend agreement checks. |
| crates/ppvm-vihaco/tests/rotxy.sst | Fixture for circuit.r behavior (axis-angle rotation). |
| crates/ppvm-vihaco/tests/paulisum_trotter_truncate.sst | PauliSum trotter + explicit truncate fixture. |
| crates/ppvm-vihaco/tests/paulisum_ry_z_trace.sst | PauliSum Heisenberg RY trace fixture. |
| crates/ppvm-vihaco/tests/paulisum_multi_term_trace.sst | Multi-term observable parsing + trace fixture. |
| crates/ppvm-vihaco/tests/paulisum_measure_error.sst | Fixture asserting measure is rejected on PauliSum backend. |
| crates/ppvm-vihaco/tests/paulisum_ghz_xxx_trace.sst | PauliSum GHZ trace fixture (Heisenberg-reversed gate order). |
| crates/ppvm-vihaco/tests/paulisum_bell_trace.sst | PauliSum Bell ZZ trace fixture. |
| crates/ppvm-vihaco/tests/lossy_paulisum_loss_trace.sst | LossyPauliSum loss+trace fixture with Rust-side reference comparison. |
| crates/ppvm-vihaco/tests/hello_circuit.sst | Minimal hello-world circuit fixture. |
| crates/ppvm-vihaco/tests/function_call.sst | Function call fixture for call/return (or halt) behavior. |
| crates/ppvm-vihaco/tests/function_call_ret.sst | Function call + branching fixture (currently documented as “aspirational”). |
| crates/ppvm-vihaco/tests/function_call_branch_both.sst | Branching on tri-state measurement outcome fixture. |
| crates/ppvm-vihaco/tests/branch_on_outcome.sst | Conditional branching fixture driven by measurement. |
| crates/ppvm-vihaco/tests/branch_on_outcome_x.sst | Deterministic branch fixture (X-prepared). |
| crates/ppvm-vihaco/tests/bell.sst | Basic Bell measurement fixture. |
| crates/ppvm-vihaco/src/syntax.rs | Parser + resolver for PPVM modules, headers, labels/branches/calls, and circuit-prefixed ops. |
| crates/ppvm-vihaco/src/shots.rs | Adds shot runner (serial/parallel) with per-shot seeding and thread-pool sizing. |
| crates/ppvm-vihaco/src/observable.rs | Implements Pauli-sum header string parsing into (word, coeff) terms. |
| crates/ppvm-vihaco/src/measurements.rs | Defines measurement/trace observers and effect union for circuit outcomes. |
| crates/ppvm-vihaco/src/lib.rs | Public API for parsing/compiling/running/dumping .sst and loading modules/bytecode. |
| crates/ppvm-vihaco/src/component.rs | Circuit component dispatch for Tableau/PauliSum/LossyPauliSum (including trace/truncate semantics). |
| crates/ppvm-vihaco/src/bytecode.rs | .ssb framing format with versioning, device-info serialization, and tests. |
| crates/ppvm-vihaco/Cargo.toml | New crate manifest (optional rayon feature; links to tableau/paulisum and ISA). |
| crates/ppvm-traits/src/traits/mod.rs | Re-exports RotXY trait. |
| crates/ppvm-traits/src/traits/branch/rot1.rs | Adds RotXY trait definition to trait system. |
| crates/ppvm-traits/src/traits/branch/mod.rs | Re-exports RotXY from branch module. |
| crates/ppvm-tableau/src/lib.rs | Exposes new expectation/trace module. |
| crates/ppvm-tableau/src/gates/rot1.rs | Implements RotXY for GeneralizedTableau and adds tests. |
| crates/ppvm-tableau/src/expectation.rs | Adds tableau expectation value + pattern trace implementation and tests. |
| crates/ppvm-tableau/src/data.rs | Adds reset helpers and adjusts rayon parallelism guard; adds PauliWord decomposition helper. |
| crates/ppvm-tableau/Cargo.toml | Adds ppvm-pauli-word dependency for pattern/word support. |
| crates/ppvm-runtime/src/traits/branch/rot1.rs | Adds runtime-side RotXY trait definition (new file). |
| crates/ppvm-python-native/src/interface.rs | Exposes r on the PyO3 interface (with optional truncation). |
| crates/ppvm-python-native/src/interface_tableau.rs | Exposes r on tableau PyO3 interface. |
| crates/ppvm-python-native/ppvm_python_native.pyi | Adds r to type stubs for PauliSum and GeneralizedTableau. |
| crates/ppvm-pauli-sum/src/sum/rot1.rs | Implements RotXY for PauliSum and adds tests for axis-angle equivalence. |
| crates/ppvm-cli/src/main.rs | Adds ppvm CLI entrypoint with parse/dump/run/debug subcommands and global thread sizing. |
| crates/ppvm-cli/src/commands.rs | Implements CLI commands, formatting, and debugger loop + tests. |
| crates/ppvm-cli/README.md | Documents CLI installation and usage. |
| crates/ppvm-cli/examples/simple_loop.sst | Example .sst loop with breakpoint. |
| crates/ppvm-cli/examples/loop_feedforward.sst | Example .sst loop + measurement feed-forward. |
| crates/ppvm-cli/examples/loop_feedforward.pseudo | Pseudocode companion for the feed-forward example. |
| crates/ppvm-cli/examples/heisenberg_zz.sst | Example .sst for PauliSum Heisenberg trace with multi-term observable. |
| crates/ppvm-cli/examples/ghz.sst | Example .sst GHZ preparation and measurement. |
| crates/ppvm-cli/examples/bit_flip_correction.sst | Example .sst implementing a bit-flip correction flow using branching. |
| crates/ppvm-cli/Cargo.toml | New CLI crate manifest. |
| Cargo.toml | Adds new workspace members (ppvm-vihaco, ppvm-cli, vihaco-circuit-isa). |
| AGENTS.md | Updates skill summary to mention .sst and ppvm-cli. |
| .gitignore | Ignores debug/ directory. |
| .github/workflows/ci.yml | Excludes ppvm-cli from wasm build step; updates wasm build comments. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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
+4
to
+8
| // 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. | ||
| call 0, @run_circuit | ||
| ret |
| const.u64 1 | ||
| circuit.measure | ||
|
|
||
| ret 1 |
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
+88
to
+90
| # Installed via mise in CI (see mise.toml), but called directly here so local | ||
| # installs on PATH also work. Run `hawkeye format` manually to apply headers to | ||
| # new files. |
This was referenced Jul 8, 2026
david-pl
added a commit
that referenced
this pull request
Jul 8, 2026
## Merge order Part of splitting #168 into small, focused PRs. Full stack (independent items may merge in any relative order; dependents wait for their base): 1. **single-qubit rotations (this PR)** → `main` 2. core tableau expectation/reset (`feat/tableau-expectation-reset`) → `main` 3. native `.pyi` type stubs (`feat/native-pyi-stubs`) → **this PR** (declares the native `r` added here) 4. vihaco-circuit-isa (#169) → `main` 5. circuit component (`david/42.2-circuit-component`) → #169 6. composite (`david/42.3-composite`) → #5 7. CLI + TUI (#166) → #6 Items 1, 2, and 4 are mutually independent off `main`. ## Summary Adds the `RotXY` trait to `ppvm-traits` and implements it for both backends (`ppvm-tableau`, `ppvm-pauli-sum`), plus the `r(...)` Python binding on the native PauliSum / tableau classes and the `RotationsMixin` / `TruncatingRotationsMixin` wrappers. `RotXY` is a single-qubit rotation about an arbitrary axis in the X/Y plane: ``` R(axis_angle, θ) = exp(-i θ/2 · (cos(axis_angle)·X + sin(axis_angle)·Y)) = RZ(axis_angle)·RX(θ)·RZ(−axis_angle) ``` Pure addition alongside the existing `RotationOne` (RX/RY/RZ) rotations; no new module wiring. Like `u3`, `r` is single-qubit (scalar `addr0`), not batched over `targets`. ## Provenance Snapshotted from the tip of #168 (not cherry-picked); the R gate is a prerequisite for the circuit-component backends there. ## Testing `cargo test -p ppvm-traits -p ppvm-tableau -p ppvm-pauli-sum` green (incl. `test_rx/ry/rz/r`). Python: `maturin develop` + `pytest test/test_basics.py test/generalized_tableau/test_basics.py` → 37 passed. prek hooks (fmt, check, clippy, machete, ruff, ty, license) all pass. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
david-pl
added a commit
that referenced
this pull request
Jul 8, 2026
## Merge order Part of splitting #168 into small, focused PRs. Full stack (independent items may merge in any relative order; dependents wait for their base): 1. single-qubit rotations (#170) → `main` 2. **core tableau expectation/reset (this PR)** → `main` 3. native `.pyi` type stubs (`feat/native-pyi-stubs`) → #170 4. vihaco-circuit-isa (#169) → `main` 5. circuit component (`david/42.2-circuit-component`) → #169 6. composite (`david/42.3-composite`) → #5 7. CLI + TUI (#166) → #6 Items 1, 2, and 4 are mutually independent off `main`. ## Summary Adds `expectation.rs` for `GeneralizedTableau`: - `expectation` — single-Pauli ⟨ψ|P|ψ⟩ for a `PauliWord`, conjugating P through the tableau and overlapping with the sparse coefficient vector. - `trace` — Σ over Paulis matching a `PauliPattern`. Supporting changes in `data.rs`: - `compute_decomposition_word` — multi-qubit conjugation used by `expectation`. - `reset_all` on both `Tableau` and `GeneralizedTableau` — reinitialise to |0…0⟩, clearing coefficients and loss state (refactors `new` via a shared `new_data` helper). - the rayon-nesting guard on the coefficient path (avoids nesting rayon inside shot-level parallelism; a no-op on the single-shot path). `lib.rs` gains `pub mod expectation`; `Cargo.toml` gains a `ppvm-pauli-word` dependency. Pure core addition, snapshotted from #168. ## Testing `cargo test -p ppvm-tableau` green (12 expectation tests + reset/noise). prek hooks all pass. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
david-pl
added a commit
that referenced
this pull request
Jul 8, 2026
## Merge order Part of the #168 split. **Stacked on #170** (base branch `feat/single-qubit-rotations`) because this stub file declares the native `r` binding that #170 adds. Merge #170 first, then this. Full stack: single-qubit rotations (#170) → **this** ; core tableau expectation/reset (`feat/tableau-expectation-reset`) → `main` ; vihaco-circuit-isa (#169) → `main` ; then circuit component → composite → CLI/TUI (#166). ## Summary Adds `ppvm_python_native.pyi` — the first type-stub file for the compiled `ppvm._core` module (none exists on `main`). It declares the macro-generated concrete classes (`PauliSumIndexMapFxHash{0..15}`, `PauliSumLossIndexMapFxHash{0..15}`, the `GeneralizedTableau{N}` family, `StimProgram`) via synthetic `_PauliSumBase` / `_PauliSumLossBase` / `_GeneralizedTableauBase` bases that hold the shared method signatures once. Pure additive typing surface; no runtime effect. Split out of #170 because the block covers the whole module — only `r` is new API; the rest describe pre-existing bindings. ## Provenance Snapshotted from the tip of #168. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jul 8, 2026
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.
Hey @david-pl — heads up on the plan here 👇
What happened: #66 ("Implement circuit component and vm") was squash-merged into
mainbut caused repeated merge-conflict churn, so it was reverted in #167 (already merged —mainis back to its pre-#66 state). When #66 merged, its branch was auto-deleted; I have restoreddavid/42-circuit-componentwith all 104 original commits intact, and this PR re-exposes them.The ask: rather than re-landing this as one big commit, lets cherry-pick the changes into
mainin small, focused PRs. This PR is not meant to be merged wholesale — merging it as-is would just re-introduce the same conflict churn that forced the revert. Please use it as the source to pull individual pieces from.How to use it:
david/42-circuit-componentinto targeted branches and open small PRs againstmain.Original PR: #66
Revert PR: #167 (merged)
🤖 Generated with Claude Code