ppvm_sym (crate)

`ppvm_sym`¶

ppvm_sym

Symbolic, parametric Pauli propagation.

`ppvm-sym` provides a Term type that represents a polynomial in sines and cosines of symbolic parameters. It is used by ppvm to propagate Pauli operators through parametric circuits (e.g., variational ansätze) without committing to specific angle values until the very end.

Quick example

Build the symbolic expression `sin(x0) * cos(x1)`, then evaluate it at a concrete `(x0, x1)`:

``` use ppvm_sym::Term;

let expr = Term::var(0).sin() * Term::var(1).cos();

let v = expr.eval(&[0.5, 1.0]).unwrap(); let expected = 0.5_f64.sin() * 1.0_f64.cos(); assert!((v - expected).abs() < 1e-12); ```

class`Prod`¶source

ppvm_sym::Prod

Bases: AddAssign<Prod>, Display, Mul, MulAssign, Debug, Clone, StructuralPartialEq, PartialEq, Eq, Hash, Default

Rust struct. `<coeff> sin^m cos^n`

pub struct Prod

A single product of trigonometric atoms over symbolic variables. Sines and cosines are grouped by variable id; powers are tracked as totals so we can quickly compute and bound them. The order of variables is kept canonical (ascending) so two `Prod` values representing the same monomial compare equal.

method`add_phase`¶source

ppvm_sym::Prod::add_phase

pub fn add_phase(&mut self, phase: u8)

Parameters

Name	Type	Description
`phase`	`u8`

Multiply the phase by `i^phase` (modulo `4`).

method`cos`¶source

ppvm_sym::Prod::cos

pub fn cos(id: u32) -> Self

Parameters

Name	Type	Description
`id`	`u32`

Returns

Self

Build the singleton product `cos(x_id)`.

method`cos_pow`¶source

ppvm_sym::Prod::cos_pow

pub fn cos_pow(&self) -> usize

Returns

usize

Total power of the cosine factors.

method`eval`¶source

ppvm_sym::Prod::eval

pub fn eval(&self, vals: &[f64]) -> Result<f64>

Parameters

Name	Type	Description
`vals`	`&[f64]`

Returns

Result<f64>

Evaluate the product at the variable assignment `vals`, where `vals[i]` is the value substituted for variable `i`.

method`mul_cos`¶source

ppvm_sym::Prod::mul_cos

pub fn mul_cos(&mut self, u: u32)

Parameters

Name	Type	Description
`u`	`u32`

Multiply this product by an additional `cos(x_u)`.

method`mul_sin`¶source

ppvm_sym::Prod::mul_sin

pub fn mul_sin(&mut self, u: u32)

Parameters

Name	Type	Description
`u`	`u32`

Multiply this product by an additional `sin(x_u)`.

method`new`¶source

ppvm_sym::Prod::new

pub fn new() -> Self

Returns

Self

Construct the empty product (the multiplicative identity, value `1`).

method`pow`¶source

ppvm_sym::Prod::pow

pub fn pow(&self) -> usize

Returns

usize

Total power of all sine and cosine factors.

method`sin`¶source

ppvm_sym::Prod::sin

pub fn sin(id: u32) -> Self

Parameters

Name	Type	Description
`id`	`u32`

Returns

Self

Build the singleton product `sin(x_id)`.

method`sin_pow`¶source

ppvm_sym::Prod::sin_pow

pub fn sin_pow(&self) -> usize

Returns

usize

Total power of the sine factors.

class`Sum`¶source

ppvm_sym::Sum

Bases: AddAssign<f64>, AddAssign<Prod>, Display, MulAssign<f64>, Debug, Clone, StructuralPartialEq, PartialEq, Default

Rust struct. A formal sum `c₀ + Σᵢ cᵢ · pᵢ`, where each `pᵢ` is a [`Prod`] and `cᵢ` is an `f64` coefficient.

pub struct Sum

method`add_const`¶source

ppvm_sym::Sum::add_const

pub fn add_const(&mut self, c: f64, min_eps: f64)

Parameters

Name	Type	Description
`c`	`f64`
`min_eps`	`f64`

Add the constant `c` into the sum’s `c₀`, dropping it if `|c| < min_eps`.

method`add_term`¶source

ppvm_sym::Sum::add_term

Signature

pub fn add_term(&mut self, p: Prod, coeff: f64, max: usize, min_eps: f64)

Parameters

Name	Type	Description
`p`	`Prod`
`coeff`	`f64`
`max`	`usize`
`min_eps`	`f64`

