Struct Da 

pub struct Da { /* private fields */ }

A truncated multivariate Taylor polynomial (“differential algebra” value).

Stored as a sparse list of (monomial index, coefficient) terms, sorted by ascending monomial index; the index packs the exponent vector into the canonical position determined by the active context.

Values created under one context keep working after init is called again (they hold on to their original context); mixing values from different contexts in one operation panics. See the crate-level Multithreading section for cross-thread use.

Implementations

impl Da

pub fn new() -> Da

The zero polynomial (also Da::default).

Panics

Panics with crate::DaceError if DACE has not been initialized.

pub fn constant(c: f64) -> Da

The constant polynomial c (daceCreateConstant); |c| <= eps gives the zero polynomial.

pub fn variable(var: u32) -> Da

The independent DA variable number var (1-based), i.e. the identity in that variable (daceCreateVariable).

Divergence from C: an out-of-range var logs a warning and returns the zero polynomial instead of raising C error 624.

pub fn identity(var: u32) -> Da

Alias of Da::variable (DA::identity in the C++ interface).

pub fn monomial(jj: &[u32], c: f64) -> Da

The polynomial consisting of the single monomial c * jj[0]^jj[1] * ... (daceCreateMonomial).

jj is padded with zeros or truncated to the number of DA variables (with a warning). Terms whose total order exceeds the maximum computation order, or with an exponent above it, are dropped with a warning (divergence from C, which encodes them as the constant term after raising error 622). |c| <= eps gives the zero polynomial.

pub fn random(cmu: f64) -> Da

A DA with randomly filled coefficients (daceCreateRandom).

cmu is the filling factor: |cmu| is the fraction of non-zero coefficients; cmu < 0 draws coefficients in [-1, 1], cmu > 0 weights them to decay exponentially with order from 1.0 towards the machine epsilon.

Divergence from C: the C library uses libc rand() (platform- and seed-dependent); this implementation uses a deterministic 64-bit LCG per thread, so results are reproducible everywhere.

pub fn cons(&self) -> f64

The constant part of the polynomial (daceGetConstant).

pub fn linear(&self) -> Vec<f64>

The linear coefficients, one per DA variable (daceGetLinear).

pub fn gradient(&self) -> Vec<Da>

The gradient: derivatives with respect to all DA variables (DA::gradient in the C++ interface).

pub fn size(&self) -> usize

The number of stored (non-zero) monomials (daceGetLength).

pub fn get_coefficient(&self, jj: &[u32]) -> f64

The coefficient of the monomial with exponents jj (daceGetCoefficient). jj is padded/truncated to the number of DA variables; invalid exponents return 0.0 with a warning.

pub fn set_coefficient(&mut self, jj: &[u32], c: f64)

Set the coefficient of the monomial with exponents jj (daceSetCoefficient): sets it, replaces it, or removes the monomial when |c| <= eps, keeping the term list sorted.

pub fn get_monomial(&self, pos: usize) -> Option<Monomial>

The monomial at 1-based position pos in the stored term list (DA::getMonomial in the C++ interface); None when out of range. The ordering is implementation-dependent.

pub fn iter_monomials(&self) -> impl Iterator<Item = Monomial> + '_

Iterate over all stored monomials, in stored order.

pub fn is_nan(&self) -> bool

Whether any coefficient is NaN (daceIsNan).

pub fn is_inf(&self) -> bool

Whether any coefficient is infinite (daceIsInf).

pub fn deriv(&self, var: u32) -> Da

Derivative with respect to independent variable var (1-based) (daceDifferentiate). Out-of-range variables warn and return zero.

pub fn deriv_vars(&self, vars: &[u32]) -> Da

Repeated derivative with respect to vars[0], then vars[1], …

pub fn integ(&self, var: u32) -> Da

Integral with respect to independent variable var (1-based) (daceIntegrate); the integration constant is zero. Out-of-range variables warn and return zero.

pub fn integ_vars(&self, vars: &[u32]) -> Da

Repeated integral with respect to vars[0], then vars[1], …

pub fn trim(&self, min_order: u32, max_order: u32) -> Da

Keep only terms of order between min_order and max_order inclusive (daceTrim).

pub fn minv(&self) -> Da

The multiplicative inverse 1/self (daceMultiplicativeInverse): direct alternating series below truncation order 5, Newton iteration above.

Panics

Panics with crate::DaceError code 641 (“Dividing by zero”) when the constant part of self is zero.

pub fn sqr(&self) -> Da

The square self * self (daceSquare).

pub fn divide_variable(&self, var: u32, p: u32) -> Da

Divide by var^p, when every monomial’s exponent in var is at least p (daceDivideByVariable): exact polynomial division on the exponents, coefficients unchanged. p == 0 returns a copy.

Out-of-range variables warn and return zero. Division is impossible when some exponent is too small (p > nomax, or the DA is non-zero with insufficient exponents).

Panics

Panics with crate::DaceError code 642 (“Inverse does not exists”) when the division is impossible on a non-zero DA.

pub fn multiply_monomials(&self, other: &Da) -> Da

