File syn_matrix.c¶

FileList > src > syntropic > util > syn_matrix.c

Fixed-point Q16.16 matrix operations implementation. More...

#include "../util/syn_assert.h"
#include "syn_matrix.h"
#include <string.h>

Public Functions¶

Type	Name
void	syn_matrix_add (const SYN_Matrix * a, const SYN_Matrix * b, SYN_Matrix * out) Element-wise addition: out = A + B.
void	syn_matrix_copy (SYN_Matrix * dst, const SYN_Matrix * src) Copy matrix contents.
q16_t	syn_matrix_det (const SYN_Matrix * m) Determinant of a square matrix.
SYN_Status	syn_matrix_eigen_sym2 (const SYN_Matrix * A, q16_t evals, SYN_Matrix * E) Compute eigenvalues and eigenvectors of a symmetric 2×2 matrix A.
SYN_Status	syn_matrix_eigen_sym3 (const SYN_Matrix * A, q16_t evals, SYN_Matrix * E) Compute eigenvalues and eigenvectors of a symmetric 3×3 matrix A via Jacobi rotations.
SYN_Status	syn_matrix_get_block (const SYN_Matrix * src, uint8_t r0, uint8_t c0, SYN_Matrix * dst) Extract a submatrix block from src into dst.
void	syn_matrix_identity (SYN_Matrix * m) Set matrix to identity.
SYN_Status	syn_matrix_inv (const SYN_Matrix * m, SYN_Matrix * out) Matrix inverse: out = M⁻¹.
SYN_Status	syn_matrix_inv_lu (const SYN_Matrix * src, SYN_Matrix * dst) Invert an arbitrary N×N matrix via LU decomposition (convenience wrapper).
SYN_Status	syn_matrix_inv_lu_work (const SYN_Matrix * src, SYN_Matrix * dst, q16_t * lu_work, uint8_t * p_work, q16_t * col_work) Invert an arbitrary N×N matrix via LU decomposition using caller-supplied workspace.
SYN_Status	syn_matrix_least_squares (const SYN_Matrix * A, const SYN_Matrix * b, SYN_Matrix * x) Solve overdetermined system A · x ≈ b via Normal Equations (Least Squares).
SYN_Status	syn_matrix_least_squares_work (const SYN_Matrix * A, const SYN_Matrix * b, SYN_Matrix * x, q16_t * ata_work, q16_t * atb_work, q16_t * at_work, q16_t * solver_lu, q16_t * solver_y) Solve overdetermined system A · x ≈ b via Least Squares using caller-supplied workspace.
void	syn_matrix_mul (const SYN_Matrix * a, const SYN_Matrix * b, SYN_Matrix * out) Matrix multiply: out = A × B.
void	syn_matrix_mul_vec (const SYN_Matrix * m, const q16_t * v_in, q16_t * v_out, uint8_t n_in) Matrix–vector multiply: out = M × v.
SYN_Status	syn_matrix_outer_product (const q16_t * u, uint8_t rows, const q16_t * v, uint8_t cols, SYN_Matrix * out) Vector outer product: out = u · vᵀ (rows(u) × cols(v)).
SYN_Status	syn_matrix_qr (const SYN_Matrix * A, SYN_Matrix * Q, SYN_Matrix * R) QR Decomposition: A = Q · R via Modified Gram-Schmidt process.
void	syn_matrix_rotate_2d (SYN_Matrix * out, q16_t angle) Set 3×3 matrix to a 2D rotation.
void	syn_matrix_rotate_x (SYN_Matrix * out, q16_t angle) Set 4×4 matrix to a rotation around the X axis.
void	syn_matrix_rotate_y (SYN_Matrix * out, q16_t angle) Set 4×4 matrix to a rotation around the Y axis.
void	syn_matrix_rotate_z (SYN_Matrix * out, q16_t angle) Set 4×4 matrix to a rotation around the Z axis.
void	syn_matrix_scale (const SYN_Matrix * a, q16_t scalar, SYN_Matrix * out) Scalar multiply: out = A × scalar.
void	syn_matrix_scale_2d (SYN_Matrix * out, q16_t sx, q16_t sy) Set 3×3 matrix to a 2D scale.
SYN_Status	syn_matrix_set_block (SYN_Matrix * dst, uint8_t r0, uint8_t c0, const SYN_Matrix * src) Embed a submatrix block src into dst at position (r0, c0).
SYN_Status	syn_matrix_solve_cholesky (const SYN_Matrix * A, const SYN_Matrix * b, SYN_Matrix * x) Solve symmetric positive-definite system A · x = b via Cholesky (convenience wrapper).
SYN_Status	syn_matrix_solve_cholesky_work (const SYN_Matrix * A, const SYN_Matrix * b, SYN_Matrix * x, q16_t * L_work, q16_t * y_work) Solve system A · x = b via Cholesky decomposition using caller-supplied workspace buffer.
SYN_Status	syn_matrix_solve_lu (const SYN_Matrix * A, const SYN_Matrix * b, SYN_Matrix * x) Solve system A · x = b via LU decomposition (convenience wrapper).
SYN_Status	syn_matrix_solve_lu_work (const SYN_Matrix * A, const SYN_Matrix * b, SYN_Matrix * x, q16_t * lu_work, uint8_t * p_work, q16_t * y_work) Solve system A · x = b via LU decomposition using caller-supplied workspace buffer.
void	syn_matrix_sub (const SYN_Matrix * a, const SYN_Matrix * b, SYN_Matrix * out) Element-wise subtraction: out = A − B.
q16_t	syn_matrix_trace (const SYN_Matrix * m) Trace (sum of diagonal elements).
void	syn_matrix_translate_2d (SYN_Matrix * out, q16_t tx, q16_t ty) Set 3×3 matrix to a 2D translation.
void	syn_matrix_translate_3d (SYN_Matrix * out, q16_t tx, q16_t ty, q16_t tz) Set 4×4 matrix to a 3D translation.
void	syn_matrix_transpose (const SYN_Matrix * a, SYN_Matrix * out) Transpose: out = Aᵀ.
void	syn_matrix_zero (SYN_Matrix * m) Set all elements to zero.
void	syn_vec3_cross (const q16_t * a, const q16_t * b, q16_t * out) Cross product of two 3-element Q16 vectors.
q16_t	syn_vec_dot (const q16_t * a, const q16_t * b, uint8_t n) Dot product of two n-element Q16 vectors.
q16_t	syn_vec_norm (const q16_t * v, uint8_t n) Magnitude (Euclidean norm) of an n-element Q16 vector.
SYN_Status	syn_vec_normalize (const q16_t * v, q16_t * out, uint8_t n) Normalize a vector to unit length.

