Merge pull request #376 from marvin-hansen/main

feat(deep_causality_num): Added new Quaternion type accompanied by a comprehensive suite.

Author: marvin-hansen

deep_causality_num/README.md

@@ -33,6 +33,11 @@ Custom numerical traits with default implementation for the [DeepCausality proje
 
 This crate provides a reduced custom implementation of the `rust-num` main traits with the following properties:
 
+### Implemented Types
+
+*   `Complex`
+*   `Quaternion`
+
 * Zero external dependencies
 * Zero unsafe
 * Minimal macros (only used for testing)

deep_causality_num/src/alias/mod.rs

@@ -0,0 +1,4 @@
+//! This module defines common type aliases used throughout the crate.
+
+pub type Vector3<F> = [F; 3];
+pub type Matrix3<F> = [[F; 3]; 3];

deep_causality_num/src/complex/mod.rs

@@ -21,6 +21,13 @@ mod num_cast;
 mod part_ord;
 mod to_primitive;
 
+/// A trait for types that represent complex numbers.
+///
+/// This trait defines the fundamental operations and properties expected of a complex number,
+/// such as accessing its real and imaginary parts, computing its magnitude and argument,
+/// and calculating its conjugate.
+///
+/// Implementors of this trait are expected to provide these operations for a generic float type `F`.
 pub trait ComplexNumber<F>: Sized
 where
     F: Float,
@@ -37,25 +44,117 @@ where
         + Clone,
 {
     /// Returns the real part of the complex number.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use deep_causality_num::{Complex, ComplexNumber};
+    ///
+    /// let c = Complex::new(3.0, 4.0);
+    /// assert_eq!(c.re(), 3.0);
+    /// ```
     fn re(&self) -> F;
 
     /// Returns the imaginary part of the complex number.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use deep_causality_num::{Complex, ComplexNumber};
+    ///
+    /// let c = Complex::new(3.0, 4.0);
+    /// assert_eq!(c.im(), 4.0);
+    /// ```
     fn im(&self) -> F;
 
     /// Computes the squared norm (magnitude squared) of the complex number.
+    ///
+    /// For a complex number `z = a + bi`, the squared norm is `a^2 + b^2`.
+    /// This method avoids the square root operation, making it more efficient
+    /// when only relative magnitudes are needed.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use deep_causality_num::{Complex, ComplexNumber};
+    ///
+    /// let c = Complex::new(3.0, 4.0);
+    /// assert_eq!(c.norm_sqr(), 25.0);
+    /// ```
     fn norm_sqr(&self) -> F;
 
     /// Computes the norm (magnitude or absolute value) of the complex number.
+    ///
+    /// For a complex number `z = a + bi`, the norm is `sqrt(a^2 + b^2)`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use deep_causality_num::{Complex, ComplexNumber};
+    ///
+    /// let c = Complex::new(3.0, 4.0);
+    /// assert_eq!(c.norm(), 5.0);
+    /// ```
     fn norm(&self) -> F;
 
     /// Computes the argument (phase angle) of the complex number.
+    ///
+    /// The argument is the angle `theta` such that `z = r * (cos(theta) + i * sin(theta))`, where `r` is the norm.
+    /// It is typically in the range `(-PI, PI]`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use deep_causality_num::{Complex, ComplexNumber};
+    /// use std::f64::consts::FRAC_PI_4;
+    ///
+    /// let c = Complex::new(1.0, 1.0);
+    /// assert!((c.arg() - FRAC_PI_4).abs() < 1e-9);
+    /// ```
     fn arg(&self) -> F;
 
     /// Computes the complex conjugate of the complex number.
+    ///
+    /// For a complex number `z = a + bi`, the conjugate is `a - bi`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use deep_causality_num::{Complex, ComplexNumber};
+    ///
+    /// let c = Complex::new(3.0, 4.0);
+    /// let conj_c = c.conj();
+    /// assert_eq!(conj_c.re(), 3.0);
+    /// assert_eq!(conj_c.im(), -4.0);
+    /// ```
     fn conj(&self) -> Self;
 }
 
 /// Represents a complex number with real and imaginary parts.
+///
+/// A complex number is a number that can be expressed in the form `a + bi`,
+/// where `a` and `b` are real numbers, and `i` is the imaginary unit,
+/// satisfying the equation `i^2 = -1`.
+///
+/// The `Complex` struct is generic over a float type `F`, allowing it to work
+/// with different floating-point precisions (e.g., `f32` or `f64`).
+///
+/// # Fields
+///
+/// * `re`: The real part of the complex number.
+/// * `im`: The imaginary part of the complex number.
+///
+/// # Examples
+///
+/// ```
+/// use deep_causality_num::Complex;
+///
+/// let c1 = Complex::new(1.0, 2.0); // Represents 1.0 + 2.0i
+/// let c2 = Complex { re: 3.0, im: -1.0 }; // Represents 3.0 - 1.0i
+///
+/// assert_eq!(c1.re, 1.0);
+/// assert_eq!(c2.im, -1.0);
+/// ```
 #[derive(Copy, Clone, PartialEq, Default)]
 pub struct Complex<F>
 where

deep_causality_num/src/lib.rs

@@ -1,12 +1,15 @@
+mod alias;
 mod cast;
 mod complex;
 pub mod float;
 mod float_option;
 mod identity;
 pub mod num;
 mod ops;
+mod quaternion;
 pub mod utils_tests;
 
+pub use crate::alias::{Matrix3, Vector3};
 pub use crate::cast::as_primitive::AsPrimitive;
 pub use crate::cast::as_scalar::float_as_scalar_impl::FloatAsScalar;
 pub use crate::cast::as_scalar::int_as_scalar_impl::IntAsScalar;
@@ -21,3 +24,4 @@ pub use crate::identity::one::{ConstOne, One};
 pub use crate::identity::zero::{ConstZero, Zero};
 pub use crate::num::Num;
 pub use crate::ops::num_ops::*;
+pub use crate::quaternion::Quaternion;