API reference

The public API is split across two modules: the JAX frontend in sparsax and the optional PyTensor frontend in sparsax.pytensor.

JAX frontend (sparsax)

Sparse Cholesky (CHOLMOD) solvers for symmetric positive definite matrices, exposed as XLA FFI custom calls that run at full native speed inside @jax.jit (and lax.scan / lax.fori_loop). Symbolic analysis is cached on the sparsity pattern, so repeated solves with the same pattern only pay for the numeric refactorization.

solve

Solve A x = b for symmetric positive definite sparse A.

logdet

Log-determinant of a symmetric positive definite sparse matrix.

selinv

Selected inverse: entries of A^{-1} at A's sparsity pattern.

rcond

A cheap estimate of the reciprocal condition number of an SPD matrix.

factor_solve

Factor A once, then run several solve chains from that one factor.

sample_gaussian

Draw eta ~ N(A^{-1} b, A^{-1}) from a single factorization of A.

update_solve

Solve (A ± C C') x = b via a rank-k update of A's factor.

argmax_logprob

Log-probability that chosen is the largest component of a sparse-precision Gaussian.

solve_bcoo

solve() for a JAX BCOO matrix A.

logdet_bcoo

logdet() for a JAX BCOO matrix A.

update_solve_bcoo

update_solve() for a JAX BCOO base matrix A.

set_options

Configure sparsax for this process.

clear_cache

Free all cached symbolic analyses and factorizations.

cache_size

Number of sparsity patterns currently cached.

factorization_count

Total numeric (re)factorizations performed since import.

Factor tokens (hold a numeric factor open)

Factor SPD A once, then issue an unbounded sequence of solves + a logdet against the held factor without re-hashing Ax or refactoring. This is the “hold the factor open” primitive that factor_solve() (which fuses a fixed set of solves into one call) cannot express: a recurrence V_{j+1} = A^{-1}(G V_j) (a shift-invert Krylov basis) needs the previous solve’s output as the next solve’s input. Not differentiable; use solve() / logdet() when gradients are needed.

factor

Factor SPD A once, returning a reusable factor token.

solve_factor

Solve A x = b using a pre-computed factor (no refactor).

logdet_factor

Return log|A| from a pre-computed factor (no refactor).

set_num_cache_size

Cap the value-keyed numeric-factor cache per CHOLMOD pattern (default 32).

Sparse LU (KLU)

Sparse LU solver for general (non-symmetric) matrices, e.g. A = I - rho W for a row-standardised spatial weights matrix. See Sparse LU (UMFPACK) below for the second LU backend and when to prefer it.

lu_solve

Solve A x = b for a general (non-symmetric) sparse A via KLU.

lu_solve_bcoo

lu_solve() for a JAX BCOO matrix A.

lu_logdet

Log-determinant of a general (non-symmetric) sparse matrix via KLU.

lu_slogdet

Sign and log-absolute-determinant of a sparse matrix via KLU.

lu_rcond

A cheap estimate of the reciprocal condition number of A, via KLU.

lu_logdet_bcoo

lu_logdet() for a JAX BCOO matrix A.

KLU factor tokens

The non-symmetric analogue of the CHOLMOD factor tokens: factor general A once via KLU, then issue an unbounded sequence of solves (A x = b or A^T x = b) and a logdet against the held factor. The token holds a strong reference to the numeric factor, so the per-pattern LRU cannot evict it while the token is live. Not differentiable.

lu_factor

Factor general (non-symmetric) A once via KLU, return a token.

lu_solve_factor

Solve A x = b (or A^T x = b) using a pre-computed KLU factor.

lu_logdet_factor

Return log|det(A)| from a pre-computed KLU factor (no refactor).

set_lu_cache_size

Set how many KLU numeric factors are retained per sparsity pattern.

Sparse LU (UMFPACK)

The second LU backend, interchangeable with the KLU functions above — same arguments, same results, same JIT/vmap/autodiff behaviour — and differing only in which graph it is fast on. KLU has a refactor stage that reuses its pivot ordering across value changes and wins several-fold while the graph is sparse; UMFPACK re-pivots on every numeric factorization but is multifrontal and uses BLAS3, and wins several-fold once the graph densifies. The crossover falls as n grows (mean degree around 30 at n = 1,500, around 15 at n = 12,000), so lu_backend() routes on KLU’s flops per factor entry, which depends on the sparsity pattern alone.

umf_logdet() reads log|det(A)| from umfpack_*_get_determinant, which returns the determinant in mantissa/exponent form. KLU exposes no equivalent, so lu_logdet() reconstructs it from U’s diagonal and the row scale factors as a sum of n logarithms. Both are overflow-safe and agree closely; UMFPACK’s is the more accurate at large n, having no rounding accumulated over n terms.

umf_solve

Solve A x = b for a general (non-symmetric) sparse A via UMFPACK.

umf_solve_bcoo

umf_solve() for a JAX BCOO matrix A.

umf_logdet

Log-determinant of a general (non-symmetric) sparse matrix via UMFPACK.

umf_slogdet

Sign and log-absolute-determinant of a sparse matrix via UMFPACK.

umf_rcond

A cheap estimate of the reciprocal condition number of A, via UMFPACK.

lu_backend

Choose the faster LU backend for a sparsity pattern.

LUBackend

One LU backend's functions, all with the lu_* signatures.

umf_logdet_bcoo

umf_logdet() for a JAX BCOO matrix A.

UMFPACK factor tokens

The UMFPACK counterpart of the KLU factor tokens, with identical semantics: factor once, then issue an unbounded sequence of solves (A x = b or A^T x = b) and a logdet against the held factor. Not differentiable.

umf_factor

Factor general (non-symmetric) A once via UMFPACK, return a token.

umf_solve_factor

Solve A x = b (or A^T x = b) using a pre-computed UMFPACK factor.

umf_logdet_factor

Return log|det(A)| from a pre-computed UMFPACK factor (no refactor).

set_umf_cache_size

Set how many UMFPACK numeric factors are retained per sparsity pattern.

set_token_cache_size

Keep at most n factor tokens per backend (default 64).

Solve modes

Constants selecting which system is solved by solve() and update_solve(). The factorization is P'LL'P = A, so e.g. sampling from N(0, A^{-1}) is solve(..., z, mode=MODE_LT) followed by solve(..., ., mode=MODE_PT).

MODE_A

int([x]) -> integer int(x, base=10) -> integer

MODE_LDLT

int([x]) -> integer int(x, base=10) -> integer

MODE_LD

int([x]) -> integer int(x, base=10) -> integer

MODE_DLT

int([x]) -> integer int(x, base=10) -> integer

MODE_L

int([x]) -> integer int(x, base=10) -> integer

MODE_LT

int([x]) -> integer int(x, base=10) -> integer

MODE_D

int([x]) -> integer int(x, base=10) -> integer

MODE_P

int([x]) -> integer int(x, base=10) -> integer

MODE_PT

int([x]) -> integer int(x, base=10) -> integer

PyTensor frontend (sparsax.pytensor)

A second frontend over the same cached CHOLMOD core, for use with PyMC’s default (PyTensor) backend — including gradient-based samplers like NUTS. These are pure-Python Ops whose perform calls the numpy-callable core; they do not go through JAX/XLA. Install with pip install sparsax[pytensor].

solve

Solve A x = b for SPD sparse A (PyTensor).

logdet

log|A| (PyTensor), differentiable in Ax.

selinv

Selected inverse A^-1 at the pattern (PyTensor).

PyTensor Ops

The Op classes backing the convenience functions above. Documented for users who need to construct or introspect them directly.

class sparsax.pytensor.CholmodSolve(mode=0)[source]

Solve A x = b (or a factor-part system) from cached CHOLMOD factor.

Differentiable in Ax and b only for mode == MODE_A; other modes are not differentiable (their VJP is undefined, matching the JAX solve).

class sparsax.pytensor.CholmodLogdet(n)[source]

log|A|. Differentiable in Ax via the selected inverse.

class sparsax.pytensor.CholmodSelinv(n)[source]

Selected inverse: A^-1 at A’s pattern. Not differentiable.