Multiply with other monomial-by-monomial: the coefficient-wise product over matching monomial indices (daceMultiplyMonomials).

impl Da

pub fn exp(&self) -> Da

Method form of exp.

pub fn log(&self) -> Da

Method form of log.

pub fn log10(&self) -> Da

Method form of log10.

pub fn log2(&self) -> Da

Method form of log2.

pub fn sin(&self) -> Da

Method form of sin.

pub fn cos(&self) -> Da

Method form of cos.

pub fn tan(&self) -> Da

Method form of tan.

pub fn asin(&self) -> Da

Method form of asin.

pub fn acos(&self) -> Da

Method form of acos.

pub fn atan(&self) -> Da

Method form of atan.

pub fn sinh(&self) -> Da

Method form of sinh.

pub fn cosh(&self) -> Da

Method form of cosh.

pub fn tanh(&self) -> Da

Method form of tanh.

pub fn asinh(&self) -> Da

Method form of asinh.

pub fn acosh(&self) -> Da

Method form of acosh.

pub fn atanh(&self) -> Da

Method form of atanh.

pub fn erf(&self) -> Da

Method form of erf.

pub fn erfc(&self) -> Da

Method form of erfc.

pub fn sqrt(&self) -> Da

Method form of sqrt.

pub fn isrt(&self) -> Da

Method form of isrt.

pub fn cbrt(&self) -> Da

Method form of cbrt.

pub fn icrt(&self) -> Da

Method form of icrt.

pub fn powf(&self, p: f64) -> Da

Method form of powf.

pub fn powi(&self, np: i32) -> Da

Method form of powi.

pub fn root(&self, np: i32) -> Da

Method form of root.

pub fn log_base(&self, b: f64) -> Da

Method form of log_base.

pub fn hypot(&self, b: &Da) -> Da

Method form of hypot.

pub fn atan2(&self, x: &Da) -> Da

Method form of atan2.

pub fn modulo(&self, p: f64) -> Da

Method form of modulo.

pub fn trunc(&self) -> Da

Method form of trunc.

pub fn round(&self) -> Da

Method form of round.

impl Da

pub fn plug(&self, var: u32, val: f64) -> Da

Partial evaluation: replace independent variable var (1-based) by the value val (daceEvalVariable). Out-of-range variables warn and return zero.

pub fn replace_variable(&self, from: u32, to: u32, val: f64) -> Da

Replace independent variable from by val times independent variable to (daceReplaceVariable); from == to scales the variable by val. Out-of-range variables warn and return zero.

Divergence from C: the C implementation indexes its 0-based exponent array with the 1-based variable numbers, so it actually replaces variable from + 1 by val · (variable to + 1) and silently does nothing when from == nvmax. This implementation follows the documented (1-based) semantics instead.

pub fn scale_variable(&self, var: u32, val: f64) -> Da

Scale independent variable var by val: x_var -> val * x_var (daceScaleVariable). Out-of-range variables warn and return zero.

pub fn translate_variable(&self, var: u32, a: f64, c: f64) -> Da

Translate independent variable var to a*x + c (daceTranslateVariable). Out-of-range variables warn and return zero.

pub fn eval_monomials(&self, values: &Da) -> f64

Evaluate by providing the value of each monomial in values: the monomial-wise dot product of the two DAs (daceEvalMonomials).

pub fn eval(&self, args: &[f64]) -> f64

Evaluate at a point: compile and evaluate the tree, returning the first component (C++ DA::eval).

pub fn eval_da(&self, args: &[Da]) -> Da

Evaluate with DA arguments (contraction): substitute each argument DA for the corresponding variable.

pub fn compile(&self) -> CompiledDa

Compile into a reusable evaluation tree (C++ compiledDA).

impl Da

pub fn to_blob(&self) -> Vec<u8>

Export in the C binary blob format (daceExportBlob): magic, no, nv1, nv2, len as little-endian u32s, then len packed {i1, i2, cc} records. As in C, the buffer always includes one record slot (zeroed when the DA is empty).

All supported targets are little-endian, so blobs interoperate with the C library on the reference platforms.

pub fn from_blob(blob: &[u8]) -> Result<Da, DaceError>

Import from the C binary blob format (daceImportBlob): silently truncates orders above the current maximum computation order and any extra variables present, as in C.

Errors

Returns crate::DaceError code 631 (“Invalid data”) when the magic is wrong or the buffer is too short.

impl Da

pub fn abs(&self) -> f64

The absolute value (maximum coefficient norm) of the DA (daceAbsoluteValue).

pub fn norm(&self, ityp: NormType) -> f64

A norm of all coefficients (daceNorm).

pub fn order_norm(&self, var: u32, ityp: NormType) -> Vec<f64>

Order-sorted norms (daceOrderedNorm): one norm per order (var == 0, length nomax + 1) or per exponent of variable var (1-based, length nomax + 1).

Out-of-range variables log a warning and return all zeros.

pub fn estim_norm(&self, var: u32, ityp: NormType, nc: u32) -> Vec<f64>

