Matrices

Matrices

Sun provides N-dimensional matrices through the standard library Matrix<T> class. Matrices support bracket indexing syntax and are backed by contiguous heap memory.

Using the Standard Library

Include stdlib.moon in your manifest:

manifest {
  libraries: ["stdlib.moon"]
}

Creating Matrices

Use Matrix<T>(allocator, shape) to create a matrix with the specified dimensions:

using std.linalg;
using std;
 
function main() i32 throws {
  // 1D array (vector) of 10 elements
  var v = Matrix<i32>(std.mem.global_allocator, [10]);
 
  // 2D matrix (3x4)
  var m = Matrix<i32>(std.mem.global_allocator, [3, 4]);
 
  // 3D tensor (2x3x4)
  var t = Matrix<f64>(std.mem.global_allocator, [2, 3, 4]);
 
  return 0;
}
 
manifest {
  libraries: ["stdlib.moon"]
}

To initialize the elements as well, pass an array literal first and the allocator second. The matrix infers all dimensions and owns independent storage:

using std.linalg;
var m = Matrix<f32>([[1.0f32, 2.0f32], [3.0f32, 4.0f32]], allocator);
var value = m[1, 0];  // 3.0f32

This constructor also accepts an existing array by reference. Use elements of the matrix's type, such as Matrix<i64>([1i64, 2i64], allocator). Putting the values first keeps integer data distinct from the shape in Matrix<i64>(allocator, [2, 3]).

Indexing

Access elements using comma-separated indices in brackets:

using std.linalg;
using std;
 
function main() i32 throws {
  var m = Matrix<i32>(std.mem.global_allocator, [3, 3]);
 
  // Assignment
  m[0, 0] = 1;
  m[1, 1] = 5;
  m[2, 2] = 9;
 
  // Reading
  var diag = m[0, 0] + m[1, 1] + m[2, 2];  // 15
 
  return diag;
}
 
manifest {
  libraries: ["stdlib.moon"]
}

For 1D matrices:

using std.linalg;
using std;
 
function main() i32 throws {
  var arr = Matrix<i32>(std.mem.global_allocator, [5]);
  arr[0] = 10;
  arr[1] = 20;
  arr[2] = 30;
  return arr[0] + arr[1] + arr[2];  // 60
}

Matrix Methods

get(indices) / set(indices, value)

Direct method access (equivalent to bracket syntax):

var val = m.get([i, j]);  // Same as m[i, j]
m.set([i, j], value);  // Same as m[i, j] = value

dim(i)

Returns the size of dimension i; ndims() returns how many dimensions there are. The matrix owns a copy of the shape it was built from.

using std.linalg;
using std.io;
 
function main() void throws {
  var m = Matrix<i32>(std.mem.global_allocator, [3, 4]);
 
  println(m.dim(0));  // 3
  println(m.dim(1));  // 4
 
  println(m.dim(0) * m.dim(1));  // 12
}

size()

Returns the total number of elements:

using std.linalg;
 
function main() void throws {
  var m = Matrix<i32>(std.mem.global_allocator, [3, 4]);
 
  std.io.println(m.size());  // 12
}

ndims()

Returns the number of dimensions:

using std.linalg;
 
function main() void throws {
  var t = Matrix<f32>(std.mem.global_allocator, [2, 3, 4]);
 
  std.io.println(t.ndims());  // 3
}

Matrix Views

MatrixView<T> provides a non-owning view into a Matrix<T> or another view. Views share memory with the original matrix.

Creating Views

Views are created by slicing a matrix. A view owns its own shape and strides and points at the matrix's elements:

using std.linalg;
 
function main() i32 throws {
  var m = Matrix<i32>(std.mem.global_allocator, [9]);
  for (var i: i64 = 0; i < 9; i = i + 1) { m[i] = i; }
 
  // Elements 2, 3, 4 of m (shares memory with m)
  var view = m[2:5];
  return view[1] + view.dim(0);  // 3 + 3
}

Views do not own their data. The original matrix must remain valid while the view is in use.

How Operator Overloading Works

When you write m[i, j], the compiler translates it to method calls:

SyntaxCompiler Translation
m[i, j] (read)m.__index__([i, j])
m[i, j] = v (write)m.__setindex__([i, j], v)

