ferray

01Overview

ferray is an educational project that implements a NumPy-like multidimensional array library in Rust with Python bindings. It demonstrates how to build high-performance numerical computing libraries using Rust's safety and speed while maintaining Python's ease of use.

The project uses OpenBLAS for optimized linear algebra operations and PyO3 for seamless Python-Rust interoperability.

02Key Features

• NumPy-like APIFamiliar interface for Python developers with array operations
• Rust PerformanceFast operations with zero-cost abstractions and memory safety
• OpenBLAS IntegrationLeverages optimized BLAS routines for linear algebra
• Python BindingsSeamless integration via PyO3 and maturin
• Broadcasting SupportNumPy-style broadcasting for element-wise operations
• NumPy InteroperabilityConvert between NumPy arrays and ferray

03Supported Operations

Array Creation

• NdArray([2, 3])Create uninitialized array
• zeros([3, 4])Create array filled with zeros
• ones([2, 3])Create array filled with ones
• from_list([[1, 2], [3, 4]])From Python list
• from_numpy(arr)From NumPy array

Indexing & Reshaping

• a[0, 2]Element access via indexing
• a.get([0, 1])Get element at position
• a.set([0, 1], 42.0)Set element value
• a.reshape([3, 2])Change shape
• a.transpose()Matrix transpose

Element-wise Operations

• a + bAddition with broadcasting
• a - bSubtraction
• a * bMultiplication
• a / bDivision
• a + 2.0Scalar operations

Properties & Conversion

• a.ndim()Number of dimensions
• a.shape()Shape tuple
• a.to_list()Convert to Python list
• a.to_numpy()Convert to NumPy array

04Installation

Prerequisites

# Ubuntu/Debian
sudo apt install libopenblas-dev

# macOS (Homebrew)
brew install openblas

# Arch Linux
sudo pacman -S openblas

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Using uv (recommended)
uv tool install maturin

# Or using pip
pip install maturin

Building the Package

# Clone the repository
git clone https://github.com/kashifulhaque/ferray.git
cd ferray

# Build and install in development mode
maturin develop --release

# Or using uv
uv run maturin develop --release

05Usage Examples

Basic Array Creation

import ferray as tnp

# Create arrays
a = tnp.NdArray.zeros([3, 4])
b = tnp.NdArray.ones([2, 3])
c = tnp.NdArray.from_list([[1.0, 2.0], [3.0, 4.0]])

# Check properties
print(a.shape())  # [3, 4]
print(a.ndim())   # 2

Indexing and Assignment

a = tnp.NdArray.zeros([3, 4])

# Get and set values
print(a[0, 2])  # 0.0
a[0, 2] = 99.0
print(a[0, 2])  # 99.0

# Using methods
a.set([1, 3], 42.0)
print(a.get([1, 3]))  # 42.0

Element-wise Operations

a = tnp.NdArray.ones([2, 3])
b = tnp.NdArray.ones([1, 3]) * 2.0

print(a + b)  # Broadcasting addition
print(a - b)  # Subtraction
print(a * b)  # Multiplication
print(a / b)  # Division

# Scalar operations
print(a + 2.0)
print(a * 5.0)

Transpose and Reshape

a = tnp.NdArray.from_list([
    [1.0, 2.0, 3.0],
    [4.0, 5.0, 6.0]
])

print(a.shape())          # [2, 3]
print(a.transpose())      # Transposed array

a.reshape([3, 2])
print(a.shape())          # [3, 2]

NumPy Interoperability

import numpy as np
import ferray as tnp

# From NumPy to ferray
a_np = np.ones((2, 3), dtype=np.float32)
a_rust = tnp.NdArray.from_numpy(a_np)

# Back to NumPy
a_back = a_rust.to_numpy()
print(np.allclose(a_np, a_back))  # True

06Using mise (Optional)

If you have mise installed, you can use the provided task commands:

• mise run developBuild and install in development mode
• mise run testRun test suite
• mise run benchRun performance benchmarks
• mise run checkCheck code quality

07Project Structure

• src/lib.rsPyO3 module definition and exports
• src/array.rsCore NdArray implementation
• src/operations.rsElement-wise operations and broadcasting
• src/conversions.rsNumPy interoperability
• src/utils.rsHelper functions and utilities
• build.rsBuild script for linking OpenBLAS
• test.pyBasic functionality tests
• bench_matmul.pyMatrix multiplication benchmarks

08Tech Stack

Language

Rust

Python Bindings

PyO3

Build Tool

maturin

Linear Algebra

OpenBLAS

Target

Python 3.11+

09Learning Goals

• Understanding NumPy's internal architecture and memory layout
• Exploring Rust-Python interoperability with PyO3
• Implementing broadcasting semantics for array operations
• Integrating native BLAS libraries for performance
• Building Python extensions with maturin
• Managing memory safety across language boundaries

10Status