std.matrix

std.matrix provides construction, transpose, and wrapping-multiply helpers for the built-in Matrix<T, R, C> magic type. The type itself — literals, constructors, casts, element-wise operators, @hadamard, Matrix/Matrix, Matrix/Vector and Vector/Matrix multiplication, scaling, masks, bracketed formatting, and indexing — is part of the language; see Matrix Types. Magic types have no methods, so these helpers are free functions.

Exports

Function	Signature	Semantics
transpose	<T: Float, R: usize, C: usize>(m: Matrix<T, R, C>) -> Matrix<T, C, R>	matrix transpose
transpose	<T: Integer, R: usize, C: usize>(m: Matrix<T, R, C>) -> Matrix<T, C, R>	matrix transpose (integer elements)
transpose	<R: usize, C: usize>(m: Matrix<bool, R, C>) -> Matrix<bool, C, R>	mask matrix transpose
fill	<T: Float, R: usize, C: usize>(v: T) -> Matrix<T, R, C>	matrix with every element set to v
fill	<T: Integer, R: usize, C: usize>(v: T) -> Matrix<T, R, C>	matrix with every element set to v (integer elements)
identity	<T: Float, N: usize>() -> Matrix<T, N, N>	the N×N identity matrix
identity	<T: Integer, N: usize>() -> Matrix<T, N, N>	the N×N identity matrix (integer elements)
wrapping_mul	<T: Integer, M: usize, K: usize, N: usize>(a: Matrix<T, M, K>, b: Matrix<T, K, N>) -> Matrix<T, M, N>	matrix multiplication that WRAPS on overflow

transpose and wrapping_mul infer their type arguments from the arguments. fill and identity need explicit instantiation for the dimensions:

For Matrix<T, M, K> and Matrix<T, K, N>, wrapping_mul returns exactly Matrix<T, M, N>. For Matrix<T, R, C>, transpose returns exactly Matrix<T, C, R>.

import std.matrix;

fn main() {
	let a: Matrix<f64, 2, 3> = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]];

	let t = matrix.transpose(a);          // Matrix<f64, 3, 2>
	let z = matrix.fill<f64, 2, 3>(0.0);  // all zeros
	let i = matrix.identity<f64, 3>();    // 3x3 identity
	let n = matrix.identity<i32, 3>();    // integer 3x3 identity

	let p = a * i;                        // == a
	_ = t;
	_ = z;
	_ = p;
	_ = n;
}

Wrapping Multiplication

The * operator on integer matrices is checked by default and traps on overflow (per-cell products AND the accumulation adds). wrapping_mul is the explicit two's-complement alternative: every per-cell product and accumulation wraps in the element type.

import std.matrix;

fn main() {
	let big: Matrix<i32, 1, 2> = [[100000, 0]];
	let col: Matrix<i32, 2, 1> = [[100000], [0]];

	let w = matrix.wrapping_mul(big, col);
	// w[0][0] == 1410065408  (10^10 mod 2^32)
	// big * col would trap: Overflow error: mul overflow
	_ = w;
}

The single T: Integer bound covers signed and unsigned alike — the wrapped bit pattern is sign-agnostic.

How It Works

transpose and wrapping_mul are ordinary exported functions. Their compiler-trusted SDK implementations may invoke private, target-independent semantic intrinsic contracts. transpose's contract is a compile-time lane permutation with no runtime loop; wrapping_mul's contract fixes wrapping products and accumulations. The selected backend may use scalar expansion, vector shuffles, or backend-specific intrinsics without changing those semantics or result types.

Ordinary source cannot call @llvm.matrix.multiply or @llvm.matrix.transpose. Those raw backend spellings are rejected and are not aliases for the private semantic contracts.

fill and identity are plain Zynx code over the matrix fill-literal form ([[v; C]; R]) and element assignment. The integer identity relies on Integer-bounded generic literal fitting (let x: T = 0; accepts literals in [0, 127], the intersection of every integer type's range; a Signed bound widens the window to [-128, 127] — see the marker-interface section of the generics guide).

The helpers do not allocate and do not throw.