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.

Modules

native64

Native 64-bit Floating-Point Kernel

native64_validated

Validated Native 64-bit Kernel Types

rug

Structs

ComplexValidated

A validated complex number that is guaranteed to conform to a specific NumKernel.

NumKernelStrictFinite

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

NumKernelStrictFiniteInDebug

RealValidated

A validated real number that is guaranteed to conform to a specific NumKernel.

Traits

NumKernel

Defines a complete numerical kernel, acting as the central configuration point.

RawComplexTrait

A trait for raw complex scalar types, extending RawScalarTrait.

RawKernel

Defines the identity of a raw numerical kernel by associating its fundamental types.

RawRealTrait

A trait for raw real scalar types, extending RawScalarTrait with real-specific operations.

RawScalarTrait

A baseline trait for raw scalar types, defining core operations and properties.