Struct Parameter 

pub struct Parameter { /* private fields */ }

A symbolic or numeric parameter used to represent gate angles and other continuous values in a quantum circuit.

Parameter is a thin, cheaply-cloneable wrapper around symb_anafis::Expr. It supports the full suite of arithmetic operators (+, -, *, /) between Parameter values as well as between Parameter and primitive numeric types (f64, f32, i32, u32).

The mathematical constants π and e are always available as free symbols and are automatically resolved during Parameter::evaluate.

Implementations

impl Parameter

pub fn new(expr: Expr) -> Self

Creates a new Parameter directly from a symb_anafis::Expr node.

Prefer Parameter::symbol for named variables or the From<f64> / From<i32> impls for numeric constants.

pub fn as_expr(&self) -> &Expr

Returns a reference to the underlying expression.

pub fn into_expr(self) -> Expr

Consumes the parameter and returns the underlying expression.

pub fn symbol(name: &str) -> Self

Creates a symbolic parameter representing a free variable with the given name.

Examples

use cqlib_core::circuit::Parameter;

let theta = Parameter::symbol("θ");
assert_eq!(theta.get_symbols().contains("θ"), true);

pub fn evaluate( &self, bindings: &Option<HashMap<&str, f64>>, ) -> Result<f64, ParameterError>

Evaluates the expression to a concrete f64 value.

The mathematical constants π and e are injected automatically, so callers do not need to supply them. Additional variable bindings are provided through bindings.

Returns ParameterError::NaN if the expression still contains unbound free variables after applying the supplied bindings.

Examples

use cqlib_core::circuit::Parameter;
use std::collections::HashMap;

// Numeric constant — no bindings needed.
let p = Parameter::from(std::f64::consts::PI);
assert!((p.evaluate(&None).unwrap() - std::f64::consts::PI).abs() < 1e-10);

// Symbolic expression with a user-supplied binding.
let theta = Parameter::symbol("θ");
let expr  = theta * Parameter::from(2.0);
let mut bindings = HashMap::new();
bindings.insert("θ", 1.0_f64);
assert!((expr.evaluate(&Some(bindings)).unwrap() - 2.0).abs() < 1e-10);

pub fn simplify(&self) -> Result<Self, ParameterError>

Returns an algebraically simplified form of this parameter.

Simplification is performed in a domain-safe mode to avoid invalid transformations (e.g. taking the log of a potentially negative number). For affine sums, scalar products and division by numeric constants, nonzero f64 coefficients and cancellation results are preserved without tolerance pruning. Numeric literals are retained exactly. Floating-point rounding, overflow and underflow still apply. Parsing and general nonlinear simplification use the symbolic engine’s own numeric policy.

Examples

use cqlib_core::circuit::Parameter;

let theta = Parameter::symbol("θ");
let expr  = theta.clone() * Parameter::from(1.0);   // θ * 1
let simplified = expr.simplify().unwrap();
assert_eq!(simplified.to_string(), "θ");

pub fn canonicalized(&self) -> Result<Self, ParameterError>

Returns the canonical storage form of this parameter expression.

A constant expression is evaluated before symbolic simplification. If simplification eliminates all symbols, the result is also evaluated and rebuilt as a finite numeric parameter. This also normalizes -0.0 to 0.0, giving circuit operation storage a stable representation for equivalent constants.

Symbolic expressions are returned in their simplified form. This method does not intern symbolic parameters into any circuit; use Circuit::map_param when a CircuitParam is needed for operation storage.

Errors

Returns ParameterError if simplification fails, a constant expression cannot be evaluated, or the evaluated constant is not finite.

pub fn is_exact_zero(&self) -> Result<bool, ParameterError>

Returns whether this parameter is exactly the numeric constant 0.0.

This is stricter than Parameter::is_zero: symbolic parameters return false, and constants are compared exactly after evaluation rather than with an epsilon tolerance. Compiler canonicalization uses this predicate when deciding whether a no-op is represented exactly as zero.

Errors

Returns ParameterError if a constant parameter cannot be evaluated.

pub fn derivative(&self, var: &str) -> Result<Self, ParameterError>

Computes the symbolic partial derivative of this expression with respect to the variable var.

Returns ParameterError if differentiation is not supported for the expression.

Examples

use cqlib_core::circuit::Parameter;

let theta = Parameter::symbol("θ");
let expr  = theta.clone() * theta.clone();  // θ²
let deriv = expr.derivative("θ").unwrap();  // 2θ
let val   = deriv.evaluate(&Some([("θ", 3.0)].iter().cloned().collect())).unwrap();
assert!((val - 6.0).abs() < 1e-10);