Public Static Functions¶

Type	Name
q16_t	det_2x2 (const q16_t * d) 2×2 determinant: ad - bc.
q16_t	det_3x3 (const q16_t * d) 3×3 determinant via cofactor expansion along row 0.
q16_t	det_4x4 (const q16_t * d) 4×4 determinant via cofactor expansion along row 0.
SYN_Status	inv_1x1 (const SYN_Matrix * m, SYN_Matrix * out) 1×1 inverse via scalar division: 1/a.
SYN_Status	inv_2x2 (const SYN_Matrix * m, SYN_Matrix * out) 2×2 inverse via adjugate/determinant.
SYN_Status	inv_3x3 (const SYN_Matrix * m, SYN_Matrix * out) 3×3 inverse via adjugate/determinant.
SYN_Status	inv_4x4 (const SYN_Matrix * m, SYN_Matrix * out) 4×4 inverse via Gauss-Jordan elimination with partial pivoting.

Detailed Description¶

All operations use caller-owned storage. No heap allocation. int64_t accumulators preserve full Q16 precision in multiply chains.

Public Functions Documentation¶

function syn_matrix_add¶

Element-wise addition: out = A + B.

void syn_matrix_add (
    const SYN_Matrix * a,
    const SYN_Matrix * b,
    SYN_Matrix * out
)

Parameters:

a First operand.
b Second operand (same dimensions as a).
out Result (same dimensions as a).

function syn_matrix_copy¶

Copy matrix contents.

void syn_matrix_copy (
    SYN_Matrix * dst,
    const SYN_Matrix * src
)

Parameters:

dst Destination (must match src dimensions).
src Source matrix.

function syn_matrix_det¶

Determinant of a square matrix.

q16_t syn_matrix_det (
    const SYN_Matrix * m
)

