Metadata-Version: 2.4
Name: zanpy
Version: 1.0.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Topic :: Scientific/Engineering :: Mathematics
Summary: First release of a high-performance N-dimensional array library built in Rust for macOS.
Keywords: matrix,rust,simd,ndarray,math
Author-email: Santiago Zanoni <santiagozanoni08@gmail.com>
License: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Mersautschip/zanpy

# zanpy

**A high-performance numerical computing library for Rust.**

`zanpy` is a lightweight, hardware-aware multidimensional array library. It was built to explore the intersection of systems programming and data science, bridging the gap between Python's ease of use and Rust's raw computational power.

## Performance Benchmarks

In a $1024 \times 1024$ double-precision ($f64$) matrix multiplication task, `zanpy` delivers performance that rivals industry-standard BLAS implementations.

| Implementation | Avg. Time (1024x1024) | Speedup vs. Python | Ratio vs. NumPy |
| :--- | :--- | :--- | :--- |
| **NumPy (Accelerate/vecLib)** | 7.9ms | ~3000x | 1.0x |
| **zanpy (Rayon + SIMD)** | **43.5ms** | **~550x** | **5.48x** |
| Pure Python (Nested Loops) | ~24,000ms | 1x | 3000x+ |

*Benchmarks conducted on Apple M1 (8-core), 16GB RAM. Results may vary based on thermal throttling and background processes.*

---

## Core Technologies

- **SIMD Vectorization:** Leverages 128-bit wide registers via the `wide` crate to execute multiple floating-point operations per clock cycle (ARM NEON).
- **Work-Stealing Parallelism:** Utilizes `rayon` to distribute workloads across all available CPU cores, maximizing throughput on multi-core architectures.
- **PyO3 Bindings:** High-efficiency FFI (Foreign Function Interface) allowing the library to be imported and used as a native Python module.
- **Manual Memory Management:** Uses raw pointer arithmetic and `MaybeUninit` to bypass the overhead of standard collection initialization.

---

## Architecture

Achieving **5.48x** of NumPy (a library written in C and Assembly) required deep architectural optimizations:

### 1. Spatial Locality & IKJ Reordering
I moved away from the naive $O(n^3)$ loop structure in favor of an **IKJ-ordered kernel**. By processing the matrix in this order, I ensured contiguous memory access (streaming). This allows the CPU's **hardware prefetcher** to load data into the L1 cache before the execution unit even requests it.

### 2. Cache Boundary Awareness
The library was tuned to respect the 128-byte cache line size of the Apple M1. Through iterative profiling, I balanced "Cache Tiling" overhead against "Instruction Pressure," eventually settling on a streamlined parallel SIMD kernel that minimizes branch mispredictions.

---

## Usage

Zanpy is available on pip: 

```
bash
pip install zanpy
```

### Prerequisites

You will need the Rust toolchain and `maturin` installed to build the project from source. 


```
bash
# Clone the repository
git clone [https://github.com/yourusername/zanpy.git](https://github.com/yourusername/zanpy.git)
cd zanpy

# Build with release optimizations
maturin develop --release
```

### Testing

Run

```
bash

python3.12 test.py
```

## Core Features

`zanpy` provides a robust API for multidimensional array manipulation, optimized for performance via its Rust backend.

### Array Creation & Manipulation
- **Flexible Initialization:** Create arrays from Python lists, or use built-in constructors like `ones()`, `zeros()`, `identity()`, and `arange()`.
- **Advanced Reshaping:** Modify array dimensions with `reshape()` or reorder axes using `permute()` and `transpose()`.
- **High-Performance Access:** Efficient indexing via the `get()` method with bounds checking handled by Rust.

### Element-wise Operations
`zanpy` overloads standard Python operators to perform multi-threaded, SIMD-accelerated element-wise math:
- **Arithmetic:** Support for `+` (`__add__`), `-` (`__sub__`), `*` (`__mul__`), and `/` (`__truediv__`).
- **Broadcasting Ready:** Designed to handle element-wise operations across compatible shapes.

### Reductions & Statistics
Quickly compute aggregate values across your datasets:
- **Sum & Mean:** Fast summation and averaging.
- **Extrema:** Rapid `max()` and `min()` identification using optimized comparison kernels.

### Linear Algebra (The Engine)
This is where `zanpy` shines, utilizing specialized Rust kernels for heavy computations:
- **Matrix Multiplication (`@`):** Implemented via the `__matmul__` operator, featuring the optimized IKJ-tiled SIMD kernel.
- **Dot Product:** Vector-vector and matrix-vector dot products.
- **Matrix Inverse:** Compute the inverse of square matrices using optimized linear algebra routines.

---

## Technical Implementation Details

For those interested in the bridge between Python and Rust:

- **PyO3 Integration:** We use `#[pyclass]` and `#[pymethods]` to expose the `NdArray` Rust struct as a native Python object, minimizing FFI overhead.
- **Memory Ownership:** Data is stored in contiguous memory in Rust. When accessing `.data` from Python, a copy is safely provided to maintain Rust's strict memory safety and avoid dangling pointers.
- **Error Handling:** Rust `Result` types are automatically mapped to Python `ValueError` exceptions, ensuring that dimension mismatches or non-invertible matrices provide clear, actionable feedback to the Python user.

