Zigen

Zigen: High-performance linear algebra library for Zig — pure Zig implementation with Eigen-compatible naming, zero dependencies, and zero-allocation APIs for performance-critical code.

Overview

Metric	Value
Version	0.1.0
Zig	0.16.0-dev.2510+bcb5218a2
Dependencies	None (pure Zig)
Decompositions	20+
Tests	All passing ✅
Examples	9
Benchmarks	28 (vs Eigen 5.0)

Features

• ✅ Zero Dependencies — Pure Zig, no BLAS/LAPACK required
• ✅ Fixed + Dynamic Size — Compile-time and runtime-sized matrices/vectors
• ✅ 20+ Decompositions — LU, QR, Cholesky, SVD, Eigensolvers, Schur, and more
• ✅ Sparse Matrices — CSR/COO formats, SparseLU/Cholesky/QR solvers
• ✅ Iterative Solvers — CG, BiCGSTAB, GMRES, MINRES with preconditioners
• ✅ Geometry — Quaternions, transforms, rotations, SLERP, Euler angles
• ✅ Zero-Allocation APIs — Workspace-reuse pattern for hot paths
• ✅ I/O — NumPy .npy and MatrixMarket format support
• ✅ Eigen-Compatible Naming — Easy migration from Eigen C++

Quick Start

Prerequisites

• Zig 0.16.0-dev.2510+bcb5218a2

No other dependencies required — Zigen is pure Zig.

Build & Test

git clone https://github.com/coderonion/zigen
cd zigen

zig build                           # Build library
zig build test                      # Run all tests
zig build unit-test                 # Unit tests only
zig build integration-test          # Integration tests only
zig build run-basic_matrix          # Run a specific example

Basic Usage

const Zigen = @import("zigen");

// Fixed-size matrix operations
const A = Zigen.Matrix3f.fromArray([3][3]f32{
    .{ 2, -1, 0 },
    .{ -1, 2, -1 },
    .{ 0, -1, 2 },
});
const b = Zigen.Vector3f.fromArray(.{ 1, 0, 1 });

// Solve Ax = b via LU decomposition
const lu = try Zigen.LU(f32, 3).compute(A);
const x = lu.solve(b);

// Quaternion rotation
const axis = Zigen.Vector3f.fromArray(.{ 0, 0, 1 });
const q = Zigen.Quaternionf.fromAxisAngle(axis, std.math.pi / 2.0);
const rotated = q.rotate(b);

📦 Use as Zig Package

Add Zigen as a dependency in your project — pure Zig, no linking needed.

Step 1: Add dependency to build.zig.zon

Local path (for development):

.dependencies = .{
    .zigen = .{
        .path = "../zigen",
    },
},

Git URL (for release):

.dependencies = .{
    .zigen = .{
        .url = "https://github.com/coderonion/zigen/archive/v0.1.0.tar.gz",
        .hash = "HASH_VALUE",
    },
},

Tip

How to get the hash: First, add the .url field without .hash, then run zig build. Zig will download the package, compute the hash, and display the correct .hash = "..." value in the error output. Copy that value into your build.zig.zon.

Step 2: Import in build.zig

// Get zigen dependency — pure Zig, no linking needed
const zigen = b.dependency("zigen", .{}).module("zigen");

// Just one line to import
exe.root_module.addImport("zigen", zigen);

Step 3: Use in your code

const Zigen = @import("zigen");

pub fn main() !void {
    const m = Zigen.Matrix3f.identity();
    const det = m.determinant();
    // ...
}

Modules

Module	Features	Status
Core	Matrix/vector ops, transpose, inverse, determinant, trace, norms	✅
Decompositions	LU, QR, Cholesky, LDLT, SVD, JacobiSVD, BDCSVD	✅
Eigensolvers	SelfAdjointEigenSolver, EigenSolver, GeneralizedEigenSolver	✅
Advanced Decomp	Tridiagonalization, Hessenberg, RealSchur, ComplexSchur, RealQZ	✅
Sparse	CSR, COO, SparseLU, SparseCholesky, SparseQR, SimplicialLDLT/LLT	✅
Iterative Solvers	CG, BiCGSTAB, GMRES, MINRES, LSCG	✅
Preconditioners	Diagonal, IncompleteLUT, IdentityPreconditioner	✅
Geometry	Quaternions, transforms, AngleAxis, Rotation2D, Euler angles	✅
I/O	NumPy .npy, MatrixMarket	✅
Matrix Functions	matExp, matPow, matSqrt, matLog, Kronecker product	✅
Zero-Alloc APIs	Workspace reuse, *Into() variants, computeFrom()	✅

