Crate mdmath_core

Expand description

Core multidimensional mathematics library.

§🧮 mdmath_core

Fundamental multidimensional mathematics for computer graphics and scientific computing

A high-performance, type-safe mathematics library providing essential vector operations and geometric primitives. Built specifically for computer graphics applications with support for n-dimensional vector spaces and optimized operations.

§✨ Features

§🔢 Vector Operations

Dot Product - Efficient vector dot product calculations
Magnitude & Normalization - Vector length and unit vector operations
Projection - Project vectors onto other vectors
Angular Calculations - Compute angles between vectors
Orthogonality Testing - Check perpendicular relationships
Dimension Handling - N-dimensional vector support

§🛠️ Memory Management

Zero-Copy Operations - Efficient slice and tuple conversions
Mutable References - Safe in-place vector modifications
Iterator Support - Standard Rust iteration patterns
Type Safety - Compile-time guarantees for vector operations

§🚀 Performance

SIMD Optimization - Vectorized operations where possible
Stack Allocation - Minimal heap usage for small vectors
Generic Implementation - Works with any numeric type

§📦 Installation

Add to your Cargo.toml:

mdmath_core = { workspace = true }

Or with specific features:

mdmath_core = { workspace = true, features = ["full"] }

§🚀 Quick Start

§Basic Vector Operations

use mdmath_core::vector;

fn main() {
  // Create vectors as arrays
  let vec_a = [1.0, 2.0, 3.0];
  let vec_b = [4.0, 5.0, 6.0];
  
  // Dot product
  let dot_result = vector::dot(&vec_a, &vec_b);
  println!("Dot product: {}", dot_result); // 32.0
  
  // Vector magnitude
  let magnitude: f32 = vector::mag2(&vec_a);
  let magnitude = magnitude.sqrt();
  println!("Magnitude: {}", magnitude); // ~3.74
  
  // Normalize vector
  let mut normalized = vec_a;
  vector::normalize(&mut normalized, &vec_a);
  println!("Normalized: {:?}", normalized);
}

§Advanced Vector Operations

use mdmath_core::vector;
use approx::assert_ulps_eq;

fn advanced_example() {
  // Vector projection
  let mut vec_a = [1.0, 2.0, 3.0];
  let vec_b = [4.0, 5.0, 6.0];
  vector::project_on(&mut vec_a, &vec_b);
  
  // Angle between vectors
  let vec_x = [1.0, 0.0];
  let vec_y = [0.0, 1.0];
  let angle = vector::angle(&vec_x, &vec_y);
  assert_ulps_eq!(angle, std::f32::consts::FRAC_PI_2);
  
  // Check orthogonality
  let is_orthogonal = vector::is_orthogonal(&vec_x, &vec_y);
  assert!(is_orthogonal);
}

§📖 API Reference

§Core Functions

Function	Description	Example
`dot(a, b)`	Compute dot product	`vector::dot(&[1,2], &[3,4])`
`mag2(v)`	Squared magnitude	`vector::mag2(&[3,4])` → `25.0`
`normalize(dst, src)`	Normalize vector	`vector::normalize(&mut v, &src)`
`project_on(a, b)`	Project a onto b	`vector::project_on(&mut a, &b)`
`angle(a, b)`	Angle between vectors	`vector::angle(&a, &b)`
`is_orthogonal(a, b)`	Check perpendicularity	`vector::is_orthogonal(&a, &b)`

§Features

Enable additional functionality:

mdmath_core = { workspace = true, features = ["full", "approx", "arithmetics"] }

full - All features enabled
approx - Floating-point comparison utilities
arithmetics - Advanced arithmetic operations
nd - N-dimensional array support

§🎯 Use Cases

Computer Graphics - 3D transformations and lighting calculations
Game Development - Physics simulations and collision detection
Scientific Computing - Mathematical modeling and analysis
Machine Learning - Vector operations for neural networks
Robotics - Spatial calculations and motion planning

§⚡ Performance

mdmath_core is designed for high-performance applications:

Zero-allocation operations on stack arrays
Generic implementations work with any numeric type
Optimized for common vector sizes (2D, 3D, 4D)
SIMD optimizations where available

Modules§

