https://github.com/muhammad-fiaz/num.zig
A production-grade, high-performance numerical computing library for Zig, designed with a clean, intuitive, and developer-friendly API similar to NumPy.
https://github.com/muhammad-fiaz/num.zig
num-zig num-zig-package numzig numzig-library package zig zig-lang zig-library zig-package
Last synced: about 4 hours ago
JSON representation
A production-grade, high-performance numerical computing library for Zig, designed with a clean, intuitive, and developer-friendly API similar to NumPy.
- Host: GitHub
- URL: https://github.com/muhammad-fiaz/num.zig
- Owner: muhammad-fiaz
- License: apache-2.0
- Created: 2025-12-07T08:25:40.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-12-08T08:20:57.000Z (6 months ago)
- Last Synced: 2026-04-22T15:40:32.346Z (about 2 months ago)
- Topics: num-zig, num-zig-package, numzig, numzig-library, package, zig, zig-lang, zig-library, zig-package
- Language: Zig
- Homepage: https://muhammad-fiaz.github.io/num.zig/
- Size: 271 KB
- Stars: 14
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
A fast, high-performance, memory-safe numerical computing and machine learning library for Zig.
📚 Documentation |
API Reference |
Quick Start |
Contributing
A production-grade, high-performance numerical computing library for Zig, designed with a clean, intuitive, and developer-friendly API similar to NumPy.
> Note: Num.zig is currently under active development. GPU acceleration is not yet supported, but it is planned for future releases. If you are interested, contributions are welcome! ⭐ If you love Num.zig, please consider starring the repository.
---
✨ Features of Num.Zig (click to expand)
| Feature | Description |
|---------|-------------|
| ✨ **NDArray** | N-dimensional array implementation with efficient memory management |
| 🎯 **Broadcasting** | NumPy-style broadcasting for arithmetic operations |
| 🚀 **Linear Algebra** | Matrix multiplication, dot products, QR/Cholesky/Eig decompositions, solvers |
| 📁 **Statistics** | Reductions (sum, mean, min, max, std, var, median) |
| 🔍 **Indexing** | Advanced slicing, boolean masking, take, where, nonzero |
| 📡 **Signal Processing** | Convolution, correlation, filtering modes (full, valid, same) |
| 📈 **Polynomials** | Evaluation, arithmetic, roots, derivatives, integrals |
| 🔢 **Calculus** | Finite differences, gradients |
| 🛠️ **Element-wise** | Clip, Round, Floor, Ceil, Abs, Sign, Min/Max, Trig, Log, Exp |
| 🔄 **Random** | Random number generation with various distributions |
| ⚡ **FFT** | N-dimensional Fast Fourier Transform |
| ℂ **Complex Numbers** | Complex number support and operations |
| 💾 **IO** | Binary save/load, Memory Mapping (mmap) |
| 🎨 **Machine Learning** | Sequential Models, Dense/Dropout/Softmax Layers, Training Loop, Save/Load |
| 📊 **Memory Safe** | Built with Zig's safety features and explicit allocator control |
| 📝 **Cross-Platform** | Supports Windows, Linux, macOS, and bare metal |
| 🔗 **Zero Dependencies** | Pure Zig implementation with no external dependencies |
| ⚡ **Performance** | Optimized algorithms including tiled matrix multiplication |
| 🧮 **Autograd** | Automatic differentiation for gradient-based optimization |
| 📊 **DataFrame** | Tabular data structures similar to pandas (DataFrame, Series) |
| 🧩 **Modular Design** | Organized into modules for easy use and extension |
| 🛠️ **Builtin Collections** | Efficient data structures like basic ML Algorithms, HashSet, etc. |
| 📚 **Comprehensive Documentation** | Detailed guides and API reference for easy adoption |
----
📌 Prerequisites & Supported Platforms (click to expand)
## Prerequisites
Before installing Num.Zig, ensure you have the following:
| Requirement | Version | Notes |
|-------------|---------|-------|
| **Zig** | 0.15.0+ | Download from [ziglang.org](https://ziglang.org/download/) |
| **Operating System** | Windows 10+, Linux, macOS | Cross-platform support |
> **Tip:** Verify your Zig installation by running `zig version` in your terminal.
---
## Supported Platforms
Num.Zig supports a wide range of platforms and architectures:
| Platform | Architectures | Status |
|----------|---------------|--------|
| **Windows** | x86_64, x86 | ✅ Full support |
| **Linux** | x86_64, x86, aarch64 | ✅ Full support |
| **macOS** | x86_64, aarch64 (Apple Silicon) | ✅ Full support |
| **Bare Metal / Freestanding** | x86_64, aarch64, arm, riscv64 | ✅ Full support |
---
## Installation
### Method 1: Starter Project (Recommended)
Download the starter project to get up and running quickly:
[**⬇️ Download Starter Project**](https://github.com/muhammad-fiaz/num.zig/releases/latest/download/project-starter-example.zip)
### Method 2: Zig Fetch
The easiest way to add Num.Zig to your existing project:
```bash
zig fetch --save https://github.com/muhammad-fiaz/num.zig/archive/refs/heads/main.tar.gz
```
This automatically adds the dependency with the correct hash to your `build.zig.zon`.
### Method 3: Manual Configuration
Add to your `build.zig.zon`:
```zig
.dependencies = .{
.num = .{
.url = "https://github.com/muhammad-fiaz/num.zig/archive/refs/heads/main.tar.gz",
// .hash = "...", // Run zig build to get the hash
},
},
```
Then in your `build.zig`:
```zig
const num = b.dependency("num", .{
.target = target,
.optimize = optimize,
});
exe.root_module.addImport("num", num.module("num"));
```
## Quick Start
```zig
const std = @import("std");
const num = @import("num");
const NDArray = num.NDArray;
pub fn main() !void {
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer _ = gpa.deinit();
const allocator = gpa.allocator();
// Create a 2x3 matrix using arange (0, 1, 2, 3, 4, 5)
var a = try NDArray(f32).arange(allocator, 0.0, 6.0, 1.0);
defer a.deinit();
try a.reshape(&.{ 2, 3 });
// Create another matrix of ones
var b = try NDArray(f32).ones(allocator, &.{ 2, 3 });
defer b.deinit();
// Add them together
var c = try num.ops.add(f32, allocator, &a, &b);
defer c.deinit();
// Print result
const val = try c.get(&.{ 0, 0 }); // 0.0 + 1.0 = 1.0
std.debug.print("Result at [0,0]: {d}\n", .{val});
}
```
## Running Examples
This repository includes several runnable examples covering different aspects of the library:
- `zig build run-basics`: Basic array creation, I/O, and indexing.
- `zig build run-manipulation`: Reshaping, transposing, and flattening arrays.
- `zig build run-math`: Arithmetic operations, broadcasting, and statistics.
- `zig build run-linalg`: Linear algebra operations (matmul, solve).
- `zig build run-random`: Random number generation distributions.
- `zig build run-ml`: Machine learning components (Dense layer, ReLU, MSE).
- `zig build run-ml_sample`: Full Neural Network training (XOR) using Sequential API.
- `zig build run-fft`: Fast Fourier Transform.
- `zig build run-indexing`: Advanced indexing (slicing, take).
- `zig build run-signal_poly`: Signal processing and polynomials.
- `zig build run-setops`: Set operations.
To run an example:
```bash
zig build run-basics
```
## Usage Examples
### Linear Algebra
```zig
const allocator = std.heap.page_allocator;
// Matrix Multiplication
var a = try NDArray(f32).init(allocator, &.{ 2, 3 });
// ... fill a ...
var b = try NDArray(f32).init(allocator, &.{ 3, 2 });
// ... fill b ...
var c = try num.linalg.matmul(f32, allocator, &a, &b);
defer c.deinit();
```
### Machine Learning (Sequential API)
```zig
const allocator = std.heap.page_allocator;
const Sequential = num.ml.models.Sequential;
const Layer = num.ml.layers.Layer;
const Dense = num.ml.layers.Dense;
// Define Model
var model = Sequential.init(allocator);
defer model.deinit(allocator);
// Add Layers
try model.add(allocator, Layer{ .Dense = try Dense.init(allocator, 10, 32, .XavierUniform) });
try model.add(allocator, Layer{ .ReLU = {} });
try model.add(allocator, Layer{ .Dense = try Dense.init(allocator, 32, 1, .XavierUniform) });
try model.add(allocator, Layer{ .Sigmoid = {} });
// Train (assuming x_train, y_train, optimizer, loss_fn are defined)
// try model.fit(allocator, x_train, y_train, optimizer, loss_fn, 100);
// Save & Load
try model.save(allocator, "model.bin");
var loaded = try Sequential.load(allocator, "model.bin");
defer loaded.deinit(allocator);
```
## Performance
Num.Zig is designed for high performance. It uses tiled algorithms for matrix multiplication to optimize cache usage and minimize memory bandwidth bottlenecks.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
Apache 2.0 License - see [LICENSE](LICENSE) for details.