Zero-Allocation Pattern

For performance-critical loops, use workspace-reuse APIs to eliminate per-iteration allocations:

// Allocate once
var lu = try Zigen.LUDynamic(f64).init(allocator, n);
defer lu.deinit();

// Reuse in hot loop — zero allocation per iteration
for (matrices) |A| {
    lu.computeFrom(A);
    lu.solveInto(b, x_buf, pb_buf, y_buf);
}

Eigen Compatibility

Operation	Eigen C++	Zigen
Zero/Identity	.Zero() .Identity()	.zero() .identity()
Transpose	.transpose()	.transpose()
Multiply	A * B	A.mul(cols, B)
Element access	m(i,j)	m.at(i,j)
LU solve	lu.solve(b)	lu.solve(b)

Key difference: Zig has no operator overloading, so * becomes .mul().

See Eigen Migration Guide for details.

Examples

9 working examples in the examples/ directory. See examples/README.md for the full categorized index.

zig build run-basic_matrix             # Matrix basics
zig build run-linear_algebra           # Decompositions, solve
zig build run-geometry                 # Quaternions, rotations
zig build run-sparse_systems           # Sparse matrices, SparseLU
zig build run-iterative_solvers        # CG, BiCGSTAB
zig build run-dynamic_decompositions   # Workspace-reuse pattern

Example Categories

Category	Examples
Getting Started	basic_matrix, matrix_operations
Linear Algebra	linear_algebra, dynamic_decompositions
Sparse & Iterative	sparse_systems, iterative_solvers
Geometry	geometry
Applications	data_analysis (PCA), image_processing (convolution)

Documentation

Comprehensive documentation is available in the docs/ directory:

• Documentation Index — Full navigation guide
• API Reference — Complete API listing with Eigen comparison
• Eigen Migration — Step-by-step migration from Eigen C++
• Module Docs — Per-module detailed reference (core, decompositions, sparse, solvers, geometry, io)

See also STRUCTURE.md for project layout details.

Testing

zig build test                      # All tests (src + unit + integration)
zig build unit-test                 # Unit tests only
zig build integration-test          # Integration tests only

Test coverage includes:

• Unit tests — Each module's core functionality, error handling, edge cases
• Integration tests — Cross-module workflows combining decompositions, sparse, geometry
• Inline tests — Source-level tests embedded in library code

Benchmarks

Compare Zigen vs Eigen 5.0 performance across 28 tests:

cd bench
./run_benchmark.sh              # dim 64, f64
./run_benchmark.sh --dim 128    # Custom dimension
./run_benchmark.sh --all        # Full sweep (64,256,1024 × f32,f64)

See bench/README.md for details.

Architecture

zigen/
├── src/                    # Pure Zig library
│   ├── zigen.zig          # Root module — re-exports all types
│   ├── core/              # Matrix, Vector, Array, Map, Kronecker (8 files)
│   ├── decompositions/    # LU, QR, Cholesky, SVD, Eigen, Schur (13 files)
│   ├── sparse/            # CSR, COO, SparseLU/Cholesky/QR (6 files)
│   ├── solvers/           # CG, BiCGSTAB, GMRES, preconditioners (3 files)
│   ├── geometry/          # Quaternion, Transform, AngleAxis
│   └── io/                # NumPy .npy I/O
├── test/                  # Tests
│   ├── unit/              # 8 unit test files
│   └── integration/       # Integration tests
├── examples/              # 9 working examples
├── bench/                 # Benchmark system (vs Eigen 5.0)
├── docs/                  # Comprehensive API documentation
├── build.zig              # Build configuration
└── build.zig.zon          # Package manifest

Contributing

1. ⭐ Star and Fork this repository
2. Create a feature branch (git checkout -b feature/new-module)
3. Implement your changes in src/
4. Add unit tests in test/unit/ and integration tests in test/integration/
5. Create an example in examples/
6. Update documentation in docs/
7. Submit a Pull Request

License

MIT License

Acknowledgments

Built with gratitude on the shoulders of giants:

• Eigen — The C++ linear algebra library that inspired Zigen's API design and naming conventions.
• Zig — A modern systems programming language focused on safety, performance, and simplicity, created by Andrew Kelley and the Zig Software Foundation.