pub fn get_symbols(&self) -> HashSet<String>

Returns the set of free variable names present in this expression.

The built-in constants π and e may appear here if the expression was constructed symbolically (e.g. via Parameter::pi), but they are resolved automatically during Parameter::evaluate.

Examples

use cqlib_core::circuit::Parameter;

let expr = Parameter::symbol("θ") + Parameter::symbol("φ");
let syms = expr.get_symbols();
assert!(syms.contains("θ"));
assert!(syms.contains("φ"));

pub fn abs(&self) -> Self

Returns a new parameter representing the absolute value |x|.

pub fn sqrt(&self) -> Self

Returns a new parameter representing the square root √x.

pub fn exp(&self) -> Self

Returns a new parameter representing the exponential eˣ.

pub fn sin(&self) -> Self

Returns a new parameter representing the sine sin(x).

pub fn asin(&self) -> Self

Returns a new parameter representing the inverse sine asin(x).

pub fn cos(&self) -> Self

Returns a new parameter representing the cosine cos(x).

pub fn acos(&self) -> Self

Returns a new parameter representing the inverse cosine acos(x).

pub fn tan(&self) -> Self

Returns a new parameter representing the tangent tan(x).

pub fn atan(&self) -> Self

Returns a new parameter representing the inverse tangent atan(x).

pub fn ln(&self) -> Self

Returns a new parameter representing the natural logarithm ln(x).

pub fn log(&self, base: impl Into<Self>) -> Self

Returns a new parameter representing the logarithm log_base(x).

Examples

use cqlib_core::circuit::Parameter;

// log base 2 of x
let x    = Parameter::symbol("x");
let log2 = x.log(Parameter::from(2.0));
let val  = log2.evaluate(&Some([("x", 8.0)].iter().cloned().collect())).unwrap();
assert!((val - 3.0).abs() < 1e-10);

pub fn pi() -> Self

Returns the mathematical constant π as a symbolic parameter.

The symbol "π" is resolved to std::f64::consts::PI automatically inside Parameter::evaluate.

pub fn e() -> Self

Returns the mathematical constant e (Euler’s number) as a symbolic parameter.

The symbol "e" is resolved to std::f64::consts::E automatically inside Parameter::evaluate.

pub fn pow(&self, exp: impl Into<Self>) -> Self

Returns a new parameter representing self raised to the power exp.

Examples

use cqlib_core::circuit::Parameter;

let x   = Parameter::symbol("x");
let x3  = x.pow(Parameter::from(3.0));   // x³
let val = x3.evaluate(&Some([("x", 2.0)].iter().cloned().collect())).unwrap();
assert!((val - 8.0).abs() < 1e-10);

pub fn replace(&self, symbol: &str, param: impl Into<Self>) -> Self

Substitutes every occurrence of symbol in this expression with param, returning the resulting expression. The inserted expression is not visited again; the original is unchanged.

Examples

use cqlib_core::circuit::Parameter;

let expr     = Parameter::symbol("θ") * Parameter::from(2.0);  // θ * 2
let replaced = expr.replace("θ", Parameter::pi());      // π * 2
let val      = replaced.evaluate(&None).unwrap();
assert!((val - 2.0 * std::f64::consts::PI).abs() < 1e-10);

pub fn as_symbol(&self) -> Option<String>

Returns the symbol name if this parameter is exactly one free symbol.

This is intentionally conservative: expressions containing one symbol are accepted only when they are structurally equal to that symbol after optional simplification.

pub fn substitute_many(&self, bindings: &HashMap<String, Parameter>) -> Self

Simultaneously substitutes bound symbols and simplifies when possible.

Replacement expressions are inserted as-is, without applying other bindings to them. The result is independent of binding iteration order, and the original expression is unchanged.

pub fn provably_equal(&self, other: &Self, tolerance: f64) -> bool

Returns whether two parameters are provably equal within tolerance.

This is a conservative symbolic check. It accepts structural equality after simplification and concrete numeric equality, but it does not try to prove arbitrary symbolic identities.

pub fn provably_equal_modulo( &self, other: &Self, modulus: &Self, tolerance: f64, ) -> bool

Returns whether two parameters are provably equal modulo modulus.

Fully numeric parameters take a fast path with plain floating-point math, without building or simplifying a symbolic difference expression. Only expressions with unbound symbols fall back to the symbolic path, where the expression difference and modulus must both evaluate without extra bindings for the numeric modulo check to apply.

pub fn is_constant(&self) -> bool

Returns true if this parameter is a constant (has no free variables).

Examples

use cqlib_core::circuit::Parameter;

let constant = Parameter::from(3.14);
assert!(constant.is_constant());

