sparsax.factor

sparsax.factor(Ai, Aj, Ax, n)[source]

Factor SPD A once, returning a reusable factor token.

The token is an opaque int64[2] array carrying a reference to a CHOLMOD numeric factor held in the extension’s cache. Pass it to solve_factor() and logdet_factor() to issue an unbounded sequence of solves and a logdet against the same factor — no refactoring and no per-call re-hash of Ax.

This is the “hold the factor open” primitive that factor_solve() 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, which a single fused call cannot represent. With a token, the basis build is a lax.fori_loop of solve_factor() calls against one factor.

The token is not differentiable. Use solve() / logdet() when gradients are needed.

Parameters:
Ai

[n_nz] int32 — COO pattern (upper triangle, Ai <= Aj).

Aj

[n_nz] int32 — COO pattern (upper triangle, Ai <= Aj).

Ax

[n_nz] float64 — COO values.

n

matrix dimension (static Python int).

Returns:

Factor — an opaque int64[2] token. Not meant to be inspected; pass to solve_factor() / logdet_factor().

Note

Repeated factor calls with identical Ax reuse a cached numeric factor (no refactoring). The cache is per sparsity pattern; call clear_cache() to drop all factors and invalidate outstanding tokens.