Module kernels 

Numerical Kernels and Validated Types

This module is the core of the numerical backend for the num-valid crate. It defines the fundamental traits, types, and operations for floating-point arithmetic.

Core Architecture

The architecture is built on three key concepts:

1. Raw Traits (RawScalarTrait, RawRealTrait, RawComplexTrait): These traits define the baseline contract for a “raw” number type (like f64 or rug::Float). They provide a comprehensive set of unchecked_* methods for arithmetic and mathematical functions. The “unchecked” prefix signifies that these methods do not perform any validation (e.g., for domain, finiteness, or division by zero) and are intended for internal use where validity has already been confirmed.

2. Validated Structs (RealValidated, ComplexValidated): These are wrapper types (newtypes) that enforce correctness. An instance of RealValidated<P> is guaranteed to hold a raw value that has been successfully validated against the policy P. All operations on these types (addition, sqrt, etc.) are designed to preserve this validity, either by returning a Result or by panicking on failure in debug builds.

3. Validation Policies (NumKernel): This trait allows the validation strategy to be generic. A kernel can be configured with different policies, such as NumKernelStrictFinite, which ensures all numbers are finite (not NaN or Infinity).

Available Kernels

The library provides concrete kernels that bundle these concepts:

• native64: Uses Rust’s standard f64 and num::Complex<f64> as the raw types. This is the default, high-performance kernel.

• rug (feature-gated): Uses arbitrary-precision types from the rug crate, ideal for high-precision scientific computing.

Re-exports

pub use crate::core::types::ComplexValidated;

pub use crate::core::types::RealValidated;

pub use crate::core::traits::raw::RawComplexTrait;

pub use crate::core::traits::raw::RawRealTrait;

pub use crate::core::traits::raw::RawScalarHyperbolic;

pub use crate::core::traits::raw::RawScalarPow;

pub use crate::core::traits::raw::RawScalarTrait;

pub use crate::core::traits::raw::RawScalarTrigonometric;

Structs

NumKernelStrictFinite

A strict finite kernel validation policy for raw real numbers. This policy ensures that the real numbers are finite and not NaN.

NumKernelStrictFiniteInDebug

A debug-only strict finite kernel validation policy for raw real numbers.