let symbolic = Parameter::symbol("x");
assert!(!symbolic.is_constant());

pub fn is_zero(&self) -> bool

Returns true if this parameter evaluates to zero.

Returns false if the parameter cannot be evaluated (contains unbound symbols).

Examples

use cqlib_core::circuit::Parameter;

let zero = Parameter::from(0.0);
assert!(zero.is_zero());

let non_zero = Parameter::from(1.0);
assert!(!non_zero.is_zero());

pub fn is_one(&self) -> bool

Returns true if this parameter evaluates to one.

Returns false if the parameter cannot be evaluated (contains unbound symbols).

Examples

use cqlib_core::circuit::Parameter;

let one = Parameter::from(1.0);
assert!(one.is_one());

let non_one = Parameter::from(2.0);
assert!(!non_one.is_one());

pub fn sinh(&self) -> Self

Returns the hyperbolic sine sinh(x).

pub fn cosh(&self) -> Self

Returns the hyperbolic cosine cosh(x).

pub fn tanh(&self) -> Self

Returns the hyperbolic tangent tanh(x).

pub fn floor(&self) -> Self

Returns the floor of the expression.

pub fn ceil(&self) -> Self

Returns the ceiling of the expression.

pub fn round(&self) -> Self

Returns the rounded value of the expression.

Trait Implementations

impl Add for Parameter

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: Parameter) -> Self::Output

Performs the + operation.

impl<'a> Add<&'a Parameter> for Parameter

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: &'a Parameter) -> Self::Output

Performs the + operation.

impl<'a, 'b> Add<&'b Parameter> for &'a Parameter

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: &'b Parameter) -> Self::Output

Performs the + operation.

impl Add<Parameter> for f64

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: Parameter) -> Self::Output

Performs the + operation.

impl Add<Parameter> for f32

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: Parameter) -> Self::Output

Performs the + operation.

impl Add<Parameter> for i32

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: Parameter) -> Self::Output

Performs the + operation.

impl Add<Parameter> for u32

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: Parameter) -> Self::Output

Performs the + operation.

impl<'a> Add<Parameter> for &'a Parameter

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: Parameter) -> Self::Output

Performs the + operation.

impl Add<f32> for Parameter

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: f32) -> Self::Output

Performs the + operation.

impl Add<f64> for Parameter

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: f64) -> Self::Output

Performs the + operation.

impl Add<i32> for Parameter

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: i32) -> Self::Output

Performs the + operation.

impl Add<u32> for Parameter

type Output = Parameter

The resulting type after applying the + operator.

fn add(self, rhs: u32) -> Self::Output

Performs the + operation.

impl Clone for Parameter

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Parameter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Parameter

fn default() -> Self

Creates a default parameter representing the integer 0.

impl Display for Parameter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the parameter as a human-readable mathematical string.

impl Div for Parameter

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: Parameter) -> Self::Output

Performs the / operation.

impl<'a> Div<&'a Parameter> for Parameter

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: &'a Parameter) -> Self::Output

Performs the / operation.

impl<'a, 'b> Div<&'b Parameter> for &'a Parameter

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: &'b Parameter) -> Self::Output

Performs the / operation.

impl Div<Parameter> for f64

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: Parameter) -> Self::Output

Performs the / operation.

impl Div<Parameter> for f32

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: Parameter) -> Self::Output

Performs the / operation.

impl Div<Parameter> for i32

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: Parameter) -> Self::Output

Performs the / operation.

impl Div<Parameter> for u32

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: Parameter) -> Self::Output

Performs the / operation.

impl<'a> Div<Parameter> for &'a Parameter

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: Parameter) -> Self::Output

Performs the / operation.

impl Div<f32> for Parameter

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: f32) -> Self::Output

Performs the / operation.

impl Div<f64> for Parameter

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: f64) -> Self::Output

Performs the / operation.

impl Div<i32> for Parameter

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: i32) -> Self::Output

Performs the / operation.

impl Div<u32> for Parameter

type Output = Parameter

The resulting type after applying the / operator.

fn div(self, rhs: u32) -> Self::Output

Performs the / operation.

impl Eq for Parameter

impl From<&Parameter> for ParameterValue

fn from(para: &Parameter) -> Self

Converts to this type from the input type.

impl From<&ParameterValue> for Parameter

fn from(para: &ParameterValue) -> Parameter

Converts to this type from the input type.

impl From<Expr> for Parameter

fn from(expr: Expr) -> Self

Converts to this type from the input type.

impl From<Parameter> for ParameterValue

fn from(para: Parameter) -> Self

Converts a Parameter into a ParameterValue.

It attempts to eagerly evaluate the parameter if it represents a known constant (like Pi, E, or a simple number) to optimize storage.

