https://github.com/coderonion/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.
https://github.com/coderonion/zigen
armadillo cpp eigen hpc linear-algebra math matrix numpy tensor vector zig zigen ziglang
Last synced: about 2 hours ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/coderonion/zigen
- Owner: coderonion
- License: mit
- Created: 2026-02-14T04:33:34.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-14T04:39:28.000Z (5 months ago)
- Last Synced: 2026-06-12T05:30:23.061Z (25 days ago)
- Topics: armadillo, cpp, eigen, hpc, linear-algebra, math, matrix, numpy, tensor, vector, zig, zigen, ziglang
- Language: Zig
- Homepage:
- Size: 161 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```bash
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
```zig
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):**
```zig
.dependencies = .{
.zigen = .{
.path = "../zigen",
},
},
```
**Git URL (for release):**
```zig
.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`
```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
```zig
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:
```zig
// 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](docs/eigen-migration.md) for details.
## Examples
9 working examples in the [`examples/`](examples/) directory. See [examples/README.md](examples/README.md) for the full categorized index.
```bash
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/`](docs/) directory:
- **[Documentation Index](docs/README.md)** — Full navigation guide
- **[API Reference](docs/api.md)** — Complete API listing with Eigen comparison
- **[Eigen Migration](docs/eigen-migration.md)** — Step-by-step migration from Eigen C++
- **[Module Docs](docs/modules/)** — Per-module detailed reference (core, decompositions, sparse, solvers, geometry, io)
See also [STRUCTURE.md](STRUCTURE.md) for project layout details.
## Testing
```bash
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:
```bash
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](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](https://eigen.tuxfamily.org/)** — The C++ linear algebra library that inspired Zigen's API design and naming conventions.
- **[Zig](https://ziglang.org/)** — A modern systems programming language focused on safety, performance, and simplicity, created by Andrew Kelley and the Zig Software Foundation.