Estimate order-sorted norms up to order nc by an exponential least-squares fit (daceEstimate): returns the estimates c[0..=nc].

If fewer than two orders have non-negligible norms, the fit is impossible; a warning is logged and zeros are returned (as in C, where this is informational).

Panics

Panics with crate::DaceError code 651 when nomax < 2.

pub fn estim_norm_err( &self, var: u32, ityp: NormType, nc: u32, ) -> (Vec<f64>, Vec<f64>)

Like Da::estim_norm, also returning the fit residuals per order (length min(nc, nomax) + 1).

pub fn bound(&self) -> Interval

An upper and lower bound of the DA over [-1, 1]^nv (daceGetBounds): monomials with all-even exponents contribute their signed coefficient to one side, others their absolute value to both.

pub fn conv_radius(&self, eps: f64, ityp: NormType) -> f64

Estimate the convergence radius: the radius at which the estimated norm of the next order falls below eps (C++ DA::convRadius).

impl Da

pub fn bessel_j(&self, n: i32) -> Da

Method form of bessel_j.

pub fn bessel_y(&self, n: i32) -> Da

Method form of bessel_y.

pub fn bessel_i(&self, n: i32, scaled: bool) -> Da

Method form of bessel_i.

pub fn bessel_k(&self, n: i32, scaled: bool) -> Da

Method form of bessel_k.

pub fn log_gamma(&self) -> Da

Method form of log_gamma.

pub fn gamma(&self) -> Da

Method form of gamma.

pub fn psi(&self, n: u32) -> Da

Method form of psi.

Trait Implementations

impl Add for Da

type Output = Da

The resulting type after applying the + operator.

fn add(self, rhs: Da) -> Da

Performs the + operation.

impl Add<Da> for f64

type Output = Da

The resulting type after applying the + operator.

fn add(self, rhs: Da) -> Da

Performs the + operation.

impl Add<f64> for Da

type Output = Da

The resulting type after applying the + operator.

fn add(self, rhs: f64) -> Da

Performs the + operation.

impl AddAssign for Da

fn add_assign(&mut self, rhs: Da)

Performs the += operation.

impl AddAssign<f64> for Da

fn add_assign(&mut self, rhs: f64)

Performs the += operation.

impl Clone for Da

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 Da

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

Formats the value using the given formatter.

impl Default for Da

fn default() -> Da

Returns the “default value” for a type.

impl Display for Da

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

Formats the value using the given formatter.

impl Div for Da

fn div(self, rhs: Da) -> Da

Panics

Panics with crate::DaceError code 641 when rhs has a zero constant part (division by zero), via the multiplicative inverse.

type Output = Da

The resulting type after applying the / operator.

impl Div<Da> for f64

type Output = Da

The resulting type after applying the / operator.

fn div(self, rhs: Da) -> Da

Performs the / operation.

impl Div<f64> for Da

fn div(self, rhs: f64) -> Da

Panics

Panics with crate::DaceError code 641 when rhs == 0.0.

type Output = Da

The resulting type after applying the / operator.

impl DivAssign for Da

fn div_assign(&mut self, rhs: Da)

Performs the /= operation.

impl DivAssign<f64> for Da

fn div_assign(&mut self, rhs: f64)

Performs the /= operation.

impl FromStr for Da

fn from_str(s: &str) -> Result<Da, DaceError>

Parse the text format emitted by Display (the daceRead parser, including its tolerance: line-number and order mismatches warn, order/truncation-excess rows are skipped, duplicate monomials accumulate).

Panics

Panics with crate::DaceError if DACE has not been initialized.

type Err = DaceError

The associated error which can be returned from parsing.

impl Mul for Da

type Output = Da

The resulting type after applying the * operator.

fn mul(self, rhs: Da) -> Da

Performs the * operation.

impl Mul<Da> for f64

type Output = Da

The resulting type after applying the * operator.

fn mul(self, rhs: Da) -> Da

Performs the * operation.

impl Mul<f64> for Da

type Output = Da

The resulting type after applying the * operator.

fn mul(self, rhs: f64) -> Da

Performs the * operation.

impl MulAssign for Da

fn mul_assign(&mut self, rhs: Da)

Performs the *= operation.

impl MulAssign<f64> for Da

fn mul_assign(&mut self, rhs: f64)

Performs the *= operation.

impl Neg for Da

type Output = Da

The resulting type after applying the - operator.

fn neg(self) -> Da

Performs the unary - operation.

impl Sub for Da

type Output = Da

The resulting type after applying the - operator.

fn sub(self, rhs: Da) -> Da

Performs the - operation.

impl Sub<Da> for f64

type Output = Da

The resulting type after applying the - operator.

fn sub(self, rhs: Da) -> Da

Performs the - operation.

impl Sub<f64> for Da

type Output = Da

The resulting type after applying the - operator.

fn sub(self, rhs: f64) -> Da

Performs the - operation.

impl SubAssign for Da

fn sub_assign(&mut self, rhs: Da)

Performs the -= operation.

impl SubAssign<f64> for Da

fn sub_assign(&mut self, rhs: f64)

Performs the -= operation.