A production-grade, high-performance numerical computing library for Zig, designed with a clean, intuitive, and developer-friendly API similar to NumPy.

Note: This Project is Still in Development!

---

✨ 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	Dense Layers, Activation Functions, Loss Functions, Optimizers
📊 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

---

📌 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-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 (Dense Layer)

const allocator = std.heap.page_allocator;
var layer = try num.ml.layers.Dense.init(allocator, 10, 5); // Input 10, Output 5
defer layer.deinit();

var input = try NDArray(f32).zeros(allocator, &.{ 1, 10 });
defer input.deinit();

var output = try layer.forward(allocator, &input);
defer output.deinit();

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.