ftl-numkernel

ftl-numkernel is a comprehensive library designed to provide advanced numerical operations and error handling for both real and complex numbers. It leverages Rust's strong type system and error handling capabilities to ensure robust and reliable computations. The library includes traits and implementations for various mathematical functions, with support for both native floating-point types and arbitrary precision types provided by the rug library.

Key Features:

1. Error Handling:

   • The library defines detailed error types for various numerical operations, ensuring that invalid inputs and outputs are properly handled and reported.
   • Errors are categorized into input and output errors, with specific variants for different types of numerical issues such as division by zero, invalid values, and subnormal numbers.

2. Traits for Numerical Operations:

   • The library provides traits for common numerical operations and most of the trais include methods for performing the operation with and without validity checks, allowing for both safe and optimized computations.

3. Support for Real and Complex Numbers:

   • The library supports both real and complex numbers, with specific error types and validation logic for each.
   • Complex number operations are handled with care to ensure that both the real and imaginary parts are valid.

4. Arbitrary Precision Support:

   • Conditional compilation is used to provide support for arbitrary precision types from the rug library.
   • The support for arbitrary precision types, via the rug library is activated with the optional flag --features=rug.
   • This allows users to perform high-precision computations when needed, with the same robust error handling as native types.

5. Comprehensive Documentation:

   • The library includes detailed documentation for each trait, method, and error type, making it easy for users to understand and utilize the provided functionality.
   • Examples are provided for key functions to demonstrate their usage and expected behavior.

6. Extensibility:

   • The use of traits and generic types allows for easy extension of the library to support additional numerical types and operations.
   • The duplicate crate is used to reduce code redundancy and ensure consistent implementations across different types.

Compiler Requirement: Rust Nightly

This library currently requires the nightly branch of the Rust compiler, as it depends on the unstable feature error_generic_member_access, which is not yet available in stable or beta releases.

Note: This requirement is accurate at the time of writing (November 2024), but it may change if the feature error_generic_member_access becomes stable in the future. Once the feature is stabilized, this library should work on the stable Rust compiler as well.

To use this library with the nightly compiler, please run:

rustup install nightly
rustup override set nightly

This will set your environment to use the nightly compiler, enabling compatibility with the current version of the library.

Example Usage:

use ftl_numkernel::functions::Sqrt;

let x = 4.;
let sqrt_x = x.sqrt();
assert_eq!(sqrt_x, 2.0);

let y = -4.;
let sqrt_y = y.try_sqrt();
assert!(sqrt_y.is_err());

In this example, x.sqrt() computes the square root of x without checks (in Release mode), while y.try_sqrt() will perform checks (in Debug and Release mode) on the values of y before the computation of the square root (ensuring that the input value is finite, normal and non-negative) and after the computation of the square root (i.e., just before the result is returned and stored in sqrt_y), in order to ensure that the returned value is finite and normal. Since y is negative, the rust Err type will wrap an error in sqrt_y.

License

Copyright 2024, C.N.R. - Consiglio Nazionale delle Ricerche

Licensed under either of

• Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

License Notice for Optional Feature Dependencies (LGPL-3.0 Compliance)

If you enable the rug feature (with the optional flag --features=rug), this project will use the Rug library, which is licensed under the LGPL-3.0. Activating this feature may introduce LGPL-3.0 requirements to your project. Specifically, if you distribute a product that links with Rug, you may need to comply with the LGPL-3.0 license terms, which require the ability to replace or relink the Rug component by the end-user.

To avoid LGPL-3.0 obligations, you can use this library without enabling the rug feature, thereby excluding Rug as a dependency.