Supports 2×2, 3×3, and 4×4. Uses cofactor expansion for 2×2/3×3 and LU decomposition for 4×4.

Parameters:

m Square matrix.

Returns:

Determinant in Q16.

function syn_matrix_eigen_sym2¶

Compute eigenvalues and eigenvectors of a symmetric 2×2 matrix A.

SYN_Status syn_matrix_eigen_sym2 (
    const SYN_Matrix * A,
    q16_t evals,
    SYN_Matrix * E
)

Parameters:

A Symmetric 2×2 matrix.
evals Output array of 2 eigenvalues (sorted descending).
E Output 2×2 matrix whose columns are the normalized eigenvectors.

Returns:

SYN_OK on success, SYN_INVALID_PARAM on invalid inputs.

function syn_matrix_eigen_sym3¶

Compute eigenvalues and eigenvectors of a symmetric 3×3 matrix A via Jacobi rotations.

SYN_Status syn_matrix_eigen_sym3 (
    const SYN_Matrix * A,
    q16_t evals,
    SYN_Matrix * E
)

Parameters:

A Symmetric 3×3 matrix.
evals Output array of 3 eigenvalues (sorted descending).
E Output 3×3 matrix whose columns are the normalized eigenvectors.

Returns:

SYN_OK on success, SYN_INVALID_PARAM on invalid inputs.

function syn_matrix_get_block¶

Extract a submatrix block from src into dst.

SYN_Status syn_matrix_get_block (
    const SYN_Matrix * src,
    uint8_t r0,
    uint8_t c0,
    SYN_Matrix * dst
)

Parameters:

src Source matrix (M×N).
r0 Starting row index in src.
c0 Starting column index in src.
dst Destination matrix (R×C). Must fit within src bounds from (r0, c0).

Returns:

SYN_OK on success, SYN_INVALID_PARAM on out-of-bounds.

function syn_matrix_identity¶

Set matrix to identity.

void syn_matrix_identity (
    SYN_Matrix * m
)

Parameters:

m Square matrix.

function syn_matrix_inv¶

Matrix inverse: out = M⁻¹.

SYN_Status syn_matrix_inv (
    const SYN_Matrix * m,
    SYN_Matrix * out
)

Supports 2×2, 3×3, and 4×4 square matrices. Returns SYN_ERROR if the matrix is singular (determinant ≈ 0).

Parameters:

m Input square matrix.
out Output inverse (same dimensions). Must not alias m.

Returns:

SYN_OK on success, SYN_ERROR if singular.

function syn_matrix_inv_lu¶

Invert an arbitrary N×N matrix via LU decomposition (convenience wrapper).

SYN_Status syn_matrix_inv_lu (
    const SYN_Matrix * src,
    SYN_Matrix * dst
)

Parameters:

src Input square matrix (N×N).
dst Output inverse matrix (N×N).

Returns:

SYN_OK on success, SYN_ERROR if src is singular or dimensions invalid.

function syn_matrix_inv_lu_work¶

Invert an arbitrary N×N matrix via LU decomposition using caller-supplied workspace.

SYN_Status syn_matrix_inv_lu_work (
    const SYN_Matrix * src,
    SYN_Matrix * dst,
    q16_t * lu_work,
    uint8_t * p_work,
    q16_t * col_work
)

Parameters:

src Input square matrix (N×N).
dst Output inverse matrix (N×N). Must not alias src.
lu_work Caller-supplied N×N buffer (N*N elements).
p_work Caller-supplied N pivot buffer (N elements).
col_work Caller-supplied N vector buffer (N elements).

Returns:

SYN_OK on success, SYN_ERROR if src is singular or dimensions invalid.

function syn_matrix_least_squares¶

Solve overdetermined system A · x ≈ b via Normal Equations (Least Squares).

SYN_Status syn_matrix_least_squares (
    const SYN_Matrix * A,
    const SYN_Matrix * b,
    SYN_Matrix * x
)

Parameters:

A Overdetermined system matrix (M×N, M ≥ N).
b Right-hand side measurement vector (M×1).
x Output solution parameter vector (N×1).

Returns:

SYN_OK on success, SYN_ERROR if AᵀA is singular.

function syn_matrix_least_squares_work¶

Solve overdetermined system A · x ≈ b via Least Squares using caller-supplied workspace.

