Trait FpScalar

Source

pub trait FpScalar:
    Sized
    + Clone
    + Send
    + Sync
    + Debug
    + Display
    + IntoInner<InnerType: RawScalarTrait>
    + PartialEq
    + Arithmetic
    + Abs<Output = Self::RealType>
    + Sqrt
    + PowIntExponent<RawType = Self::InnerType>
    + TrigonometricFunctions
    + HyperbolicFunctions
    + LogarithmFunctions
    + Exp
    + Zero
    + One
    + FpChecks
    + Neg<Output = Self>
    + MulAddRef
    + Reciprocal
    + NeumaierAddable
    + RandomSampleFromF64
    + 'static {
    type Kind: Sealed;
    type RealType: RealScalar<RealType = Self::RealType>;
}

Expand description

§Core trait for a floating-point scalar number (real or complex)

FpScalar is a fundamental trait in num-valid that provides a common interface for all floating-point scalar types, whether they are real or complex, and regardless of their underlying numerical kernel (e.g., native f64 or arbitrary-precision rug types).

This trait serves as a primary bound for generic functions and structures that need to operate on scalar values capable of floating-point arithmetic. It aggregates a large number of mathematical function traits (e.g., Sin, Cos, Exp, Sqrt) and core properties.

§Key Responsibilities and Associated Types:

Scalar Kind (FpScalar::Kind): This associated type specifies the fundamental nature of the scalar, which can be either scalar_kind::Real or scalar_kind::Complex. It is bound by the private, sealed trait scalar_kind::Sealed. This design enforces mutual exclusion: since a type can only implement FpScalar once, it can only have one Kind, making it impossible for a type to be both a RealScalar and a ComplexScalar simultaneously.
Real Type Component (FpScalar::RealType): Specifies the real number type corresponding to this scalar via RealType.
- For real scalars (e.g., f64, RealNative64StrictFinite, RealNative64StrictFiniteInDebug, RealRugStrictFinite, etc.), FpScalar::RealType is Self.
- For complex scalars (e.g., num::Complex<f64>, ComplexNative64StrictFinite, ComplexNative64StrictFiniteInDebug, ComplexRugStrictFinite, etc.), FpScalar::RealType is their underlying real component type (e.g., f64, RealNative64StrictFinite, RealNative64StrictFiniteInDebug, RealRugStrictFinite, etc.).
Crucially, this FpScalar::RealType is constrained to implement RealScalar, ensuring consistency.
Core Floating-Point Properties: FpScalar requires implementations of the trait FpChecks, which provides fundamental floating-point checks:
- is_finite(): Checks if the number is finite.
- is_infinite(): Checks if the number is positive or negative infinity.
- is_nan(): Checks if the number is “Not a Number”.
- is_normal(): Checks if the number is a normal (not zero, subnormal, infinite, or NaN).

§Trait Bounds:

FpScalar itself has several important trait bounds:

Sized + Clone + Debug + Display + PartialEq: Standard utility traits. Note that scalar types are Clone but not necessarily Copy.
Zero + One: From num_traits, ensuring the type has additive and multiplicative identities.
Neg<Output = Self>: Ensures the type can be negated.
Arithmetic: A custom aggregate trait in num-validthat bundles standard arithmetic operator traits (like Add, Sub, Mul, Div).
RandomSampleFromF64: Allows the type to be randomly generated from any distribution that produces f64, integrating with the rand crate.
Send + Sync + 'static: Makes the scalar types suitable for use in concurrent contexts.
A comprehensive suite of mathematical function traits like Sin, Cos, Exp, Ln, Sqrt, etc.

§Relationship to Other Traits:

RealScalar: A sub-trait of FpScalar for real numbers, defined by the constraint FpScalar<Kind = scalar_kind::Real>.
ComplexScalar: A sub-trait of FpScalar for complex numbers, defined by the constraint FpScalar<Kind = scalar_kind::Complex>.
NumKernel: Policies like StrictFinitePolicy are used to validate the raw values that are wrapped inside types implementing FpScalar.

§Example: Generic Function

Here is how you can write a generic function that works with any scalar type implementing FpScalar.

use num_valid::{FpScalar, functions::{MulAddRef, Sqrt}};
use num::Zero;

// This function works with any FpScalar type.
fn norm_and_sqrt<T: FpScalar>(a: T, b: T) -> T {
    let val = a.clone().mul_add_ref(&a, &b.pow(2)); // a*a + b*b
    val.sqrt()
}

// Also this function works with any FpScalar type.
fn multiply_if_not_zero<T: FpScalar>(a: T, b: T) -> T {
    if !a.is_zero() && !b.is_zero() {
        a * b
    } else {
        T::zero()
    }
}

Required Associated Types§

Source

type Kind: Sealed

The kind of scalar this is, e.g., Real or Complex. This is a sealed trait to prevent external implementations.

Source

type RealType: RealScalar<RealType = Self::RealType>

The real number type corresponding to this scalar.

For real scalars (e.g., f64), RealType is Self.
For complex scalars (e.g., Complex<f64>), RealType is their underlying real component type (e.g., f64).

This RealType is guaranteed to implement RealScalar and belong to the same numerical kernel as Self.