include/vecmat/sparse.h file

CSR vm_spmat and Krylov solvers (CG / BiCGSTAB) with Jacobi / SSOR / IC(0).

Functions

void vm_spmat_init(vm_spmat* A)
Sparse matrix triplet (row, column, value).
void vm_spmat_free(vm_spmat* A)
Free sparse matrix storage and reset it.
auto vm_spmat_from_triplets(vm_spmat* A, int n, int nnz, const int* row, const int* col, const vm_float_t* val) -> bool
Build a square CSR matrix from unsorted (row, col, val) triplets.
void vm_spmv(vm_float_t* y, const vm_spmat* A, const vm_float_t* x)
Sparse matrix–vector product y = A x.
auto vm_spmat_diag(const vm_spmat* A, vm_float_t* d) -> bool
Extract the main diagonal of A into d.
auto vm_cg(const vm_spmat* A, const vm_float_t* b, vm_float_t* x, vm_float_t tol, int max_iter, vm_ksp_prec_t pre_cond, vm_ksp_info* info) -> bool
Conjugate gradient for SPD A x = b.
auto vm_bicgstab(const vm_spmat* A, const vm_float_t* b, vm_float_t* x, vm_float_t tol, int max_iter, vm_ksp_prec_t pre_cond, vm_ksp_info* info) -> bool
BiCGSTAB for general (possibly nonsymmetric) A x = b.

Function documentation

void vm_spmat_init(vm_spmat* A)

Sparse matrix triplet (row, column, value).

Parameters
A Sparse matrix (may be NULL).

Initialize a sparse matrix to empty.

void vm_spmat_free(vm_spmat* A)

Free sparse matrix storage and reset it.

Parameters
A Sparse matrix (may be NULL).

bool vm_spmat_from_triplets(vm_spmat* A, int n, int nnz, const int* row, const int* col, const vm_float_t* val)

Build a square CSR matrix from unsorted (row, col, val) triplets.

Parameters
A Output sparse matrix.
n Matrix size (n×n).
nnz Number of input triplets.
row Row indices (length nnz).
col Column indices (length nnz).
val Values (length nnz).
Returns true on success, false on error.

Duplicate (i, j) entries are summed. Out-of-range indices are skipped. On success, existing storage in A is freed and replaced.

void vm_spmv(vm_float_t* y, const vm_spmat* A, const vm_float_t* x)

Sparse matrix–vector product y = A x.

Parameters
y Output vector (length A->n).
A CSR matrix.
x Input vector (length A->n).

bool vm_spmat_diag(const vm_spmat* A, vm_float_t* d)

Extract the main diagonal of A into d.

Parameters
A CSR matrix.
d Output diagonal (length A->n).
Returns true on success, false on error.

Missing diagonal entries are set to 0.

bool vm_cg(const vm_spmat* A, const vm_float_t* b, vm_float_t* x, vm_float_t tol, int max_iter, vm_ksp_prec_t pre_cond, vm_ksp_info* info)

Conjugate gradient for SPD A x = b.

Parameters
A SPD CSR matrix.
b Right-hand side (length A->n).
x Initial guess / solution (length A->n).
tol Relative residual tolerance (≤0 picks a default).
max_iter Max iterations (≤0 defaults to n).
pre_cond NONE, JACOBI, SSOR, or IC0.
info Optional solver stats (may be NULL).
Returns true if converged, false otherwise.

x is the initial guess and the solution. tol is relative residual ||r|| / max(||b||, ε).

Relative residual is ||r|| / max(||b||, ε).

bool vm_bicgstab(const vm_spmat* A, const vm_float_t* b, vm_float_t* x, vm_float_t tol, int max_iter, vm_ksp_prec_t pre_cond, vm_ksp_info* info)

BiCGSTAB for general (possibly nonsymmetric) A x = b.

Parameters
A CSR matrix.
b Right-hand side (length A->n).
x Initial guess / solution (length A->n).
tol Relative residual tolerance (≤0 picks a default).
max_iter Max iterations (≤0 defaults to 2n).
pre_cond NONE, JACOBI, SSOR, or IC0.
info Optional solver stats (may be NULL).
Returns true if converged, false otherwise.

Same calling convention as vm_cg. Jacobi / SSOR / IC0 are left preconditioners; IC0 still expects an SPD-like diagonal.

Relative residual is ||r|| / max(||b||, ε).