deep_causality_num 0.1.12

Number utils for for deep_causality crate.
Documentation

DeepCausality NUM types and traits

Crates.io Docs.rs MIT licensed Tests

Summary

A comprehensive numerical foundation library for the DeepCausality project. This crate provides:

  • Algebraic Traits: A complete hierarchy of abstract algebra structures (Magma → Monoid → Group → Ring → Field) with rigorous mathematical foundations
  • Cast Traits: Safe primitive type conversions (AsPrimitive, FromPrimitive, ToPrimitive, NumCast)
  • Identity Traits: Zero and One with const variants for compile-time evaluation
  • Float Types: Standard floating-point abstractions plus DoubleFloat for double-double precision arithmetic
  • Complex Types: Full implementations of Complex, Quaternion, and Octonion number systems

The implementation is macro-free, unsafe-free, and dependency-free (with optional libm for no-std float support). Compiles for std, no-std, and no-std without float.

Algebraic Traits

The algebra module provides a rigorous type-safe hierarchy of abstract algebraic structures:

Structure Description
Magma Set with a closed binary operation
Monoid Magma + associativity + identity
Group Monoid + inverses
Ring Abelian group + multiplicative monoid + distributivity
Field Commutative ring + multiplicative inverses
RealField Field + ordering + transcendental functions
Module Vector-like structure over a ring
Algebra Module with bilinear product
DivisionAlgebra Algebra with inverses (Complex, Quaternion, Octonion)

See Algebraic Traits Reference for the complete hierarchy diagram and mathematical documentation.

Integer Traits

Type-safe abstractions over Rust's primitive integer types, extending the Ring algebraic structure:

Trait Covers Key Operations
Integer All primitives Bit ops, checked/saturating/wrapping arithmetic, Euclidean division
SignedInt i8–i128, isize abs, signum, is_negative, checked_neg
UnsignedInt u8–u128, usize is_power_of_two, next_power_of_two

Float Types

Type Description Key Traits
Float Trait for f32 and f64 RealField, Field, Float
DoubleFloat High-precision (~31 digits) using double-double arithmetic RealField, Field, Float
FloatOption Abstracts over floats and their Option variants Utility trait for nullable numerics

Complex Types

Type Algebra Associative Commutative Key Traits
Complex Division Algebra ✅ ✅ Field, DivisionAlgebra, Rotation
Quaternion Division Algebra ✅ ❌ AssociativeRing, DivisionAlgebra, Rotation
Octonion Division Algebra ❌ ❌ DivisionAlgebra (non-associative)

Numerical Traits:

Cast Traits:

  • AsPrimitive
  • FloatAsScalar
  • IntAsScalar
  • FromPrimitive
  • ToPrimitive
  • NumCast
  • IntoFloat

General traits:

  • Num
  • NumOps

Identity traits:

  • One / OneConst
  • Zero / Zero Const

non-std support

The deep_causality_num crate provides support for no-std environments. This is particularly useful for embedded systems or other contexts where the standard library is not available. Note, the std feature is enabled by default thus you need to opt-into non-std via feature flags.

To use this crate in a no-std environment, you need to disable the default std feature and, if your application requires floating-point operations, enable the libm_math feature. The libm_math feature integrates the libm crate, which provides software implementations of floating-point math functions for no-std.

Cargo Build and Test for no-std

1. Building for no-std with Floating-Point Math:

To build the crate for no-std while including floating-point math support (via libm), use the following command:

cargo build --no-default-features --features libm_math -p deep_causality_num

2. Testing for no-std with Floating-Point Math:

To run tests in a no-std environment with floating-point math support, use:

cargo test --no-default-features --features libm_math -p deep_causality_num

There might be minor floating precision differences between std and non-std implementations that cause some tests to fail. If you encounter these, please submit a PR with a fix.

3. Building for no-std without Floating-Point Math (if not needed):

If your no-std application does not require floating-point operations, you can build without the libm_math feature:

cargo build --no-default-features -p deep_causality_num

4. Testing for no-std without Floating-Point Math (if not needed):

Similarly, to test without floating-point math functions:

cargo test --no-default-features -p deep_causality_num

However, this will cause about 138 tests because to fail since these tests are not configured for conditional test run because non-std without floating-point math is considered a corner case. If you need better support for this particular scenario, please open an issue.

Bazel Build

For regular (std) builds, run:

   bazel build //deep_causality_num/...

and

   bazel test //deep_causality_num/...

for tests. When you want to build for non-std, use

   bazel build --@rules_rust//rust/settings:no_std=alloc //deep_causality_num/...

and

   bazel test --@rules_rust//rust/settings:no_std=alloc //deep_causality_num/...

License

This project is licensed under the MIT license.

Security

For details about security, please read the security policy.

Author

  • Marvin Hansen.
  • Github GPG key ID: 369D5A0B210D39BC
  • GPG Fingerprint: 4B18 F7B2 04B9 7A72 967E 663E 369D 5A0B 210D 39BC