ilu — Compute sparse incomplete LU factors without densifying.
ilu builds managed zero-fill, Crout, or threshold-pivoted sparse factors for iterative preconditioning.
Syntax
W = ilu(A)
[L,U] = ilu(A)
[L,U,P] = ilu(A)
W = ilu(A, options)
[L,U] = ilu(A, options)
[L,U,P] = ilu(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,'milu','off','udiag',0,'thresh',1)- Description
- Incomplete-LU options.
Returns
W- Type
NumericArray- Description
- Combined sparse factors L + U - I.
L- Type
NumericArray- Description
- Sparse unit lower factor.
U- Type
NumericArray- Description
- Sparse upper factor.
P- Type
NumericArray- Description
- Sparse permutation matrix.
Returned values from ilu depend on how many outputs the caller requests.
Errors
RunMat:ilu:InvalidArgument- When
- Options or output count are invalid.
- Message
ilu: invalid options or output count
RunMat:ilu:InvalidInput- When
- Input is not a finite square sparse floating matrix.
- Message
ilu: expected a finite square sparse single- or double-precision matrix
RunMat:ilu:NumericalFailure- When
- An unreplaced zero pivot or numerical breakdown occurs.
- Message
ilu: incomplete factorization encountered a numerical failure
RunMat:ilu:Runtime- When
- Managed execution or output publication fails.
- Message
ilu: managed sparse execution failed
Syntax
W = ilu(A)
[L,U] = ilu(A)
[L,U,P] = ilu(A)
[___] = ilu(A, options)
A is a square sparse single- or double-precision real or complex matrix. W equals L + U - speye(size(A)).
Options fields are type ('nofill', 'crout', or 'ilutp'), nonnegative droptol, milu ('off', 'row', or 'col'), udiag (0 or 1), and thresh in [0,1].
Modes and defaults
type = 'nofill' is the default, retains only the input sparsity pattern, and ignores droptol and thresh. type = 'crout' admits threshold fill without pivoting. type = 'ilutp' applies threshold dropping and pivoting.
droptol defaults to 0. For threshold modes, U uses droptol * norm(A(:,j),2) and L candidates are tested before pivot scaling. thresh is in [0,1], defaults to 1, and is used by ILUTP.
milu defaults to 'off'; 'row' or 'col' compensates discarded contributions. udiag defaults to 0; in ILUTP, 1 replaces a zero pivot by its local drop tolerance.
Permutation, classes, and errors
For nofill and crout, P is identity. With pivoted row-sum modification, A*P is approximated by L*U; with column-sum modification, P*A is approximated by L*U. When P is not requested its permutation is folded into U or L respectively.
Input single/double precision and real/complex class are preserved. P is a sparse double permutation matrix. Dense, logical, integer, nonsquare, malformed, and nonfinite inputs are rejected.
An unreplaced zero pivot raises RunMat:ilu:NumericalFailure; invalid options, invalid inputs, and managed runtime failures retain separate public identifiers.
Execution and ownership
The implementation borrows validated CSC input, uses one claimed row workspace, claims every retained sparse growth before allocation, checkpoints cooperative work, and publishes validated exact sparse outputs. It never forms a dense matrix.
Factor failures and cancellation are terminal after managed execution starts; no hidden dense or provider fallback is attempted.
Examples
Zero-fill sparse factors
A = sparse([4 1 0; 2 5 1; 0 1 3]);
[L,U] = ilu(A);Threshold pivoted preconditioner
A = sparse([1e-4 1; 1 2]);
o = struct('type','ilutp','droptol',1e-6,'thresh',1);
[L,U,P] = ilu(A,o);Combined sparse preconditioner
A = sparse([5 -1 0; -1 5 -1; 0 -1 5]);
W = ilu(A);Crout threshold fill
A = sparse([6 1 0; 1 7 1; 0 1 8]);
o = struct('type','crout','droptol',1e-3,'milu','row');
[L,U] = ilu(A,o);Using ilu with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how ilu changes the result.
Run a small ilu example, explain the result, then change one input and compare the output.
FAQ
Which mode should I use?⌄
Use nofill for source-pattern storage, crout for threshold fill without pivoting, and ilutp when pivoting is required.
What does droptol control?⌄
Larger values discard more candidates and usually reduce storage at the cost of preconditioner quality. Nofill ignores droptol.
When should I request P?⌄
Request P for the explicit ILUTP permutation identity. With two outputs it is folded into the appropriate factor.
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 · ichol · 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 ilu is executed, line by line, in Rust.
- View the source for ilu 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.