avila-math

🏛️ The Foundation of Arxis

Mathematical kernel - The solid bedrock upon which Arxis (ARX + AXIS) is built

avila-math is the mathematical citadel - providing unshakeable foundations for the entire Avila ecosystem (vision, engine, arxis).

Like the ARX (Latin: fortress), this crate provides the solid mathematical primitives that protect the integrity of all computations.

✨ Features

🎯 Geometry

• 3D Quaternions (Quat3D): Rotations, SLERP interpolation, axis-angle
• Dual Quaternions (DualQuat): Rigid body transformations (rotation + translation)
• SO(4) Rotations: 4D rotations using S³ × S³ representation
• 4D Geometry: Tesseract, 24-cell, simplex, projections (4D→3D)
• AABB: Axis-aligned bounding boxes for collision detection

📊 Tensors & Linear Algebra

• Vectors: 2D, 3D, 4D with dot product, cross product, normalization
• Matrices: 3×3, 4×4 with multiplication, determinant, inverse, transpose
• N-D Tensors: Generalized tensor operations (convolution, pooling, etc.)
• Conv4D: 4D convolutional neural networks with forward/backward pass
• SIMD Optimizations: AVX2 accelerated operations
• In-place Operations: Zero-copy tensor manipulations

🔬 Advanced Linear Algebra

• SVD: Singular Value Decomposition
• Eigenvalues/Eigenvectors: Symmetric and general matrices
• QR Decomposition: Orthogonal factorization
• LU Decomposition: Lower-upper factorization
• Linear System Solvers: Direct and least-squares methods
• Matrix Rank & Condition Number: Numerical analysis tools

🌊 Signal Processing

• FFT: 1D, 2D, 3D, 4D Fast Fourier Transform
• Spectral Analysis: Power spectral density, spectrograms
• Wavelets: CWT, DWT for gravitational wave detection (LISA)
• Window Functions: Hann, Hamming, Blackman, Kaiser
• Cross-correlation: Signal comparison and alignment

∇ Calculus & Differential Operators (4D)

• Gradient: ∇f in 4D space
• Divergence: ∇·F for vector fields
• Curl: Generalized 4D curl (bivector)
• Laplacian: ∇²f for scalar fields
• D'Alembertian: Wave operator □ for relativity
• Hessian: Second-order derivatives
• Jacobian: Function vector derivatives
• Directional Derivatives: Rates along vectors

🎨 Interpolation (4D)

• Linear: lerp, bilinear, trilinear, quadrilinear
• Bézier Curves: Quadratic, cubic, arbitrary degree
• Cubic Splines: Natural and Catmull-Rom
• B-splines: Uniform basis splines
• Hermite Interpolation: Tangent-aware curves

🔧 Additional Features

• Serde Support: Serialize/deserialize tensors (feature flag)
• Benchmarks: Criterion-based performance testing
• Pure Rust: 100% native implementation
• Parallel Computing: Rayon for Conv4D operations

📦 Installation

[dependencies]
avila-math = { git = "https://github.com/avilaops/arxis", branch = "main" }

# With serialization support
avila-math = { git = "https://github.com/avilaops/arxis", branch = "main", features = ["serde"] }

🚀 Usage Examples

Quaternions & Rotations

use avila_math::geometry::Quat3D;
use std::f64::consts::PI;

// Create rotation quaternion
let q = Quat3D::from_axis_angle([0.0, 0.0, 1.0], PI / 2.0);

// Rotate vector
let v = q.rotate_vector([1.0, 0.0, 0.0]);
// v ≈ [0.0, 1.0, 0.0]

// SLERP interpolation
let q2 = Quat3D::from_axis_angle([0.0, 0.0, 1.0], PI);
let interpolated = q.slerp(&q2, 0.5);

Linear Algebra

use avila_math::linalg::{svd, eigenvalues, solve_linear_system};
use avila_math::tensor::{Matrix, Vector};

// SVD decomposition
let m = Matrix::from_data([3, 2], vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]).unwrap();
let (u, singular_values, vt) = svd(&m).unwrap();

