feat(python-native): add type stubs for the native _core module#171
Merged
Conversation
Add the `RotXY` trait to `ppvm-traits` and implement 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. Native type stubs (`.pyi`) for the whole module
are split into a separate follow-up PR. Snapshotted from #168, where the
R gate is a prerequisite for the circuit-component backends.
Merge order for the #168 split: single-qubit rotations (this) and core
tableau expectation/reset target `main` independently; native .pyi stubs
stack on this; then vihaco-circuit-isa (#169) -> circuit component ->
composite -> CLI/TUI (#166).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add `ppvm_python_native.pyi` — the first type-stub file for the compiled
`ppvm._core` module. 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 the R-gate
PR because the stub block covers the whole module (only `r` is new API;
the rest describe pre-existing bindings), and it must stack on that PR
since it declares `r`.
Merge order: stacks on the single-qubit-rotations PR (which adds the
native `r` binding). Part of the #168 split.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new .pyi stub file intended to describe the public typing surface of the compiled native Python extension module used by ppvm (ppvm._core).
Changes:
- Introduces
crates/ppvm-python-native/ppvm_python_native.pyiwith class/type declarations for native PauliSum and GeneralizedTableau bindings.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+1
to
+4
| from typing import Sequence | ||
|
|
||
|
|
||
| class _PauliSumBase: |
Comment on lines
+5
to
+13
| def __init__( | ||
| self, | ||
| n_qubits: int, | ||
| min_abs_coeff: float = 1e-10, | ||
| max_pauli_weight: int = ..., | ||
| max_loss_weight: int = ..., | ||
| terms: list[str] = ..., | ||
| coefficients: list[float] = ..., | ||
| ) -> None: ... |
Comment on lines
+22
to
+29
| def x(self, addr0: int) -> None: ... | ||
| def y(self, addr0: int) -> None: ... | ||
| def z(self, addr0: int) -> None: ... | ||
| def h(self, addr0: int) -> None: ... | ||
| def s(self, addr0: int) -> None: ... | ||
| def cnot(self, addr0: int, addr1: int) -> None: ... | ||
| def cz(self, addr0: int, addr1: int) -> None: ... | ||
| def s_adj(self, addr0: int) -> None: ... |
| def __str__(self) -> str: ... | ||
| def __copy__(self) -> "_GeneralizedTableauBase": ... | ||
| def __deepcopy__(self, memo: object) -> "_GeneralizedTableauBase": ... | ||
| def measure(self, addr0: int) -> bool | None: ... |
Comment on lines
+157
to
+163
| class StimProgram: | ||
| @staticmethod | ||
| def parse(src: str) -> "StimProgram": ... | ||
| @staticmethod | ||
| def from_file(path: str) -> "StimProgram": ... | ||
| def __repr__(self) -> str: ... | ||
|
|
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.
Merge order
Part of the #168 split. Stacked on #170 (base branch
feat/single-qubit-rotations) because this stub file declares the nativerbinding 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 compiledppvm._coremodule (none exists onmain). It declares the macro-generated concrete classes (PauliSumIndexMapFxHash{0..15},PauliSumLossIndexMapFxHash{0..15}, theGeneralizedTableau{N}family,StimProgram) via synthetic_PauliSumBase/_PauliSumLossBase/_GeneralizedTableauBasebases 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
ris new API; the rest describe pre-existing bindings.Provenance
Snapshotted from the tip of #168.