impl From<Parameter> for Expr

fn from(p: Parameter) -> Self

Converts to this type from the input type.

impl From<ParameterValue> for Parameter

fn from(para: ParameterValue) -> Parameter

Converts to this type from the input type.

impl From<f32> for Parameter

fn from(value: f32) -> Self

Converts to this type from the input type.

impl From<f64> for Parameter

fn from(value: f64) -> Self

Converts to this type from the input type.

impl From<i32> for Parameter

fn from(value: i32) -> Self

Converts to this type from the input type.

impl From<u32> for Parameter

fn from(value: u32) -> Self

Converts to this type from the input type.

impl FromStr for Parameter

fn from_str(expr: &str) -> Result<Self, Self::Err>

Parses a symbolic expression from a string.

Returns ParameterError::ParseError if the string cannot be parsed as a valid expression.

Examples

use cqlib_core::circuit::Parameter;
use std::str::FromStr;

let p = Parameter::from_str("θ * 2 + π").unwrap();
let bad = Parameter::from_str("@@@");
assert!(bad.is_err());

type Err = ParameterError

The associated error which can be returned from parsing.

impl Hash for Parameter

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Mul for Parameter

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: Parameter) -> Self::Output

Performs the * operation.

impl<'a> Mul<&'a Parameter> for Parameter

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: &'a Parameter) -> Self::Output

Performs the * operation.

impl<'a, 'b> Mul<&'b Parameter> for &'a Parameter

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: &'b Parameter) -> Self::Output

Performs the * operation.

impl Mul<Parameter> for f64

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: Parameter) -> Self::Output

Performs the * operation.

impl Mul<Parameter> for f32

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: Parameter) -> Self::Output

Performs the * operation.

impl Mul<Parameter> for i32

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: Parameter) -> Self::Output

Performs the * operation.

impl Mul<Parameter> for u32

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: Parameter) -> Self::Output

Performs the * operation.

impl<'a> Mul<Parameter> for &'a Parameter

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: Parameter) -> Self::Output

Performs the * operation.

impl Mul<f32> for Parameter

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Self::Output

Performs the * operation.

impl Mul<f64> for Parameter

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: f64) -> Self::Output

Performs the * operation.

impl Mul<i32> for Parameter

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: i32) -> Self::Output

Performs the * operation.

impl Mul<u32> for Parameter

type Output = Parameter

The resulting type after applying the * operator.

fn mul(self, rhs: u32) -> Self::Output

Performs the * operation.

impl Neg for Parameter

type Output = Parameter

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl Neg for &Parameter

type Output = Parameter

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl PartialEq for Parameter

fn eq(&self, other: &Self) -> bool

Checks equality based on the underlying expression structure.

Note: This performs structural equality of the AST, not semantic mathematical equality. For example, x + y and y + x are structurally different and will compare as unequal.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Sub for Parameter

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: Parameter) -> Self::Output

Performs the - operation.

impl<'a> Sub<&'a Parameter> for Parameter

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: &'a Parameter) -> Self::Output

Performs the - operation.

impl<'a, 'b> Sub<&'b Parameter> for &'a Parameter

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: &'b Parameter) -> Self::Output

Performs the - operation.

impl Sub<Parameter> for f64

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: Parameter) -> Self::Output

Performs the - operation.

impl Sub<Parameter> for f32

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: Parameter) -> Self::Output

Performs the - operation.

impl Sub<Parameter> for i32

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: Parameter) -> Self::Output

Performs the - operation.

impl Sub<Parameter> for u32

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: Parameter) -> Self::Output

Performs the - operation.

impl<'a> Sub<Parameter> for &'a Parameter

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: Parameter) -> Self::Output

Performs the - operation.

impl Sub<f32> for Parameter

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: f32) -> Self::Output

Performs the - operation.

impl Sub<f64> for Parameter

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: f64) -> Self::Output

Performs the - operation.

impl Sub<i32> for Parameter

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: i32) -> Self::Output

Performs the - operation.

impl Sub<u32> for Parameter

type Output = Parameter

The resulting type after applying the - operator.

fn sub(self, rhs: u32) -> Self::Output

Performs the - operation.

impl TryFrom<&str> for Parameter

fn try_from(expr: &str) -> Result<Self, Self::Error>

Parses a symbolic expression from a string slice.

Returns ParameterError::ParseError if the string cannot be parsed as a valid expression.

Examples

use cqlib_core::circuit::Parameter;

let p = Parameter::try_from("θ * 2 + π").unwrap();
let bad = Parameter::try_from("@@@");
assert!(bad.is_err());

type Error = ParameterError

The type returned in the event of a conversion error.