What is RMath?

RMath is a high-performance numerical toolkit for Python, built from the ground up in Rust and exposed via PyO3. It provides the core data structures and mathematical kernels needed for data science, machine learning, signal processing, and scientific computing — all executing outside the Python GIL on a Rayon thread pool.

The Core Idea

RMath is a drop-in accelerator, not a replacement. You keep writing Python. Heavy numerical work gets offloaded to Rust. Results come back as native Python types or are bridged to NumPy, PyTorch, JAX, and pandas via zero-copy protocols.

hello_rmath.py

import rmath as rm

# Top-level imports: rm.Array, rm.Vector, rm.Tensor, rm.Scalar, rm.Dual
v = rm.Vector([1.0, 2.0, 3.0, 4.0, 5.0])
print(v.sum())     # 15.0
print(v.mean())    # 3.0
print(v.std_dev()) # 1.5811...

a = rm.Array([[1.0, 2.0], [3.0, 4.0]])
print(a.mean())    # 2.5

15.0 3.0 1.5811388300841898 2.5

What's Inside

Module	What it provides
`rmath.array`	N-dimensional `Array` — parallel math, storage tiering (stack/heap/mmap), NumPy/PyTorch bridges
`rmath.vector`	1-D `Vector` — 70+ operations (trig, reductions, sorting, filtering, norms)
`rmath.Tensor`	Autograd-enabled tensor — forward + reverse mode AD, gradient tracking via `Arc<RwLock>`
`rmath.scalar`	Precision f64 math — 80+ functions, mirrors Python's `math` module
`rmath.linalg`	LU, QR, Cholesky, SVD, eigendecomposition via faer
`rmath.stats`	Descriptive & inferential statistics — Welford's variance, t-tests, regression, distributions
`rmath.calculus`	Dual-number autodiff, Simpson/Gauss integration, Newton root-finding
`rmath.signal`	FFT, convolution, spectral analysis
`rmath.geometry`	3D transforms, quaternions, convex hull, cosine similarity
`rmath.nn`	Activation functions (ReLU, GELU, Softmax), loss, normalization
`rmath.constants`	Mathematical and physical constants (π, e, G, c, …)

Why Rust?

Python's GIL serialises every thread. C extensions work around it, but they require manual memory management. Rust gives us both: zero-cost memory safety and true parallelism via Rayon — no race conditions, no use-after-free, no garbage collector pauses.

Operations on arrays and vectors above the parallelism threshold (8,192 elements) automatically dispatch to a Rayon thread pool. Below that threshold, serial execution avoids thread-pool overhead for small workloads.

Key Design Principles

🔒 Memory Safety Without GC

All data structures use Rust's ownership model. Arc<Vec<f64>> for heap vectors enables cheap cloning (reference count bump) with no deep copies. Copy-on-Write is triggered only on mutation.

⚡ GIL-Free Parallelism

Every reduction, elementwise op, sort, and filter calls py.allow_threads(), fully releasing the GIL so Python threads can run concurrently.

🔢 IEEE-754 Accuracy

Summation uses Kahan compensation. Variance uses Welford's one-pass algorithm. Both guarantee O(ε) error regardless of input size N.

🔌 First-Class Interop

Implements __array__, __array_interface__ protocols. Pass rmath objects directly to scikit-learn, pandas, and PyTorch without explicit conversion.

Ready to start? Go to Installation to get rmath on your system in one command, then follow the Quickstart for your first parallel computation.

Page Guide

Page	What you'll learn
Installation	pip install, wheel support, building from source
Quickstart	Verified code examples for Vector, Array, filtering, and stats
The RMath Engine	4-tier memory architecture, storage tiering, thread safety
Performance	Real benchmarks: rmath vs NumPy on a 5M-row pipeline