SYN_Status syn_matrix_least_squares_work (
    const SYN_Matrix * A,
    const SYN_Matrix * b,
    SYN_Matrix * x,
    q16_t * ata_work,
    q16_t * atb_work,
    q16_t * at_work,
    q16_t * solver_lu,
    q16_t * solver_y
)

Parameters:

A Overdetermined system matrix (M×N, M ≥ N).
b Right-hand side measurement vector (M×1).
x Output solution parameter vector (N×1).
ata_work Caller-supplied N×N matrix buffer (N*N elements).
atb_work Caller-supplied N vector buffer (N elements).
at_work Caller-supplied N×M transpose matrix buffer (N*M elements).
solver_lu Caller-supplied N×N solver matrix buffer (N*N elements).
solver_y Caller-supplied N solver vector buffer (N elements).

Returns:

SYN_OK on success, SYN_ERROR if AᵀA is singular.

function syn_matrix_mul¶

Matrix multiply: out = A × B.

void syn_matrix_mul (
    const SYN_Matrix * a,
    const SYN_Matrix * b,
    SYN_Matrix * out
)

Requires: A.cols == B.rows, out is A.rows × B.cols. Uses int64_t accumulator for full Q16 precision.

Parameters:

a Left operand (R₁ × C₁).
b Right operand (C₁ × C₂).
out Result (R₁ × C₂). Must not alias a or b.

function syn_matrix_mul_vec¶

Matrix–vector multiply: out = M × v.

void syn_matrix_mul_vec (
    const SYN_Matrix * m,
    const q16_t * v_in,
    q16_t * v_out,
    uint8_t n_in
)

Parameters:

m Square or rectangular matrix (R × C).
v_in Input vector (C elements).
v_out Output vector (R elements). Must not alias v_in.
n_in Length of input vector (must equal m->cols).

function syn_matrix_outer_product¶

Vector outer product: out = u · vᵀ (rows(u) × cols(v)).

SYN_Status syn_matrix_outer_product (
    const q16_t * u,
    uint8_t rows,
    const q16_t * v,
    uint8_t cols,
    SYN_Matrix * out
)

Parameters:

u Column vector elements (R elements).
rows Number of rows (R).
v Row vector elements (C elements).
cols Number of columns (C).
out Output matrix (R×C).

Returns:

SYN_OK on success, SYN_INVALID_PARAM if NULL or invalid dimensions.

function syn_matrix_qr¶

QR Decomposition: A = Q · R via Modified Gram-Schmidt process.

SYN_Status syn_matrix_qr (
    const SYN_Matrix * A,
    SYN_Matrix * Q,
    SYN_Matrix * R
)

Decomposes an M×N matrix A (M ≥ N) into orthogonal M×N matrix Q (QᵀQ = I) and upper-triangular N×N matrix R.

Parameters:

A Input matrix (M×N, M ≥ N).
Q Output orthogonal matrix (M×N).
R Output upper-triangular matrix (N×N).

Returns:

SYN_OK on success, SYN_ERROR if A is linearly dependent / singular.

function syn_matrix_rotate_2d¶

Set 3×3 matrix to a 2D rotation.

void syn_matrix_rotate_2d (
    SYN_Matrix * out,
    q16_t angle
)

Parameters:

out Output 3×3 matrix.
angle Rotation angle in Q16 radians (counter-clockwise).

function syn_matrix_rotate_x¶

Set 4×4 matrix to a rotation around the X axis.

void syn_matrix_rotate_x (
    SYN_Matrix * out,
    q16_t angle
)

Parameters:

out Output 4×4 matrix.
angle Rotation angle in Q16 radians.

function syn_matrix_rotate_y¶

Set 4×4 matrix to a rotation around the Y axis.

void syn_matrix_rotate_y (
    SYN_Matrix * out,
    q16_t angle
)

Parameters:

out Output 4×4 matrix.
angle Rotation angle in Q16 radians.

function syn_matrix_rotate_z¶

Set 4×4 matrix to a rotation around the Z axis.

void syn_matrix_rotate_z (
    SYN_Matrix * out,
    q16_t angle
)

Parameters:

out Output 4×4 matrix.
angle Rotation angle in Q16 radians.

function syn_matrix_scale¶

Scalar multiply: out = A × scalar.

