Skip to content

feat(ppvm-sym-2): symbolic sin/cos coefficient ring over ppvm-traits-2 - #313

Merged
lkdvos merged 3 commits into
mainfrom
claude/ppvm-sym-release-prep-6e8960
Nov 20, 2026
Merged

lkdvos merged 3 commits into
mainfrom
claude/ppvm-sym-release-prep-6e8960

Conversation

@lkdvos

@lkdvos lkdvos commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds ppvm-sym-2, the symbolic coefficient ring for the -2 engine. A Term is a polynomial in sin(xᵥ) and cos(xᵥ) of circuit parameters with real f64 coefficients, so a circuit is propagated once and evaluated at many angles. It implements Coefficient, Angle, ImaginaryUnit, Conjugate and Halvable, and depends only on ppvm-traits-2.

Design

struct Prod { factors: Vec<Factor>, sin_pow: usize, imag: bool } // [i] · Π sin(xᵥ)^a cos(xᵥ)^b
struct Sum  { c0: f64, terms: FxHashMap<Prod, f64>, aux: FxHashMap<Prod, f64> }
enum Inner  { Sum(Sum), One(Prod, f64), Const(f64) }
struct Term { inner: Inner, max_sin: usize, min_eps: f64 }
struct Var(u32) // an angle, not a Term
  • One representation per value.
    • A monomial keeps only an imag bit. Every phase operation returns the ±1 it moves into the coefficient.
    • The real identity monomial is never a table key; constants live in c₀ or Const.
    • Cancelled monomials are removed, so x − x is structurally empty.
  • Equality by value: Const(c) equals a constant-only Sum, and One equals a one-entry Sum.
  • Truncation is an invariant.
    • max_sin and min_eps apply to monomials, never to the constant.
    • Setting them prunes; every operation truncates its result with the left operand's settings, including One × One.
  • Var is its own angle type, so a bare variable can't enter arithmetic and no operator panics.
  • Evaluation: eval is the real part of eval_complex, with a per-call sin/cos cache.
  • No engine dependency: scale a sum with sum.scale(&term).
  • Only Term, Var, MissingVariable and the default thresholds are public; the representation above is crate-private.

Why

Differences from #204's ppvm-sym-2

#204 This PR
Phase phase: u8 on the monomial imag bit
Variables Inner::Var separate Var type
Engine depends on ppvm-pauli-sum-2, for sum *= term no dependency

Open questions for reviewers

  • magnitude is +∞ for symbolic terms, which is cautious, so CoefficientThreshold never drops one. The ℓ¹ norm would bound the value at every angle and allow more truncation.
  • No sum *= term operator. It needs an edge between the ring and the pauli engine in one direction or the other, since that isn't done yet this is left out for now.
  • The bit-exact evaluation order. Relaxing it would allow one pass per factor and enable SIMD but requires reassociating floating point operations.

Testing

  • 46 unit tests, run over 14 forms that cover every representation and phase:
    • evaluation is a ring homomorphism to ℂ;
    • the ring axioms hold for every triple;
    • max_sin truncation is exact for every form and operator;
    • a 60-step multiply chain tracks the running product.

Follow-ups

Assisted by Claude Code

Copilot AI balanced review requested due to automatic review settings November 19, 2026 17:16

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor
PR Preview Action v1.8.2
Preview removed because the pull request was closed.
2026-11-20 17:14 UTC

@lkdvos
lkdvos force-pushed the claude/ppvm-sym-release-prep-6e8960 branch from efb472c to bcca069 Compare November 19, 2026 17:49
Copilot AI balanced review requested due to automatic review settings November 19, 2026 17:49

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@lkdvos
lkdvos requested a review from david-pl November 19, 2026 19:10
A `Term` is a polynomial in `sin(x_v)`/`cos(x_v)` of circuit parameters, with
real `f64` coefficients, implementing the `ppvm-traits-2` coefficient traits
(`Coefficient`, `Angle`, `ImaginaryUnit`, `Conjugate`, `Halvable`).

- One representation per value: a monomial keeps only an `imag` bit and every
  phase operation returns the sign it moves into the coefficient; the real
  identity is never a table key; cancelled monomials are removed.
- Equality is by value, so `Const(c)` equals a constant-only `Sum`.
- `max_sin`/`min_eps` are an invariant on monomials: setting them prunes and
  every operation truncates its result with the left operand's settings. The
  constant is never truncated.
- `Var` is a separate angle type, so a bare variable cannot enter arithmetic.
- `eval` is the real part of `eval_complex`, with a per-call trig cache.
- No dependency on the engine: scale a sum with `sum.scale(&term)`.

Assisted-by: Claude Code
@lkdvos
lkdvos force-pushed the claude/ppvm-sym-release-prep-6e8960 branch from bcca069 to b4cdbe5 Compare November 20, 2026 12:29
Copilot AI balanced review requested due to automatic review settings November 20, 2026 12:29

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@david-pl david-pl left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just one minor thing, and I'd suggest to see if you can split the large files.

Comment thread crates/ppvm-sym-2/src/term.rs Resolved
Comment thread crates/ppvm-sym-2/src/term.rs Resolved
With a strict `<`, `min_eps = 0` kept exact zeros: a cancelled monomial
stayed in the table and `is_zero` failed on `Const(0.0)`. Dropping at the
threshold makes `min_eps = 0` remove exactly the zeros.

Assisted-by: Claude Code
`Factor`/`Prod` move to `prod.rs` and `Sum` to `sum.rs`, each with its
own tests; `term.rs` keeps `Inner`, `Term` and `Var`. No behaviour change.

Assisted-by: Claude Code
Copilot AI balanced review requested due to automatic review settings November 20, 2026 13:37

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@lkdvos
lkdvos merged commit 6ced520 into main Nov 20, 2026
22 checks passed
@lkdvos
lkdvos deleted the claude/ppvm-sym-release-prep-6e8960 branch November 20, 2026 17:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants