⚠️ Disclaimer: RustyNum is currently a work in progress and is not recommended for production use. Features may be unstable and subject to change.

RustyNum

RustyNum is a high-performance numerical computation library written in Rust, created to demonstrate the potential of Rust's SIMD (Single Instruction, Multiple Data) capabilities using the nightly portable_simd feature, and serving as a fast alternative to Numpy.

Key Features

• High Performance: Utilizes Rust's portable_simd for accelerated numerical operations across various hardware platforms, achieving up to 2.86x faster computations for certain operations compared to Numpy.
• Python Bindings: Seamless integration with Python, providing a familiar Numpy-like interface.
• Lightweight: Minimal dependencies (no external crates are used), ensuring a small footprint and easy deployment. RustyNum Python wheels are only 300kBytes (50x smaller than Numpy wheels).

Installation

Supported Python versions: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13

Supported operating systems: Windows x86, Linux x86, MacOS x86 & ARM

For comprehensive documentation, tutorials, and API reference, visit rustynum.com.

For Python

You can install RustyNum directly from PyPI:

pip install rustynum

If that does not work for you please create an issue with the operating system and Python version you're using!

Quick Start Guide (Python)

If you're familiar with Numpy, you'll quickly get used to RustyNum!

import numpy as np
import rustynum as rnp

# Using Numpy
a = np.array([1.0, 2.0, 3.0, 4.0], dtype="float32")
a = a + 2
print(a.mean())  # 4.5

# Using RustyNum
b = rnp.NumArray([1.0, 2.0, 3.0, 4.0], dtype="float32")
b = b + 2
print(b.mean().item())  # 4.5

Advanced Usage

You can perform advanced operations such as matrix-vector and matrix-matrix multiplications:

# Matrix-vector dot product using Numpy
import numpy as np
import rustynum as rnp

a = np.random.rand(4 * 4).astype(np.float32)
b = np.random.rand(4).astype(np.float32)
result_numpy = np.dot(a.reshape((4, 4)), b)

# Matrix-vector dot product using RustyNum
a_rnp = rnp.NumArray(a.tolist())
b_rnp = rnp.NumArray(b.tolist())
result_rust = a_rnp.reshape([4, 4]).dot(b_rnp).tolist()

print(result_numpy)  # Example Output: [0.8383043, 1.678406, 1.4153088, 0.7959367]
print(result_rust)   # Example Output: [0.8383043, 1.678406, 1.4153088, 0.7959367]

Features

RustyNum offers a variety of numerical operations and data types, with more features planned for the future.

Supported Data Types

• float64
• float32
• uint8 (experimental)
• int32 (Planned)
• int64 (Planned)

Supported Operations

NumArray Class

Initialization

from rustynum import NumArray

# From a list
a = NumArray([1.0, 2.0, 3.0], dtype="float32")

# From another NumArray
b = NumArray(a)

# From nested lists (2D array)
c = NumArray([[1.0, 2.0], [3.0, 4.0]], dtype="float64")

Methods

reshape(shape: List[int]) -> NumArray

Reshapes the array to the specified shape.

reshaped = a.reshape([3, 1])

matmul(other: NumArray) -> NumArray

Performs matrix multiplication with another NumArray.

result = a.matmul(b)
# or
result = a @ b

dot(other: NumArray) -> NumArray

Computes the dot product with another NumArray.

dot_product = a.dot(b)

mean(axis: Union[None, int, Sequence[int]] = None) -> Union[NumArray, float]

Computes the mean along specified axis.

average = a.mean()
average_axis0 = a.mean(axis=0)

median(axis: Union[None, int, Sequence[int]] = None) -> Union[NumArray, float]

Computes the median along specified axis.

median = a.median()
median_axis0 = a.median(axis=0)

min(axis: Union[None, int, Sequence[int]] = None) -> Union[NumArray, float]

Returns the minimum value in the array.

minimum = a.min()

max(axis: Union[None, int, Sequence[int]] = None) -> Union[NumArray, float]

Returns the maximum value in the array.

maximum = a.max()

tolist() -> Union[List[float], List[List[float]]]

Converts the NumArray to a Python list.

list_representation = a.tolist()

Multi-Dimensional Arrays

• Matrix-vector dot product
• Matrix-matrix dot product

Roadmap

Planned Features:

• N-dimensional arrays
• Useful for filters, image processing, and machine learning
• Additional operations: argmin, argmax, sort, std, var, zeros, cumsum, interp
• Integer support
• Extended shaping and reshaping capabilities
• C++ and WASM bindings

Not Planned:

• Random number generation (use the rand crate)

Design Principles

RustyNum is built on four core principles:

1. No 3rd Party Dependencies: Ensuring transparency and control over the codebase.
2. Leverage Portable SIMD: Utilizing Rust's nightly SIMD feature for high-performance operations across platforms.
3. First-Class Language Bindings: Providing robust support for Python, with plans for WebAssembly and C++.
4. Numpy-like Interface: Offering a familiar and intuitive user experience for those coming from Python.

Performance

Python

RustyNum leverages Rust's portable_simd feature to achieve significant performance improvements in numerical computations. On a MacBook Pro M1 Pro, RustyNum outperforms Numpy in several key operations. Below are benchmark results comparing RustyNum 0.1.4 with Numpy 1.24.4:

Benchmark Results (float32)

Benchmark Results (float64)

Observations

• RustyNum significantly outperforms Numpy in basic operations such as mean, median, min, and dot product, with speedup factors up to and over 2x.
• For larger operations, especially matrix-vector and matrix-matrix multiplications, Numpy currently performs better, which highlights areas for potential optimization in RustyNum.

These results demonstrate RustyNum's potential for high-performance numerical computations, particularly in operations where SIMD instructions can be fully leveraged.

Rust

In addition to the Python bindings, RustyNum’s core library is implemented in Rust. Below is a comparison of RustyNum (rustynum_rs) with two popular Rust numerical libraries: nalgebra 0.33.0 and ndarray 0.16.1. The benchmarks were conducted using the Criterion crate to measure performance across various basic operations.

Benchmark Results (float32)

Observations

• RustyNum is able to perform on par with nalgebra and ndarray in most operations and sometimes even outperforms them.
• There seems a significant overhead in the Python bindings. We're getting 10ms in Python in RustyNum for the matrix-vector multiplication with 1k elements vs 77us in Rust.

Build

Rust Crate

Run tests

Run using

cargo test

Create Docs

cargo doc --open

Run Benchmarks

Run using

cargo bench -- <benchmark_name>

Python bindings

Don't use maturin. But only setup.py

cd bindings/python/ && python setup.py install

or

cd bindings/python/ && python setup.py bdist_wheel

Then run tests using

pytest tests

or benchmarks using

pytest benchmarks