linear-algebra

Kind	ffi-zig
Categories	math numeric ffi
Keywords	linear-algebra blas lapack matrix vector math numeric zig-ffi

High-performance linear algebra via BLAS/LAPACK (uses Accelerate on macOS, OpenBLAS on Linux)

Files

File	Description
`kit.toml`	Package manifest with metadata and dependencies
`src/main.kit`	Main module - exports all public functions and types
`zig/linear_algebra.zig`	FFI bindings to BLAS/LAPACK via Accelerate/OpenBLAS
`tests/linear-algebra.test.kit`	Comprehensive test suite (93 tests)
`examples/basic.kit`	Basic vector, matrix, and decomposition examples
`examples/least-squares.kit`	Linear and polynomial regression
`examples/decompositions.kit`	LU, QR, Cholesky, and SVD factorizations
`examples/eigenvalues.kit`	Eigenvalue problems and spectral properties
`examples/3d-vectors.kit`	Cross product, projections, and 3D geometry
`examples/transformations.kit`	2D rotation, scaling, reflection, and shear
`examples/matrix-norms.kit`	Matrix norms, condition numbers, and rank
`LICENSE`	MIT license file

Dependencies

No Kit package dependencies.

Architecture

Features

BLAS Operations - Vectors (dot product, norm, scaling) and matrices (multiplication, transpose)
LAPACK Decompositions - LU, QR, Cholesky, eigenvalues/eigenvectors, singular value decomposition
Linear System Solving - Solve Ax = b efficiently
Matrix Properties - Determinant, inverse, trace, rank, condition number
Advanced Operations - Pseudoinverse, matrix norms, least squares
Platform Support - Uses Accelerate framework on macOS, OpenBLAS on Linux
Type-Safe - Compile-time type checking with custom Matrix and Vector types

Requirements

Kit compiler
macOS: Built-in Accelerate framework (no installation needed)
Linux: OpenBLAS library (see install commands below)

Linux OpenBLAS Installation

Distribution	Command
Ubuntu/Debian	`sudo apt install libopenblas-dev`
Fedora	`sudo dnf install openblas-devel`
Arch	`sudo pacman -S openblas`
Alpine	`apk add openblas-dev`

Installation

In your project directory, add the package as a dependency:

kit add gitlab.com/kit-lang/packages/kit-linear-algebra.git

Then import it in your Kit code:

import Kit.LinearAlgebra
# or with an alias
import Kit.LinearAlgebra as LA

Quick Start

import Kit.LinearAlgebra as LA

# Vector operations
x = [1.0, 2.0, 3.0]
y = [4.0, 5.0, 6.0]

# Dot product
match LA.dot x y
  | Ok result -> print "dot product: ${result}"  # 32.0
  | Err e -> print "error: ${e}"

# Vector norm (Euclidean length)
match LA.norm [3.0, 4.0]
  | Ok result -> print "norm: ${result}"  # 5.0
  | Err e -> print "error: ${e}"

# Matrix multiplication
a = [[1.0, 2.0], [3.0, 4.0]]
b = [[5.0, 6.0], [7.0, 8.0]]

match LA.matmul a b
  | Ok c -> print "product: ${c}"
  | Err e -> print "error: ${e}"

# Solve linear system: 2x + y = 5, x + 3y = 6
coeffs = [[2.0, 1.0], [1.0, 3.0]]
rhs = [5.0, 6.0]

match LA.solve coeffs rhs
  | Ok solution -> print "x = ${List.head solution ?? 0}, y = ${List.at solution 1 ?? 0}"
  | Err e -> print "error: ${e}"

API Reference

Vector Operations (BLAS Level 1)

Function	Description
`dot(x, y)`	Dot product of two vectors: x · y
`norm(x)`	Euclidean norm (L2) of a vector
`asum(x)`	Sum of absolute values (L1 norm)
`iamax(x)`	Index of element with maximum absolute value
`scale(α, x)`	Scale vector by scalar: α × x
`axpy(α, x, y)`	AXPY operation: α × x + y
`add(x, y)`	Add two vectors: x + y
`sub(x, y)`	Subtract vectors: x - y
`normalize(x)`	Normalize vector to unit length

Matrix-Vector Operations (BLAS Level 2)

Function	Description
`matvec(a, x)`	Matrix-vector multiplication: A × x

Matrix Operations (BLAS Level 3)

Function	Description
`matmul(a, b)`	Matrix multiplication: A × B
`transpose(a)`	Matrix transpose: Aᵀ
`mat-scale(α, a)`	Scale matrix by scalar: α × A
`mat-add(a, b)`	Add two matrices element-wise: A + B
`mat-sub(a, b)`	Subtract matrices element-wise: A - B

Matrix Properties

Function	Description
`det(a)`	Determinant of a square matrix
`inverse(a)`	Matrix inverse: A⁻¹
`trace(a)`	Trace (sum of diagonal elements)
`rank(a)`	Matrix rank via SVD
`cond(a)`	Condition number (ratio of largest to smallest singular value)
`shape(a)`	Get shape as {rows, cols}
`rows(a)`	Number of rows
`cols(a)`	Number of columns
`diag(a)`	Extract diagonal of a matrix
`is-square?(a)`	Check if matrix is square

Matrix Norms

Function	Description
`norm-1(a)`	1-norm (maximum column sum)
`norm-inf(a)`	Infinity norm (maximum row sum)
`norm-fro(a)`	Frobenius norm: √(Σᵢⱼ aᵢⱼ²)

Matrix Constructors

Function	Description
`identity(n)`	Identity matrix of size n×n
`zeros(rows, cols)`	Zero matrix
`ones(rows, cols)`	Matrix of ones