approx: Approximate equality for floating-point types can be determined using either relative difference or comparisons based on units in the last place (ULPs). Approximate equality for floating-point types can be determined using either relative difference or comparisons based on units in the last place (ULPs).
exposed: Exposed namespace of the module.
float: Describe general floats and operations on them. Describe general floats and operations on them.
general: General math traits. General math traits for handling zero-related operations.
index: Multidimensional indices. Provides functionality for converting various types into multidimensional indices. This module is particularly useful for operations involving multidimensional arrays or grids.
nd: Reusing nd_array. Provides functionality for converting various types into multidimensional indices. This module is particularly useful for operations involving multidimensional arrays or grids.
orphan: Orphan namespace of the module.
own: Own namespace of the module.
plain: Strides for plain multidemnsional space. Provides functionality for converting multidimensional indices into flat offsets, particularly useful for operations involving multidimensional arrays or grids.
prelude: Prelude to use essentials: use my_module::prelude::*.
traits: General traits, not necessarily special for math.
vector: Univeral vector. Provides traits and implementations for working with vectors and collections of scalars. This module is useful for operations that require fixed-size arrays and compile-time length information.

Macros§

abs_diff_eq: Approximate equality of using the absolute difference.
abs_diff_ne: Approximate inequality of using the absolute difference.
assert_abs_diff_eq: An assertion that delegates to abs_diff_eq!, and panics with a helpful error on failure.
assert_abs_diff_ne: An assertion that delegates to abs_diff_ne!, and panics with a helpful error on failure.
assert_relative_eq: An assertion that delegates to relative_eq!, and panics with a helpful error on failure.
assert_relative_ne: An assertion that delegates to relative_ne!, and panics with a helpful error on failure.
assert_ulps_eq: An assertion that delegates to ulps_eq!, and panics with a helpful error on failure.
assert_ulps_ne: An assertion that delegates to ulps_ne!, and panics with a helpful error on failure.
relative_eq: Approximate equality using both the absolute difference and relative based comparisons.
relative_ne: Approximate inequality using both the absolute difference and relative based comparisons.
ulps_eq: Approximate equality using both the absolute difference and ULPs (Units in Last Place).
ulps_ne: Approximate inequality using both the absolute difference and ULPs (Units in Last Place).

Structs§

AbsDiff: The requisite parameters for testing for approximate equality using a absolute difference based comparison.
Relative: The requisite parameters for testing for approximate equality using a relative based comparison.
Ulps: The requisite parameters for testing for approximate equality using an ULPs based comparison.

Traits§

AbsDiffEq: Equality that is defined using the absolute difference of two numbers.
ArrayMut: A trait for accessing a mutable reference to a fixed-size array from a collection.
ArrayRef: A trait for accessing a reference to a fixed-size array from a collection.
AsIx2: Trait for converting a type into a 2-dimensional index (Ix2).
AsIx3: Trait for converting a type into a 3-dimensional index (Ix3).
Collection: A trait for collections of scalars.
ConstLength: A trait implemented for entities with known length at compile-time.
Float: Generic trait for floating point numbers
IntoArray: The IntoArray trait is used to convert a collection into a fixed-size array.
NdFloat: Floating-point element types f32 and f64.
RelativeEq: Equality comparisons between two numbers using both the absolute difference and relative based comparisons.
ToRef: Trait for converting a value, reference, or mutable reference to an immutable reference.
ToValue: Trait for obtaining a value from a reference or mutable reference.
UlpsEq: Equality comparisons between two numbers using both the absolute difference and ULPs (Units in Last Place) based comparisons.
VectorIter: Trait to get iterator over elements of a vector. Should be implemented even for scalars.
VectorIterMut: Trait to get iterator over elements of a vector.
VectorIterator: Trait that encapsulates an vector elements iterator with specific characteristics and implemetning CloneDyn.
VectorIteratorRef: Trait that encapsulates an vector elements iterator with specific characteristics and implemetning CloneDyn.
VectorWithLength: A trait indicate that entity in case of referencing it can be interpreted as such having specified length LEN.
VectorWithLengthMut: A trait indicate that entity in case of mutable referencing it can be interpreted as such having specified length LEN.

Functions§

Ix0: Create a zero-dimensional index
Ix1: Create a one-dimensional index
Ix2: Create a two-dimensional index
Ix3: Create a three-dimensional index
Ix4: Create a four-dimensional index
Ix5: Create a five-dimensional index
Ix6: Create a six-dimensional index

Type Aliases§

Ix: Array index type
Ix0: zero-dimensionial
Ix1: one-dimensional
Ix2: two-dimensional
Ix3: three-dimensional
Ix4: four-dimensional
Ix5: five-dimensional
Ix6: six-dimensional

Crate mdmath_coreCopy item path