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
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

Method 2: Zig Fetch

The easiest way to add Num.Zig to your existing project:

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:

.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:

const num = b.dependency("num", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("num", num.module("num"));

Quick Start

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:

zig build run-basics

Usage Examples

Linear Algebra

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)

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 for details.