Decompositions (LAPACK)

Function	Description
`lu(a)`	LU decomposition with partial pivoting
`qr(a)`	QR decomposition: A = QR
`cholesky(a)`	Cholesky decomposition for positive definite matrices
`solve(a, b)`	Solve linear system A × x = b
`lstsq(a, b)`	Least squares solution via QR
`eig-symmetric(a)`	Eigenvalues/eigenvectors of symmetric matrix
`svd(a)`	Singular value decomposition: A = UΣVᵀ
`pinv(a)`	Moore-Penrose pseudoinverse via SVD

Types

All operations use two main types:

type Matrix = Matrix {rows: [[Float]]}
type Vector = [Float]

Error results return Result T String where T is the result type.

Error Type

type LinAlgError =
  | DimensionMismatch {message: String}
  | SingularMatrix {message: String}
  | InvalidArgument {message: String}
  | AllocationFailed {message: String}
  | ConvergenceFailed {message: String}

Examples

Running Examples

cd kit-linear-algebra

# Basic operations (vectors, matrices, solving systems)
kit run examples/basic.kit

# Least squares regression (linear and polynomial fitting)
kit run examples/least-squares.kit

# Matrix decompositions (LU, QR, Cholesky, SVD)
kit run examples/decompositions.kit

# Eigenvalue problems (symmetric matrices, spectral properties)
kit run examples/eigenvalues.kit

# 3D vector operations (cross product, projections, angles)
kit run examples/3d-vectors.kit

# 2D transformations (rotation, scaling, reflection, shear)
kit run examples/transformations.kit

# Matrix norms and condition numbers
kit run examples/matrix-norms.kit

Computing Eigenvalues

import Kit.LinearAlgebra as LA

# Symmetric matrix
symmetric = [[2.0, 1.0], [1.0, 2.0]]

match LA.eig-symmetric symmetric
  | Ok {values, vectors} ->
      print "Eigenvalues: ${values}"
      print "Eigenvectors: ${vectors}"
  | Err e ->
      print "Error: ${e}"

Singular Value Decomposition

import Kit.LinearAlgebra as LA

# Rectangular matrix
rect = [[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]

match LA.svd rect
  | Ok {u, s, vt} ->
      print "Singular values: ${s}"
      print "U matrix: ${u}"
      print "V^T matrix: ${vt}"
  | Err e ->
      print "Error: ${e}"

Vector Operations

import Kit.LinearAlgebra as LA

x = [1.0, 0.0, 0.0]
y = [0.0, 1.0, 0.0]

# Orthogonal vectors have dot product = 0
match LA.dot x y
  | Ok result -> print "Orthogonal: ${result == 0.0}"
  | Err e -> print "Error: ${e}"

# Normalize to unit vector
match LA.normalize [3.0, 4.0]
  | Ok unit -> print "Unit vector: ${unit}"
  | Err e -> print "Error: ${e}"

Performance Notes

macOS: Uses Apple's Accelerate framework with optimized BLAS/LAPACK routines
Linux: Uses OpenBLAS for high-performance linear algebra
All operations are designed for numerical stability and efficiency
BLAS Level 1, 2, and 3 operations are available for different computational complexity

License

MIT License - see LICENSE for details.

This package provides bindings to:

Apple Accelerate (macOS)
OpenBLAS (Linux)

Exported Functions & Types

`Matrix`

A matrix represented as a list of rows, where each row is a list of floats.

Use Matrix.from rows to create, Matrix.rows matrix to unwrap.

Variants

Matrix {rows}

`Vector`

A vector represented as a list of floats.

Use Vector.from values to create, Vector.values vec to unwrap.

Variants

Vector {values}

`LinAlgError`

Error types for linear algebra operations.

Variants

DimensionMismatch {message}

Matrix/vector dimensions are incompatible

SingularMatrix {message}

Matrix is singular (non-invertible)

InvalidArgument {message}

Invalid input parameter

AllocationFailed {message}

Memory allocation failed

ConvergenceFailed {message}

Iterative algorithm did not converge

`LUResult`

Result type for LU decomposition.

Contains the combined L and U matrices and pivot indices.

Variants

LUResult {lu, pivots}

`EigenResult`

Result type for eigenvalue decomposition.

Contains eigenvalues (λ) and corresponding eigenvectors.

Variants

EigenResult {values, vectors}

`SVDResult`

Result type for singular value decomposition (SVD).

For A = UΣVᵀ, contains: - u: Left singular vectors (m×m orthogonal matrix) - s: Singular values (diagonal of Σ) - vt: Right singular vectors transposed (Vᵀ, n×n orthogonal matrix)

Variants

SVDResult {u, s, vt}

`ShapeResult`

Result type for matrix shape query.

Variants

ShapeResult {rows, cols}

`add`

Adds two vectors element-wise: x + y.

[Float] -> [Float] -> Result [Float] String

`sub`

Subtracts two vectors element-wise: x - y.

[Float] -> [Float] -> Result [Float] String

`mat-add`

Adds two matrices element-wise: A + B.

Requires matrices to have the same dimensions.

[[Float]] -> [[Float]] -> Result [[Float]] String

`mat-sub`

Subtracts two matrices element-wise: A - B.

Requires matrices to have the same dimensions.

[[Float]] -> [[Float]] -> Result [[Float]] String

`diag`

Extracts the diagonal elements of a matrix.

Returns [A₀₀, A₁₁, A₂₂, ...].

[[Float]] -> [Float]

`is-square?`

Checks if a matrix is square (m = n).

[[a]] -> Bool

`rows`

Returns the number of rows in a matrix.

[[a]] -> Int

`cols`

Returns the number of columns in a matrix.

[[a]] -> Int