Module native64 

Native 64-bit Floating-Point Kernel

This module provides a numerical kernel implementation based on Rust’s native 64-bit floating-point numbers (f64) and complex numbers (num::Complex<f64>). It serves as the standard, high-performance double-precision backend for the num-valid library.

Purpose and Role

The primary role of this module is to act as a bridge between the abstract traits defined by num-valid (like RealScalar and ComplexScalar) and Rust’s concrete, hardware-accelerated numeric types. It adapts f64 and Complex<f64> so they can be used seamlessly in generic code written against the library’s traits.

f64 as a RealScalar

By implementing RealScalar for f64, this module makes Rust’s native float a “first-class citizen” in the num-validecosystem. This implementation provides concrete logic for all the operations required by RealScalar and its super-traits (e.g., FpScalar, Rounding, Sign, Constants). Most of these implementations simply delegate to the highly optimized methods available in Rust’s standard library (e.g., f64::sin, f64::sqrt).

This allows generic functions bounded by T: RealScalar to be instantiated with f64, leveraging direct CPU floating-point support for maximum performance.

Complex<f64> as a ComplexScalar

Similarly, this module implements ComplexScalar for num::Complex<f64>. This makes the standard complex number type from the num crate compatible with the num-validabstraction for complex numbers. It implements all required traits, including FpScalar, ComplexScalarGetParts, ComplexScalarSetParts, and ComplexScalarMutateParts, by delegating to the methods of num::Complex.

This enables generic code written against T: ComplexScalar to operate on Complex<f64> values, providing a performant backend for complex arithmetic.

Core Components

• Native64: A marker struct that implements the NumKernel trait. It is used in generic contexts to select this native kernel, specifying f64 as its Real type and num::Complex<f64> as its Complex type.
• Trait Implementations: This module is primarily composed of impl blocks that satisfy the contracts of core traits (FpScalar, RealScalar, ComplexScalar, Arithmetic, MulAddRef, etc.) for f64 and Complex<f64>.

Validation

It is crucial to understand that the base types f64 and Complex<f64> do not inherently enforce properties like finiteness (they can be NaN or Infinity).

The num-valid library introduces validation at the trait and wrapper level, not at the base type level. For instance, RealScalar::try_from_f64 for f64 uses a StrictFinitePolicy to ensure the input is finite before creating an instance. This design separates the raw, high-performance types from the validated, safer abstractions built on top of them.

For scenarios requiring types that are guaranteed to be valid by construction, consider using the validated wrappers from the native64_validated module.

Structs

Native64

Numerical kernel specifier for Rust’s native 64-bit floating-point types.