// Eigenvalues
let symmetric = Matrix::from_data([2, 2], vec![2.0, 1.0, 1.0, 2.0]).unwrap();
let eigenvals = eigenvalues(&symmetric).unwrap();

// Solve Ax = b
let a = Matrix::from_data([2, 2], vec![2.0, 1.0, 1.0, 3.0]).unwrap();
let b = Vector::from_slice(&[5.0, 6.0]);
let x = solve_linear_system(&a, &b).unwrap();

Conv4D Neural Networks

use avila_math::tensor::{Conv4DLayer, Conv4DConfig, Tensor6D};

// Create 4D convolutional layer
let mut layer = Conv4DLayer::new(
    8,              // in_channels
    16,             // out_channels
    [3, 3, 3, 3],   // kernel_size
    Conv4DConfig::default()
).with_bias(16);

layer.init_xavier();

// Forward pass
let input = Tensor6D::zeros([2, 8, 16, 16, 16, 16]); // [batch, channels, d1, d2, d3, d4]
let output = layer.forward(&input).unwrap();

// Backward pass for training
let grad_output = Tensor6D::filled(output.shape, 0.1);
let (grad_input, grad_weights, grad_bias) = layer.backward(&input, &grad_output).unwrap();

Differential Calculus (4D)

use avila_math::calculus::{gradient_4d, laplacian_4d, divergence_4d};

// Scalar field: f(x,y,z,w) = x² + y² + z² + w²
let f = |p: &[f64]| p[0]*p[0] + p[1]*p[1] + p[2]*p[2] + p[3]*p[3];

// Gradient: ∇f = [2x, 2y, 2z, 2w]
let grad = gradient_4d(&f, &[1.0, 2.0, 3.0, 4.0], 1e-7);

// Laplacian: ∇²f = 8
let lap = laplacian_4d(&f, &[1.0, 2.0, 3.0, 4.0], 1e-5);

// Vector field divergence
let field = |p: &[f64; 4]| [p[0], p[1], p[2], p[3]];
let div = divergence_4d(&field, &[1.0, 2.0, 3.0, 4.0], 1e-5);

Interpolation & Curves

use avila_math::interpolation::{BezierCurve4D, cubic_spline_4d, catmull_rom_4d};

// Bézier curve
let control_points = vec![
    [0.0, 0.0, 0.0, 0.0],
    [1.0, 2.0, 0.0, 0.0],
    [2.0, 0.0, 0.0, 0.0],
];
let curve = BezierCurve4D::new(control_points);
let point = curve.eval(0.5);

// Cubic spline
let points = vec![
    [0.0, 0.0, 0.0, 0.0],
    [1.0, 1.0, 1.0, 1.0],
    [2.0, 0.0, 0.0, 0.0],
];
let interpolated = cubic_spline_4d(&points, 0.75);

🧪 Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific module
cargo test --lib tensor::

⚡ Benchmarks

# Run all benchmarks
cargo bench

# Run specific benchmark
cargo bench tensor_ops
cargo bench conv4d
cargo bench quaternions
cargo bench fft

📈 Performance

Optimized for Brazil/LATAM workloads with:

• AVX2 SIMD: 4x speedup on compatible CPUs
• Rayon Parallelism: Multi-core Conv4D operations
• Zero-copy: In-place tensor operations
• LTO Optimization: Link-time optimization in release builds

🏗️ Project Structure

avila-math/
├── src/
│   ├── geometry/        # Quaternions, 4D geometry
│   ├── tensor/          # N-D tensors, Conv4D
│   ├── signal/          # FFT, wavelets, spectral analysis
│   ├── linalg/          # SVD, eigenvalues, solvers
│   ├── calculus/        # Differential operators
│   └── interpolation/   # Curves and splines
├── benches/             # Criterion benchmarks
└── .github/workflows/   # CI/CD automation

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

🏛️ Part of Arxis

avila-math is the foundation stone of Arxis - the mathematical citadel.

ARX (fortress) + AXIS (engine) = ARXIS

Built with ❤️ by Avila

136 tests passing ✅ | 4 benchmarks ⚡ | Pure Rust 🦀