Add `coeff · p` into the sum, subject to the same trunation constraints used elsewhere (`max` caps the sine power, `min_eps` drops near-zero coefficients).

method`eval`¶source

ppvm_sym::Sum::eval

pub fn eval(&self, vals: &[f64]) -> Result<f64>

Parameters

Name	Type	Description
`vals`	`&[f64]`

Returns

Result<f64>

Evaluate the sum at `vals`.

method`mul_term`¶source

ppvm_sym::Sum::mul_term

Signature

pub fn mul_term(&mut self, p: Prod, coeff: f64, max: usize, min_eps: f64)

Parameters

Name	Type	Description
`p`	`Prod`
`coeff`	`f64`
`max`	`usize`
`min_eps`	`f64`

Multiply this sum in place by `coeff · p`, respecting the same `max` / `min_eps` truncation bounds used elsewhere.

method`new`¶source

ppvm_sym::Sum::new

pub fn new() -> Self

Returns

Self

Construct an empty sum (value `0`).

class`Term`¶source

ppvm_sym::Term

Bases: AddAssign<f64>, AddAssign<Prod>, AddAssign, Add, Add<f64>, Add<Term>, Sub, Sub<f64>, Coefficient, ComplexCoefficient, Sum, Neg, From<f32>, From<f64>, From<i32>, From<i64>, Zero, Display, MulAssign<Term>, MulAssign<f64>, MulAssign, Mul<f64>, Mul<Term>, Mul, Debug, Clone, StructuralPartialEq, PartialEq

Rust struct. A symbolic polynomial in `sin(x_i)` and `cos(x_i)`.

pub struct Term

`Term` is the public-facing wrapper around its Inner enum. It also carries two truncation parameters, applied during multiplication and addition:

Examples

``` use ppvm_sym::Term;

// sin²(x0) at x0 = π/2 equals 1. let expr = Term::var(0).sin() * Term::var(0).sin(); let v = expr.eval(&[std::f64::consts::FRAC_PI_2]).unwrap(); assert!((v - 1.0).abs() < 1e-12); ```

`max_sin` — drop terms whose total sine power exceeds this bound.
`min_eps` — drop terms whose coefficient magnitude falls below this threshold.

method`cos`¶source

ppvm_sym::Term::cos

pub fn cos(self) -> Self

Returns

Self

Apply `cos(·)` to the term. Only valid on variables and constants.

method`eval`¶source

ppvm_sym::Term::eval

pub fn eval(&self, vals: &[f64]) -> Result<f64>

Parameters

Name	Type	Description
`vals`	`&[f64]`

Returns

Result<f64>

Evaluate this symbolic term at `vals`.

method`from_f64`¶source

ppvm_sym::Term::from_f64

pub fn from_f64(c: f64) -> Self

Parameters

Name	Type	Description
`c`	`f64`

Returns

Self

Build a constant term from `c`.

method`set_max_sin`¶source

ppvm_sym::Term::set_max_sin

pub fn set_max_sin(&mut self, max: usize)

Parameters

Name	Type	Description
`max`	`usize`

Set the maximum sine power retained during arithmetic.

method`set_min_eps`¶source

ppvm_sym::Term::set_min_eps

pub fn set_min_eps(&mut self, eps: f64)

Parameters

Name	Type	Description
`eps`	`f64`

Set the coefficient cutoff used during arithmetic.

method`sin`¶source

ppvm_sym::Term::sin

pub fn sin(self) -> Self

Returns

Self

Apply `sin(·)` to the term. Only valid on variables and constants.

method`var`¶source

ppvm_sym::Term::var

pub fn var(u: u32) -> Self

Parameters

Name	Type	Description
`u`	`u32`

Returns

Self

Construct a bare symbolic variable.

class`Inner`¶source

ppvm_sym::Inner

Bases: Debug, Clone, StructuralPartialEq, PartialEq

Rust enum. Internal representation of a [`Term`].

pub enum Inner

Variants

Name	Type	Description
`Sum`	`(Sum)`	A general sum of products.
`One`	`(Prod, f64)`	A single weighted product.
`Var`	`(u32)`	A bare symbolic variable (only valid as the argument of `sin` or `cos`).
`Const`	`(f64)`	A numeric constant.

`Sum` holds a full formal sum; `One` is the optimisation for a single weighted product; `Var` is a bare symbolic variable used before it has been wrapped in a `sin` or `cos`; `Const` is a numeric scalar.