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.0f32This 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] = valuedim(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:
| Syntax | Compiler 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.