The RMath Engine

RMath is not just a collection of functions; it is a multi-tiered execution engine designed to bypass the limitations of the Python interpreter and maximize hardware utilization.

The 4-Tier Memory Architecture

To achieve maximum performance and bypass Python's memory overhead, RMath implements a dynamic multi-tiered memory architecture. It automatically routes data to the most efficient storage medium based on size and operation type.

1. Inline (Stack) Storage

Small vectors (≤ 32 elements) are stored directly on the CPU stack. This provides zero-allocation creation and blazing-fast cache-local operations. Ideal for 3D geometry and small spatial transformations.

2. Heap Storage

For standard datasets, RMath uses contiguous, Arc-wrapped heap memory managed by Rust. This allows safe, zero-copy sharing between threads during parallel operations and cheap clones.

3. Projected Storage (Virtual Vectors)

For operations that would otherwise generate massive intermediate results, RMath uses Projected Storage. Instead of materializing elements in RAM, data exists as mathematical projections (a pure function mapping an index to a value). This allows zero-allocation operations on massive datasets.

4. Mmap (Disk-Backed) Storage

When working with datasets larger than available RAM, RMath uses memory-mapped (mmap) storage. It maps files directly from disk into virtual memory, allowing parallel streaming and chunked processing with near-zero RAM overhead.

Bypassing the GIL

RMath releases the Python Global Interpreter Lock (GIL) before every heavy computation, allowing the Rayon thread pool to utilize 100% of your CPU cores.

Thresholding: RMath automatically parallelizes operations on datasets larger than 8,192 elements to avoid threading overhead for tiny tasks. Below this, it runs purely serial for maximum speed.

Proven: Lazy Engine Fusion

You can chain operations without allocating intermediate arrays using .lazy(). The computation is fused into a single pass through memory.

lazy_fusion_demo.py

import rmath.array as ra

# In-Memory Loop Fusion (3 passes -> 1 pass)
# Memory is allocated ONCE for the final result.
a = ra.Array.ones(4, 4)

# .lazy() defers execution. .execute() materialises it.
result = a.lazy().mul(2.0).sin().exp().execute()

print(f"Shape: {result.shape}, Mean: {result.mean():.4f}")

Shape: [4, 4], Mean: 2.4826