To learn the inner workings of NumPy
ferray/
├── src/ # Rust source code
│ ├── lib.rs # Module entry point & PyO3 module definition
│ ├── array.rs # NdArray class (core data structure)
│ ├── operations.rs # Element-wise & matrix operations (add, mul, matmul, etc.)
│ ├── conversions.rs # Conversions between Python lists, NumPy arrays & NdArray
│ └── utils.rs # Stride computation, broadcasting, index utilities
├── tests/ # Python tests
│ ├── test_basic.py # Core functionality tests
│ └── test_shapes.py # Matrix multiplication shape tests
├── benchmarks/ # Performance benchmarks
│ └── bench_matmul.py # Matrix multiplication benchmark (ferray vs NumPy)
├── Cargo.toml # Rust package manifest
├── pyproject.toml # Python package metadata (maturin build system)
├── build.rs # Build script (OpenBLAS linking)
├── Dockerfile # Container image for building & running
└── compose.yml # Docker Compose services (dev, test, bench)
This project depends on OpenBLAS for linear algebra operations.
Ubuntu/Debian:
sudo apt-get install libopenblas-devFedora/RHEL:
sudo dnf install openblas-develArch Linux:
sudo pacman -S openblasmacOS (Homebrew):
brew install openblasmacOS/Linux (Nix):
nix-shell -p openblasMake sure you have the Rust toolchain installed: https://www.rust-lang.org/tools/install
Maturin is required to build this Rust-Python extension:
# Using uv (recommended)
uv tool install maturin
# Or using pip
pip install maturin# Clone and enter the repository
git clone https://github.com/kashifulhaque/ferray.git
cd ferray
# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# Install dependencies
pip install maturin numpy
# Build and install in development mode
maturin develop --releaseuv run maturin develop --release --uvAfter building, you can run:
# Run basic tests
python tests/test_basic.py
# Run shape-specific matmul tests
python tests/test_shapes.py
# Run benchmarks
python benchmarks/bench_matmul.pyBuild and run everything in a container — no local Rust or OpenBLAS needed:
# Run tests
docker compose run test
# Run benchmarks
docker compose run bench
# Interactive development
docker compose run devIf you have mise installed, you can use the provided tasks:
mise run check # cargo check
mise run build # cargo build
mise run develop # Build & install with maturin
mise run test # Run all Python tests
mise run bench # Run benchmarksThis project uses GitHub Actions for:
- CI (
ci.yml): Runscargo check,clippy, andfmton every push/PR, then builds wheels for Linux and macOS. - Benchmarks (
benchmarks.yml): Runs matmul benchmarks on push tomainand publishes results to the repository wiki.