NumRS2 - High-Performance Numerical Computing for Rust

NumRS2 is a high-performance numerical computing library for Rust, designed as a Rust-native alternative to NumPy. It provides N-dimensional arrays, linear algebra operations, and comprehensive mathematical functions with a focus on performance, safety, and ease of use.

🚀 Version 0.1.0-beta.2 - This beta release includes significant performance optimizations through SciRS2-Core integration, providing SIMD acceleration, parallel processing, and adaptive algorithm selection. The API is stabilizing as we approach the 1.0 release.

✨ Architecture Highlights

🏗️ Enhanced Design

• Trait-based architecture for extensibility and generic programming
• Hierarchical error system with rich context and recovery suggestions
• Memory management with pluggable allocators (Arena, Pool, NUMA-aware)
• Comprehensive documentation with migration guides and best practices

🔧 Core Features

• N-dimensional arrays with efficient memory layout and broadcasting
• Advanced linear algebra with BLAS/LAPACK integration and matrix decompositions
• SIMD optimization with automatic vectorization and CPU feature detection
• Thread safety with parallel processing support via Rayon
• Python interoperability for easy migration from NumPy

Main Features

• N-dimensional Array: Core Array type with efficient memory layout and broadcasting
• Linear Algebra: Matrix operations, decompositions, solvers through BLAS/LAPACK integration
• Polynomial Functions: Interpolation, evaluation, and arithmetic operations
• Fast Fourier Transform: Optimized FFT implementation with 1D/2D transforms, real FFT specialization, frequency shifting, and various windowing functions
• Sparse Arrays: Memory-efficient representation for sparse data
• SIMD Acceleration: Enhanced vectorized operations via SciRS2-Core with AVX2/AVX512/NEON support
• Parallel Computing: Advanced multi-threaded execution with adaptive chunking and work-stealing
• GPU Acceleration: Optional GPU-accelerated array operations using WGPU
• Mathematical Functions: Comprehensive set of element-wise mathematical operations
• Statistical Analysis: Descriptive statistics, probability distributions, and more
• Random Number Generation: Modern interface for various distributions with fast generation and NumPy-compatible API
• SciRS2 Integration: Optional integration with SciRS2 for advanced statistical distributions and scientific computing functionality
• Fully Type-Safe: Leverage Rust's type system for compile-time guarantees

Optional Features

NumRS2 includes several optional features that can be enabled in your Cargo.toml:

• matrix_decomp (enabled by default): Matrix decomposition functions (SVD, QR, LU, etc.)
• lapack: Enable LAPACK-dependent linear algebra operations (eigenvalues, matrix decompositions)
• validation: Additional runtime validation checks for array operations
• scirs: Integration with SciRS2 for advanced statistical distributions and scientific computing
• gpu: GPU acceleration for array operations using WGPU

To enable a feature:

[dependencies]
numrs2 = { version = "0.1.0-beta.2", features = ["scirs"] }

Or, when building:

cargo build --features scirs

🚀 Performance Optimizations (New in 0.1.0-beta.2)

NumRS2 now leverages SciRS2-Core for cutting-edge performance optimizations:

• Unified SIMD Operations: All SIMD code goes through SciRS2-Core's SimdUnifiedOps trait
• Adaptive Algorithm Selection: AutoOptimizer automatically chooses between scalar, SIMD, or GPU implementations
• Platform Detection: Automatic detection of AVX2, AVX512, NEON, and GPU capabilities
• Parallel Operations: Optimized parallel processing with intelligent work distribution
• Memory-Efficient Chunking: Process large datasets without memory bottlenecks

See the optimization example for usage details.

SciRS2 Integration

The SciRS2 integration provides additional advanced statistical distributions:

• Noncentral Chi-square: Extends the standard chi-square with a noncentrality parameter
• Noncentral F: Extends the standard F distribution with a noncentrality parameter
• Von Mises: Circular normal distribution for directional statistics
• Maxwell-Boltzmann: Used for modeling particle velocities in physics
• Truncated Normal: Normal distribution with bounded support
• Multivariate Normal with Rotation: Allows rotation of the coordinate system

For examples, see scirs_integration_example.rs

GPU Acceleration

The GPU acceleration feature provides:

• GPU-accelerated array operations for significant performance improvements
• Seamless CPU/GPU interoperability with the same API
• Support for various operations: arithmetic, matrix multiplication, element-wise functions, etc.
• WGPU backend for cross-platform GPU support (Vulkan, Metal, DX12, WebGPU)