To make your own class indexable, implement __index__ and __setindex__:

/** Owns checked storage and exposes bracket indexing. */
class MyArray {
  var data: ContiguousBuffer<i32>;
 
  /** Allocates storage that is freed when the array goes out of scope. */
  init(allocator: const ref std.mem.HeapAllocator, size: i64) throws {
    this.data = ContiguousBuffer<i32>(allocator, size);
  }
 
  /** Reads an element with bounds checking. */
  method __index__(indices: const ref array<i64>) i32 throws {
    return this.data[indices[0]];
  }
 
  /** Writes an element with bounds checking. */
  method __setindex__(indices: const ref array<i64>, value: i32) void throws {
    this.data[indices[0]] = value;
  }
}
 
function main() i32 throws {
  var arr = MyArray(std.mem.global_allocator, 10);
  arr[0] = 42;  // Calls __setindex__
  return arr[0];  // Calls __index__, returns 42
}

Complete Example

using std.linalg;
using std;
 
function main() i32 throws {
  // Create a 3x3 identity matrix
  var identity = Matrix<i32>(std.mem.global_allocator, [3, 3]);
 
  // Initialize to zero
  for (var i: i64 = 0; i < 3; i = i + 1) {
    for (var j: i64 = 0; j < 3; j = j + 1) {
      identity[i, j] = 0;
    }
  }
 
  // Set diagonal to 1
  identity[0, 0] = 1;
  identity[1, 1] = 1;
  identity[2, 2] = 1;
 
  // Sum the diagonal
  var trace = identity[0, 0] + identity[1, 1] + identity[2, 2];
 
  return trace;  // 3
}
 
manifest {
  libraries: ["stdlib.moon"]
}

Memory Management

std.linalg.Matrix<T> owns its elements in a std.ContiguousBuffer<T> and retains an allocator handle. Its storage is freed when the matrix goes out of scope; views borrow that storage.

using std.linalg;
using std;
 
function createMatrix() i32 throws {
  var m = Matrix<i32>(std.mem.global_allocator, [100, 100]);
  m[50, 50] = 42;
  return m[50, 50];
 
  // m is automatically freed here
}
 
manifest {
  libraries: ["stdlib.moon"]
}

GPU matrices

The optional NVIDIA library supplies cuda.DeviceMatrix<T>, explicit host/device transfers, and GPU arithmetic. Host std.linalg.Matrix<T> retains its existing storage and indexing behavior.

Matrix multiplication methods and operator

For Matrix<f32> and Matrix<f64>, a * b performs matrix multiplication and returns Matrix<T>, throwing LinalgError on validation failure. Call it inside a try block or a function declared throws. Both operands are borrowed and must have the same element type. The result owns independent storage allocated through the left operand's allocator. This operator allocates intentionally; use the methods below when reusing output storage.

using std;
using std.linalg;
 
/** Demonstrates allocating multiplication and reusable output storage. */
function multiply() void throws {
  var a = Matrix<f64>([[1.0, 2.0], [3.0, 4.0]], std.mem.global_allocator);
  var b = Matrix<f64>([[5.0, 6.0], [7.0, 8.0]], std.mem.global_allocator);
  var product = (a * b);
  var output = Matrix<f64>(std.mem.global_allocator, [2, 2]);
  a.matmul_into(b, output);  // output = a * b, without allocation
  output.gemm(1.0, a, Transpose.None, b, Transpose.None, 1.0);
  // output now contains twice a * b; product and both inputs are unchanged.
  return;
}
 
/** Converts a failed matrix operation into a nonzero exit status. */
function main() i32 throws {
  try {
    multiply();
    return 0; } catch (error: LinalgError) { return 1; }
}
 
manifest {
  libraries: ["stdlib.moon"]
}

a.matmul_into(b, output) overwrites output without reading its old values. output.gemm(alpha, a, trans_a, b, trans_b, beta) updates output using the full GEMM formula and supports transposed inputs. Both methods allocate no storage and preserve the destination on validation errors. They require a correctly shaped destination that does not share storage with either input.

std.linalg.matmul(a, b, allocator) provides the same allocating product as a * b with an explicitly chosen allocator. Allocating multiplication checks input ranks, compatible shapes, and output size overflow before allocating. Integer matrices remain available as containers but cannot use these floating-point multiplication operations. Matrix addition and elementwise multiplication are not provided by these methods.

