ichol — Compute sparse incomplete Cholesky factors without densifying.
ichol constructs a managed sparse incomplete Cholesky factor for preconditioning and sparse iterative solves.
Syntax
L = ichol(A)
L = ichol(A, options)Inputs
A- Type
NumericArray- Required
- Yes
- Default
- —
- Description
- Square sparse single- or double-precision matrix.
options- Type
Any- Required
- Yes
- Default
struct('type','nofill','droptol',0,'michol','off','diagcomp',0,'shape','lower')- Description
- Incomplete-factorization options.
Returns
L- Type
NumericArray- Description
- Sparse incomplete lower or upper Cholesky factor.
Errors
RunMat:ichol:InvalidArgument- When
- Options are malformed, unsupported, or more than one output is requested.
- Message
ichol: invalid options or output count
RunMat:ichol:InvalidInput- When
- Input is not a finite square sparse single- or double-precision matrix.
- Message
ichol: expected a finite square sparse single- or double-precision matrix
RunMat:ichol:NotPositiveDefinite- When
- The incomplete factorization encounters a nonpositive pivot.
- Message
ichol: matrix is not positive definite; use diagcomp to compensate the diagonal
RunMat:ichol:Runtime- When
- Managed execution or exact sparse output publication fails.
- Message
ichol: managed sparse execution failed
Syntax
L = ichol(A)
L = ichol(A, options)
A must be a square sparse single- or double-precision real or complex matrix. The default computes a zero-fill incomplete lower Cholesky factor.
options is a scalar struct. Supported fields are type ('nofill' or 'ict'), droptol (nonnegative scalar), michol ('off' or 'on'), diagcomp (nonnegative scalar), and shape ('lower' or 'upper').
Behavior
With type = 'nofill', the factor uses the selected triangular sparsity pattern of A. With type = 'ict', fill entries in column j whose magnitude exceeds droptol * norm(A(j:end,j),1) over the selected triangle are retained.
michol = 'on' compensates the diagonal for discarded contributions. diagcomp adds a nonnegative multiple of the source diagonal before factorization and can stabilize a matrix that otherwise encounters a nonpositive pivot.
The default shape = 'lower' returns sparse L; shape = 'upper' returns its conjugate transpose.
Input precision and real/complex class are preserved. A nonpositive pivot raises RunMat:ichol:NotPositiveDefinite.
Execution and ownership
ichol borrows the input CSC arrays, admits all retained factor and workspace growth through the managed host allocation ledger, cooperatively checkpoints long work, and publishes a validated exact sparse output. It does not densify the matrix.
Sparse factorization is a managed CPU operation. Resident or dense inputs are rejected rather than silently transferred or converted.
Examples
Zero-fill incomplete Cholesky factor
A = sparse([4 -1 0; -1 4 -1; 0 -1 4]);
L = ichol(A);
assert(issparse(L));Threshold incomplete factorization
A = sparse([6 -1 0; -1 6 -1; 0 -1 6]);
opts = struct('type','ict','droptol',1e-3,'michol','on');
L = ichol(A, opts);Upper incomplete factor
A = sparse([5 1; 1 3]);
R = ichol(A, struct('shape','upper'));Using ichol with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how ichol changes the result.
Run a small ichol example, explain the result, then change one input and compare the output.
FAQ
When should I use nofill or ict?⌄
Use nofill for predictable storage bounded by the source pattern. Use ict when additional retained fill can improve the preconditioner; tune droptol to trade memory for quality.
What does diagcomp do?⌄
It shifts each source diagonal before factorization. A small positive value can avoid breakdown for matrices whose zero-fill factor is not positive definite.
Related Linalg functions
Factor
chol · decomposition · decomposition.ctranspose · decomposition.mldivide · decomposition.mrdivide · decomposition.mtimes · decomposition.rdivide · decomposition.subsref · decomposition.times · decomposition.uminus · decomposition.uplus · eig · eigs · gmres · ilu · lu · ordeig · ordqz · ordschur · pcg · qr · qz · rsf2csf · schur · svd
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Source you can read
Every RunMat function's source is public. Read exactly how ichol is executed, line by line, in Rust.
- View the source for ichol in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.