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 |
|
Log-determinant of a symmetric positive definite sparse matrix. |
|
Selected inverse: entries of |
|
A cheap estimate of the reciprocal condition number of an SPD matrix. |
|
Factor |
|
Draw |
|
Solve |
|
Log-probability that |
|
|
|
|
|
|
|
Configure sparsax for this process. |
|
Free all cached symbolic analyses and factorizations. |
|
Number of sparsity patterns currently cached. |
|
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 SPD |
|
Solve |
|
Return |
|
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.
Solve |
|
|
|
Log-determinant of a general (non-symmetric) sparse matrix via KLU. |
|
Sign and log-absolute-determinant of a sparse matrix via KLU. |
|
A cheap estimate of the reciprocal condition number of |
|
|
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.
Factor general (non-symmetric) |
|
Solve |
|
Return |
|
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.
Solve |
|
|
|
Log-determinant of a general (non-symmetric) sparse matrix via UMFPACK. |
|
Sign and log-absolute-determinant of a sparse matrix via UMFPACK. |
|
A cheap estimate of the reciprocal condition number of |
|
Choose the faster LU backend for a sparsity pattern. |
|
One LU backend's functions, all with the |
|
|
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.
Factor general (non-symmetric) |
|
Solve |
|
Return |
|
Set how many UMFPACK numeric factors are retained per sparsity pattern. |
|
Keep at most |
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).
int([x]) -> integer int(x, base=10) -> integer |
|
int([x]) -> integer int(x, base=10) -> integer |
|
int([x]) -> integer int(x, base=10) -> integer |
|
int([x]) -> integer int(x, base=10) -> integer |
|
int([x]) -> integer int(x, base=10) -> integer |
|
int([x]) -> integer int(x, base=10) -> integer |
|
int([x]) -> integer int(x, base=10) -> integer |
|
int([x]) -> integer int(x, base=10) -> integer |
|
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 |
|
|
|
Selected inverse |
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
Axandbonly formode == MODE_A; other modes are not differentiable (their VJP is undefined, matching the JAXsolve).