For examples, see gpu_example.rs

Example

use numrs2::prelude::*;

fn main() -> Result<()> {
    // Create arrays
    let a = Array::from_vec(vec![1.0, 2.0, 3.0, 4.0]).reshape(&[2, 2]);
    let b = Array::from_vec(vec![5.0, 6.0, 7.0, 8.0]).reshape(&[2, 2]);
    
    // Basic operations with broadcasting
    let c = a.add(&b);
    let d = a.multiply_broadcast(&b)?;
    
    // Matrix multiplication
    let e = a.matmul(&b)?;
    println!("a @ b = {}", e);
    
    // Linear algebra operations
    let (u, s, vt) = a.svd_compute()?;
    println!("SVD components: U = {}, S = {}, Vt = {}", u, s, vt);
    
    // Eigenvalues and eigenvectors
    let symmetric = Array::from_vec(vec![2.0, 1.0, 1.0, 2.0]).reshape(&[2, 2]);
    let (eigenvalues, eigenvectors) = symmetric.eigh("lower")?;
    println!("Eigenvalues: {}", eigenvalues);
    
    // Polynomial interpolation
    let x = Array::linspace(0.0, 1.0, 5)?;
    let y = Array::from_vec(vec![0.0, 0.1, 0.4, 0.9, 1.6]);
    let poly = PolynomialInterpolation::lagrange(&x, &y)?;
    println!("Interpolated value at 0.5: {}", poly.evaluate(0.5));
    
    // FFT operations
    let signal = Array::from_vec(vec![1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]);
    // Window the signal before transforming
    let windowed_signal = signal.apply_window("hann")?;
    // Compute FFT
    let spectrum = windowed_signal.fft()?;
    // Shift frequencies to center the spectrum
    let centered = spectrum.fftshift_complex()?;
    println!("FFT magnitude: {}", spectrum.power_spectrum()?);
    
    // Statistical operations
    let data = Array::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0]);
    println!("mean = {}", data.mean()?);
    println!("std = {}", data.std()?);
    
    // Sparse array operations
    let mut sparse = SparseArray::new(&[10, 10]);
    sparse.set(&[0, 0], 1.0)?;
    sparse.set(&[5, 5], 2.0)?;
    println!("Density: {}", sparse.density());
    
    // SIMD-accelerated operations
    let result = simd_ops::apply_simd(&data, |x| x * x + 2.0 * x + 1.0)?;
    println!("SIMD result: {}", result);

    // Random number generation
    let rng = random::default_rng();
    let uniform = rng.random::<f64>(&[3])?;
    let normal = rng.normal(0.0, 1.0, &[3])?;
    println!("Random uniform [0,1): {}", uniform);
    println!("Random normal: {}", normal);

    Ok(())
}

Performance

NumRS is designed with performance as a primary goal:

• Rust's Zero-Cost Abstractions: Compile-time optimization without runtime overhead
• BLAS/LAPACK Integration: Industry-standard libraries for linear algebra operations
• SIMD Vectorization: Parallel processing at the CPU instruction level with automatic CPU feature detection
• Memory Layout Optimization: Cache-friendly data structures and memory alignment
• Data Placement Strategies: Optimized memory placement for better cache utilization
• Adaptive Parallelization: Smart thresholds to determine when parallel execution is beneficial
• Scheduling Optimization: Intelligent selection of work scheduling strategies based on workload
• Fine-grained Parallelism: Advanced workload partitioning for better load balancing
• Modern Random Generation: Advanced thread-safe RNG with PCG64 algorithm for high-quality randomness

Installation

Add this to your Cargo.toml:

[dependencies]
numrs2 = "0.1.0-beta.2"

For BLAS/LAPACK support, ensure you have the necessary system libraries:

# Ubuntu/Debian
sudo apt-get install libopenblas-dev liblapack-dev

# macOS
brew install openblas lapack

macOS Apple Silicon Configuration

For Apple Silicon Macs (M1/M2/M3), additional configuration is required to properly link LAPACK libraries. Create a .cargo/config.toml file in your project root:

[build]
rustflags = ["-L", "/opt/homebrew/opt/openblas/lib", "-l", "openblas"]

