dense.h file

Heap vm_mat plus LU / QR / SVD / Cholesky.

Rank-deficient work returns false, not a silent NaN.

Functions

auto vm_mat_alloc(int rows, int cols) -> vm_mat: Allocates a new matrix with the specified dimensions.
void vm_mat_free(vm_mat* m): Frees the memory allocated for a matrix and resets its state.
void vm_mat_zero(vm_mat* m): Sets all elements of the matrix to zero.
auto vm_mat_get(const vm_mat* m, int r, int c) -> vm_float_t: Returns the value of the matrix element at the specified row and column.
void vm_mat_set(vm_mat* m, int r, int c, vm_float_t v): Sets the element at the specified row and column in the matrix to the given value.
auto vm_mat_copy(vm_mat* dst, const vm_mat* src) -> bool: Copies the contents of one matrix to another.
auto vm_mat_det(const vm_mat* A) -> vm_float_t: Determinant of a square matrix via LU.
auto vm_mat_inverse(vm_mat* out, const vm_mat* A) -> bool: Inverse of a square matrix via LU.
auto vm_lu_factor(vm_mat* A, int* pivot, int* sign) -> bool: In-place LU factorization with partial pivoting.
auto vm_lu_solve(const vm_mat* LU, const int* pivot, const vm_float_t* b, vm_float_t* x) -> bool: Solves A x = b from a factored LU.
auto vm_qr_factor(vm_mat* A, vm_float_t* tau) -> bool: In-place Householder QR.
auto vm_qr_unpack(vm_mat* Q, vm_mat* R, const vm_mat* QR, const vm_float_t* tau) -> bool: Thin factors: Q is m x k, R is k x n, k = min(m, n).
auto vm_qr_solve(const vm_mat* QR, const vm_float_t* tau, const vm_float_t* b, vm_float_t* x) -> bool: Least-squares solve min ||A x - b|| from a factored QR.
auto vm_svd_factor(const vm_mat* A, vm_mat* U, vm_float_t* s, vm_mat* V) -> bool: Thin SVD A = U diag(s) V^T.
auto vm_chol_factor(vm_mat* A) -> bool: In-place dense Cholesky A = L Lᵀ (lower triangle overwritten).
auto vm_chol_solve(const vm_mat* L, const vm_float_t* b, vm_float_t* x) -> bool: Solve L Lᵀ x = b after vm_chol_factor.

Function documentation

vm_mat vm_mat_alloc(int rows, int cols)

Allocates a new matrix with the specified dimensions.

Parameters
rows	number of rows in the matrix
cols	number of columns in the matrix
Returns	allocated matrix or zero matrix on failure

Memory is allocated using calloc to initialize all elements to zero. If allocation fails or if dimensions are invalid, a matrix with zero dimensions and NULL data pointer is returned.

void vm_mat_free(vm_mat* m)

Frees the memory allocated for a matrix and resets its state.

Parameters
m	pointer to the matrix to free

If the matrix pointer is NULL, the function returns immediately. The data pointer is freed (if allocated), then set to NULL and both dimensions are reset to zero.

void vm_mat_zero(vm_mat* m)

Sets all elements of the matrix to zero.

Parameters
m	pointer to the matrix to be zeroed

If the matrix pointer or its data pointer is NULL, the function returns immediately without performing any operation.

vm_float_t vm_mat_get(const vm_mat* m, int r, int c)

Returns the value of the matrix element at the specified row and column.

Parameters
m	pointer to the matrix
r	zero-based row index
c	zero-based column index
Returns	value at (r, c) or 0.0f on invalid input

If the matrix pointer is NULL, the data pointer is NULL, or the row or column indices are out of bounds, the function returns 0.0f without accessing memory.

void vm_mat_set(vm_mat* m, int r, int c, vm_float_t v)

Sets the element at the specified row and column in the matrix to the given value.

Parameters
m	pointer to the matrix to modify
r	row index
c	column index
v	value to set at the specified position

The function performs bounds checking and validates the matrix pointer and its data buffer before performing the assignment. If any validation fails, the function returns without modifying any data.

