A fast, high-performance, memory-safe numerical computing and machine learning library for Zig.

📚 <a href="https://muhammad-fiaz.github.io/num.zig/">Documentation</a> | <a href="https://muhammad-fiaz.github.io/num.zig/api/overview">API Reference</a> | <a href="https://muhammad-fiaz.github.io/num.zig/guide/quick-start">Quick Start</a> | <a href="CONTRIBUTING.md">Contributing</a>

</div>

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.

<details> <summary>✨ Features of Num.Zig (click to expand)</summary>

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

</details>

<details> <summary>📌 Prerequisites & Supported Platforms (click to expand)</summary>

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 |

</details>

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,

Num.zig

Install / Use

README