This configuration ensures that the OpenBLAS library installed via Homebrew is properly linked when using LAPACK features. Without this configuration, you may encounter linking errors when building with the lapack feature enabled.

To use LAPACK functionality:

cargo build --features lapack
cargo test --features lapack

Implementation Details

NumRS is built on top of several battle-tested libraries:

• ndarray: Provides the foundation for n-dimensional arrays
• ndarray-linalg: Provides BLAS/LAPACK bindings for linear algebra
• num-complex: Complex number support for advanced operations
• BLAS/LAPACK: Powers high-performance linear algebra routines
• Rayon: Enables parallel computation capabilities
• num-traits: Provides generic numeric traits for numerical operations

Features

NumRS2 provides a comprehensive suite of numerical computing capabilities:

Core Functionality

• N-dimensional arrays with efficient memory layout and broadcasting
• Linear algebra operations with BLAS/LAPACK integration
• Matrix decompositions (SVD, QR, Cholesky, LU, Schur, COD)
• Eigenvalue and eigenvector computation
• Mathematical functions with numerical stability optimizations

Performance Optimizations

• SIMD acceleration with automatic CPU feature detection
• Parallel processing with adaptive scheduling and load balancing
• Memory optimization with cache-friendly data structures
• Vectorized operations for improved computational efficiency

Advanced Features

• Fast Fourier Transform with 1D/2D transforms and windowing functions
• Polynomial operations and interpolation methods
• Sparse matrix support for memory-efficient computations
• Random number generation with multiple distribution support
• Statistical analysis functions and descriptive statistics

Integration & Interoperability

• GPU acceleration support via WGPU (optional)
• SciRS2 integration for advanced statistical distributions (optional)
• Memory-mapped arrays for large dataset handling
• Serialization support for data persistence

📖 Documentation

📚 Comprehensive Guides

• Architecture Guide - System design and core concepts
• Migration Guide - Upgrading from previous versions
• Trait System Guide - Generic programming with NumRS2
• Error Handling Guide - Robust error management
• Memory Management Guide - Optimizing memory usage

🔗 Additional Resources

• Official API Documentation - Complete API reference
• Getting Started Guide - Essential information for beginners
• Installation Guide - Detailed installation instructions
• User Guide - Comprehensive guide to all NumRS features
• NumPy Migration Guide - Guide for NumPy users transitioning to NumRS2
• Implementation Status - Current status and next steps
• Contributing Guide - How to contribute to NumRS2

Module-specific documentation:

• Random Module Guide - Random number generation
• Statistics Module Guide - Statistical functions
• Linear Algebra Guide - Linear algebra operations
• Polynomial Guide - Polynomial operations
• FFT Guide - Fast Fourier Transform

Testing Documentation:

• Testing Guide - Guide for NumRS testing approach
• Property-based testing for mathematical operations
  • Property tests for linear algebra operations
  • Property tests for special functions
  • Statistical validation of random distributions
• Reference testing
  • Reference tests for random distributions
  • Reference tests for linear algebra operations
  • Reference tests for special functions
• Benchmarking
  • Linear algebra benchmarks
  • Special functions benchmarks

Examples

Check out the examples/ directory for more usage examples:

• basic_usage.rs: Core array operations and manipulations
• linalg_example.rs: Linear algebra operations and solvers
• simd_example.rs: SIMD-accelerated computations
• memory_optimize_example.rs: Memory layout optimization for cache efficiency
• parallel_optimize_example.rs: Parallelization optimization techniques
• random_distributions_example.rs: Comprehensive examples of random number generation
• See the examples README for more details

Development

NumRS is in active development. See TODO.md for upcoming features and development roadmap.

Testing

NumRS requires the approx crate for testing. Tests can be run after installation with:

cargo test

For running property-based and statistical tests for the random module:

cargo test --test test_random_statistical
cargo test --test test_random_properties
cargo test --test test_random_advanced

Contributing

NumRS2 is a community-driven project, and we welcome contributions from everyone. There are many ways to contribute:

• Code: Implement new features or fix bugs
• Documentation: Improve guides, docstrings, or examples
• Testing: Write tests or improve existing ones
• Reviewing: Review pull requests from other contributors
• Performance: Identify bottlenecks or implement optimizations
• Examples: Create example code showing library usage

If you're interested in contributing, please read our Contributing Guide for detailed instructions on how to get started.

For significant changes, please open an issue to discuss your ideas first.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.