void syn_matrix_scale (
    const SYN_Matrix * a,
    q16_t scalar,
    SYN_Matrix * out
)

Parameters:

a Input matrix.
scalar Q16 scalar multiplier.
out Result (same dimensions as a).

function syn_matrix_scale_2d¶

Set 3×3 matrix to a 2D scale.

void syn_matrix_scale_2d (
    SYN_Matrix * out,
    q16_t sx,
    q16_t sy
)

Parameters:

out Output 3×3 matrix.
sx X scale factor in Q16.
sy Y scale factor in Q16.

function syn_matrix_set_block¶

Embed a submatrix block src into dst at position (r0, c0).

SYN_Status syn_matrix_set_block (
    SYN_Matrix * dst,
    uint8_t r0,
    uint8_t c0,
    const SYN_Matrix * src
)

Parameters:

dst Destination matrix (M×N).
r0 Starting row index in dst.
c0 Starting column index in dst.
src Source submatrix block (R×C).

Returns:

SYN_OK on success, SYN_INVALID_PARAM on out-of-bounds.

function syn_matrix_solve_cholesky¶

Solve symmetric positive-definite system A · x = b via Cholesky (convenience wrapper).

SYN_Status syn_matrix_solve_cholesky (
    const SYN_Matrix * A,
    const SYN_Matrix * b,
    SYN_Matrix * x
)

Parameters:

A Symmetric positive-definite system matrix (N×N).
b Right-hand side vector (N×1).
x Output solution vector (N×1). May alias b.

Returns:

SYN_OK on success, SYN_ERROR if A is not positive-definite.

function syn_matrix_solve_cholesky_work¶

Solve system A · x = b via Cholesky decomposition using caller-supplied workspace buffer.

SYN_Status syn_matrix_solve_cholesky_work (
    const SYN_Matrix * A,
    const SYN_Matrix * b,
    SYN_Matrix * x,
    q16_t * L_work,
    q16_t * y_work
)

Parameters:

A Symmetric positive-definite system matrix (N×N).
b Right-hand side vector (N×1).
x Output solution vector (N×1).
L_work Caller-supplied N×N lower triangular buffer (N*N elements).
y_work Caller-supplied N vector buffer (N elements).

Returns:

SYN_OK on success, SYN_ERROR if A is not positive-definite.

function syn_matrix_solve_lu¶

Solve system A · x = b via LU decomposition (convenience wrapper).

SYN_Status syn_matrix_solve_lu (
    const SYN_Matrix * A,
    const SYN_Matrix * b,
    SYN_Matrix * x
)

Parameters:

A Square system matrix (N×N).
b Right-hand side vector (N×1).
x Output solution vector (N×1). May alias b.

Returns:

SYN_OK on success, SYN_ERROR if A is singular or dimensions invalid.

function syn_matrix_solve_lu_work¶

Solve system A · x = b via LU decomposition using caller-supplied workspace buffer.

SYN_Status syn_matrix_solve_lu_work (
    const SYN_Matrix * A,
    const SYN_Matrix * b,
    SYN_Matrix * x,
    q16_t * lu_work,
    uint8_t * p_work,
    q16_t * y_work
)

Zero stack allocation inside solver.

Parameters:

A Square system matrix (N×N).
b Right-hand side vector (N×1).
x Output solution vector (N×1).
lu_work Caller-supplied N×N buffer (N*N elements).
p_work Caller-supplied N pivot buffer (N elements).
y_work Caller-supplied N vector buffer (N elements).

Returns:

SYN_OK on success, SYN_ERROR if A is singular or dimensions invalid.

function syn_matrix_sub¶

Element-wise subtraction: out = A − B.

void syn_matrix_sub (
    const SYN_Matrix * a,
    const SYN_Matrix * b,
    SYN_Matrix * out
)

Parameters:

a Minuend.
b Subtrahend (same dimensions as a).
out Result (same dimensions as a).

function syn_matrix_trace¶

Trace (sum of diagonal elements).

q16_t syn_matrix_trace (
    const SYN_Matrix * m
)

Parameters:

m Square matrix.

Returns:

Trace in Q16.

function syn_matrix_translate_2d¶

Set 3×3 matrix to a 2D translation.

void syn_matrix_translate_2d (
    SYN_Matrix * out,
    q16_t tx,
    q16_t ty
)