bool vm_mat_copy(vm_mat* dst, const vm_mat* src)

Copies the contents of one matrix to another.

Parameters
dst	pointer to the destination matrix
src	pointer to the source matrix
Returns	true on success, false if either pointer is NULL, source data is NULL or memory allocation fails

If the destination matrix has incompatible dimensions or unallocated data it is freed and reallocated to match the source dimensions. The source matrix must be valid and have allocated data.

vm_float_t vm_mat_det(const vm_mat* A)

Determinant of a square matrix via LU.

Parameters
A	Square matrix (not modified).
Returns	det(A), or 0 on failure.

bool vm_mat_inverse(vm_mat* out, const vm_mat* A)

Inverse of a square matrix via LU.

Parameters
out	Inverse on success.
A	Square matrix (not modified).
Returns	True on success.

Allocates or resizes out when it is not already n x n.

bool vm_lu_factor(vm_mat* A, int* pivot, int* sign)

In-place LU factorization with partial pivoting.

Parameters
A	Square matrix, overwritten with L and U.
pivot	Row permutation; length `A->rows`.
sign	Optional; set to +1 or -1 for the permutation sign.
Returns	True on success.

On success A holds L (unit diagonal, strictly below) and U (on and above the diagonal). pivot[i] is the original row now at position i.

bool vm_lu_solve(const vm_mat* LU, const int* pivot, const vm_float_t* b, vm_float_t* x)

Solves A x = b from a factored LU.

Parameters
LU	Factored matrix from `vm_lu_factor`.
pivot	Row permutation from `vm_lu_factor`.
b	Right-hand side, length `n`.
x	Solution, length `n`.
Returns	True on success.

bool vm_qr_factor(vm_mat* A, vm_float_t* tau)

In-place Householder QR.

Parameters
A	Matrix overwritten with R and Householder vectors.
tau	Householder scales, length `min(m, n)`.
Returns	True on success.

A is m x n.

On success the upper triangle of A is R and the strict lower part stores Householder vectors. tau must hold min(m, n) scalars.

bool vm_qr_unpack(vm_mat* Q, vm_mat* R, const vm_mat* QR, const vm_float_t* tau)

Thin factors: Q is m x k, R is k x n, k = min(m, n).

Parameters
Q	Orthonormal factor on success.
R	Upper-triangular factor on success.
QR	Factored matrix from `vm_qr_factor`.
tau	Householder scales from `vm_qr_factor`.
Returns	True on success.

Allocates or resizes Q and R when they do not already match.

bool vm_qr_solve(const vm_mat* QR, const vm_float_t* tau, const vm_float_t* b, vm_float_t* x)

Least-squares solve min ||A x - b|| from a factored QR.

Parameters
QR	Factored matrix from `vm_qr_factor`.
tau	Householder scales from `vm_qr_factor`.
b	Right-hand side, length `m`.
x	Solution, length `n`.
Returns	True on success.

Requires m >= n. b has length m, x has length n.

bool vm_svd_factor(const vm_mat* A, vm_mat* U, vm_float_t* s, vm_mat* V)

Thin SVD A = U diag(s) V^T.

Parameters
A	Input matrix (not modified).
U	Left singular vectors on success.
s	Singular values, length `min(m, n)`.
V	Right singular vectors on success.
Returns	True on success.

s has length k = min(m, n) (descending). U is m x k, V is n x k (columns are singular vectors). Allocates or resizes U and V.

bool vm_chol_factor(vm_mat* A)

In-place dense Cholesky A = L Lᵀ (lower triangle overwritten).

Parameters
A	Square dense matrix (destroyed / factored in place).
Returns	true on success, false if not SPD or invalid input.

A must be square SPD. The strict upper triangle is left untouched.

bool vm_chol_solve(const vm_mat* L, const vm_float_t* b, vm_float_t* x)

Solve L Lᵀ x = b after vm_chol_factor.

Parameters
L	Factored lower triangle from `vm_chol_factor`.
b	Right-hand side (length n).
x	Solution (length n).
Returns	true on success, false on error.