GEMM matrix multiplication

std.linalg.gemm computes C = alpha * op(A) * op(B) + beta * C for Matrix<f32> and Matrix<f64>. Supply an existing two-dimensional destination; GEMM does not allocate output or heap scratch storage.

using std;
using std.linalg;
 
/** Multiplies two matrices into caller-owned output storage. */
function multiply() void throws {
  var a = Matrix<f64>([[1.0, 2.0], [3.0, 4.0]], std.mem.global_allocator);
  var b = Matrix<f64>([[5.0, 6.0], [7.0, 8.0]], std.mem.global_allocator);
  var c = Matrix<f64>(std.mem.global_allocator, [2, 2]);
  gemm<f64>(1.0, a, Transpose.None, b, Transpose.None, 0.0, c);
  // c now contains [[19, 22], [43, 50]].
  return;
}
 
/** Converts a failed matrix operation into a nonzero exit status. */
function main() i32 throws {
  try {
    multiply();
    return 0; } catch (error: LinalgError) { return 1; }
}
 
manifest {
  libraries: ["stdlib.moon"]
}

Transpose.Transpose uses an input's transposed orientation without copying it. For example, gemm<f64>(1.0, a, Transpose.Transpose, a, Transpose.None, 0.0, c) computes AᵀA; the destination must have the corresponding shape.

The shape-only matrix constructor leaves elements uninitialized. When beta is zero, GEMM overwrites C without reading it, so newly allocated output is valid. Otherwise initialize C before the call. Initialize input elements when they will be read; alpha == 0 or an empty inner dimension skips input reads and only scales the output. Empty output dimensions are accepted.

All validation precedes output writes. Failures throw LinalgError, whose reason() identifies invalid dimensions, incompatible shapes, or output storage shared with an input. Inputs may share storage with each other, but the destination must be separate even when alpha is zero. Constructing an error does not allocate; requesting its message() creates a string. Matrix views and integer matrices are not supported by this API.

For f32, GEMM uses explicit SIMD when B has contiguous logical columns. This applies to a * b, matmul_into, and both GEMM interfaces. Transposing A still permits SIMD; noncontiguous transposed B and all f64 products use the scalar path.

Small products use 4×4 register tiles. Products with at least 16 rows, 16 columns, and an inner dimension of at least 32 use packing. Once there is enough work to amortize the capability check, supported x86-64 CPUs automatically select an isolated AVX2/FMA kernel. It checks CPU features and OS support for XMM/YMM state; other CPUs use portable 4×8 tiles.

The AVX2/FMA kernel processes packed blocks in row-first order using 4×16 tiles and paired inner-loop iterations. The portable kernel uses four-step unrolling. Both retain increasing inner-dimension order, including cleanup iterations. Full AVX2/FMA panels hold up to 128 inner elements and 128 columns; portable panels hold up to 64 of each. Both process up to 32 rows at a time.

Packing reserves 80 KiB of stack scratch plus a 256-byte edge-output tile, with no heap allocation. Scratch is local to each call; only active panels are initialized and read. Packing copies input elements, not owning matrices, and never changes matrix shape, storage alignment, or padding.

The AVX2/FMA edge pass reuses those buffers with inner panels of up to 1024 elements. It zero-fills missing input lanes and computes into the temporary output tile, copying only valid elements back. A single leftover column uses scalar accumulation to avoid excessive padding. Portable remainders use four-lane SIMD for leftover rows and scalar arithmetic for leftover columns, keeping each sum in registers across the inner dimension.

Packed kernels apply beta on the first inner panel only. With zero beta they initialize accumulators without reading old output; subsequent panels continue the sum. Portable remainders are scaled separately. For zero alpha or an empty inner dimension, GEMM only scales output and does not read inputs.

SIMD kernels permit hardware fused multiply-add automatically; no software FMA fallback is required. Scalar paths retain separate multiply/add, so rounding can vary with target, shape, and layout. Every kernel accumulates in increasing inner-dimension order without reassociation or fast-math. This implementation is single-threaded, and performance depends on shape and CPU.

The underlying SIMD API is also available for other numeric algorithms.