Parameters:

out Output 3×3 matrix.
tx X translation in Q16.
ty Y translation in Q16.

function syn_matrix_translate_3d¶

Set 4×4 matrix to a 3D translation.

void syn_matrix_translate_3d (
    SYN_Matrix * out,
    q16_t tx,
    q16_t ty,
    q16_t tz
)

Parameters:

out Output 4×4 matrix.
tx X translation in Q16.
ty Y translation in Q16.
tz Z translation in Q16.

function syn_matrix_transpose¶

Transpose: out = Aᵀ.

void syn_matrix_transpose (
    const SYN_Matrix * a,
    SYN_Matrix * out
)

Parameters:

a Input (R × C).
out Output (C × R). Must not alias a.

function syn_matrix_zero¶

Set all elements to zero.

void syn_matrix_zero (
    SYN_Matrix * m
)

Parameters:

m Matrix to clear.

function syn_vec3_cross¶

Cross product of two 3-element Q16 vectors.

void syn_vec3_cross (
    const q16_t * a,
    const q16_t * b,
    q16_t * out
)

Parameters:

a First vector (3 elements).
b Second vector (3 elements).
out Output vector (3 elements). Must not alias a or b.

function syn_vec_dot¶

Dot product of two n-element Q16 vectors.

q16_t syn_vec_dot (
    const q16_t * a,
    const q16_t * b,
    uint8_t n
)

Parameters:

a First vector.
b Second vector.
n Number of elements.

Returns:

Dot product in Q16.

function syn_vec_norm¶

Magnitude (Euclidean norm) of an n-element Q16 vector.

q16_t syn_vec_norm (
    const q16_t * v,
    uint8_t n
)

Parameters:

v Vector.
n Number of elements.

Returns:

|v| in Q16.

function syn_vec_normalize¶

Normalize a vector to unit length.

SYN_Status syn_vec_normalize (
    const q16_t * v,
    q16_t * out,
    uint8_t n
)

Parameters:

v Input vector (n elements).
out Output unit vector (n elements). May alias v.
n Number of elements.

Returns:

SYN_OK on success, SYN_ERROR if zero-length vector.

Public Static Functions Documentation¶

function det_2x2¶

2×2 determinant: ad - bc.

static q16_t det_2x2 (
    const q16_t * d
)

Parameters:

d Flat 4-element array [a, b, c, d] (row-major).

Returns:

Determinant in Q16.

function det_3x3¶

3×3 determinant via cofactor expansion along row 0.

static q16_t det_3x3 (
    const q16_t * d
)

Parameters:

d Flat 9-element array (row-major).

Returns:

Determinant in Q16.

function det_4x4¶

4×4 determinant via cofactor expansion along row 0.

static q16_t det_4x4 (
    const q16_t * d
)

Parameters:

d Flat 16-element array (row-major).

Returns:

Determinant in Q16.

function inv_1x1¶

1×1 inverse via scalar division: 1/a.

static SYN_Status inv_1x1 (
    const SYN_Matrix * m,
    SYN_Matrix * out
)

Parameters:

m Input 1×1 matrix.
out Output 1×1 inverse.

Returns:

SYN_OK or SYN_ERROR if zero.

function inv_2x2¶

2×2 inverse via adjugate/determinant.

static SYN_Status inv_2x2 (
    const SYN_Matrix * m,
    SYN_Matrix * out
)

Parameters:

m Input 2×2 matrix.
out Output 2×2 inverse.

Returns:

SYN_OK or SYN_ERROR if singular.

function inv_3x3¶

3×3 inverse via adjugate/determinant.

static SYN_Status inv_3x3 (
    const SYN_Matrix * m,
    SYN_Matrix * out
)

Parameters:

m Input 3×3 matrix.
out Output 3×3 inverse.

Returns:

SYN_OK or SYN_ERROR if singular.

function inv_4x4¶

4×4 inverse via Gauss-Jordan elimination with partial pivoting.

static SYN_Status inv_4x4 (
    const SYN_Matrix * m,
    SYN_Matrix * out
)

Parameters:

m Input 4×4 matrix.
out Output 4×4 inverse.

Returns:

SYN_OK or SYN_ERROR if singular.

The documentation for this class was generated from the following file src/syntropic/util/syn_matrix.c