lu — Compute LU decompositions with partial pivoting in MATLAB and RunMat.
lu(A) computes real or complex LU factors. Dense calls support one through three outputs. Native sparse single/double calls additionally support rectangular/singular factors, threshold pivoting, column permutations and explicit row scaling through five outputs.
Syntax
LU = lu(A)
LU = lu(A, pivotMode)
[L, U] = lu(A)
[L, U] = lu(A, pivotMode)
[L, U, P] = lu(A)
[L, U, P] = lu(A, pivotMode)All supported lu forms
LU = lu(A)
LU = lu(A, pivotMode)
[L, U] = lu(A)
[L, U] = lu(A, pivotMode)
[L, U, P] = lu(A)
[L, U, P] = lu(A, pivotMode)
[L,U,P,Q] = lu(S)
[L,U,P,Q] = lu(S,outputForm)
[L,U,P,Q,D] = lu(S)
[L,U,P,Q,D] = lu(S,outputForm)
LU = lu(S,thresh)
LU = lu(S,thresh,outputForm)
[L,U] = lu(S,thresh)
[L,U] = lu(S,thresh,outputForm)
[L,U,P] = lu(S,thresh)
[L,U,P] = lu(S,thresh,outputForm)
[L,U,P,Q] = lu(S,thresh)
[L,U,P,Q] = lu(S,thresh,outputForm)
[L,U,P,Q,D] = lu(S,thresh)
[L,U,P,Q,D] = lu(S,thresh,outputForm)Inputs
A- Type
NumericArray- Required
- Yes
- Description
- Input matrix to factorize.
pivotMode- Type
StringScalar- Required
- Yes
- Default
"matrix"- Description
- Permutation mode (`"matrix"` or `"vector"`).
S- Type
NumericArray- Required
- Yes
- Description
- Sparse single or double matrix, real or complex, square or rectangular.
outputForm- Type
StringScalar- Required
- Yes
- Description
- matrix or vector permutation output format.
thresh- Type
NumericArray- Required
- Yes
- Description
- Floating pivot threshold in [0,1]; a scalar with up to three outputs or one/two-element vector with four or five outputs.
Returns
LU- Type
NumericArray- Description
- Combined LU factors.
L- Type
NumericArray- Description
- Lower-triangular factor.
U- Type
NumericArray- Description
- Upper-triangular factor.
P- Type
NumericArray- Description
- Permutation matrix or vector based on pivot mode.
L- Type
NumericArray- Description
- Sparse m-by-min(m,n) lower factor; with two outputs it includes the inverse row permutation.
U- Type
NumericArray- Description
- Sparse min(m,n)-by-n upper factor, including legitimate zero pivots.
P- Type
NumericArray- Description
- Sparse double row permutation matrix or one-based dense double column vector.
Q- Type
NumericArray- Description
- Sparse double column permutation matrix or one-based dense double column vector.
D- Type
NumericArray- Description
- Real sparse diagonal row scaling in the coefficient floating class.
Returned values from lu depend on how many outputs the caller requests.
Errors
RunMat:lu:InvalidArgument- When
- Option arguments or requested output count are invalid.
- Message
lu: invalid options or requested output count (dense supports at most three; sparse at most five)
RunMat:lu:InvalidInput- When
- Input is unsupported for LU factorization.
- Message
lu: expected numeric or logical input values
RunMat:lu:Internal- When
- Runtime cannot materialize LU outputs.
- Message
lu: internal runtime failure
Behavior
Pivoting improves numerical stability. The permutation is encoded either as a matrix ('matrix', default) or as a one-based column pivot vector ('vector'). Sparse inputs return sparse permutation matrices; dense inputs use their existing dense/provider forms.
Rectangular inputs are supported. The dense implementation returns m-by-m L and m-by-n U. Sparse factors use L of size m-by-min(m,n) and U of size min(m,n)-by-n.
Singular matrices are permitted. Zero pivots propagate into the U factor just as in MATLAB; MATLAB-compatible warnings are not yet emitted.
Single inputs preserve single precision; double inputs preserve double precision for real and complex factors.
When RunMat extensions are enabled, integer and logical inputs are accepted and promoted before factorization.
Sparse real/complex single and double coefficients support one through five outputs without a dense coefficient copy. Zero pivots remain valid factor data; they do not trigger an artificial singular-system refusal.
Sparse forms and ownership
Two outputs include the inverse row permutation in L, so S = L*U. With three outputs P*S = L*U. Four outputs add structural column ordering, P*S*Q = L*U; vector forms satisfy S(p,q) = L*U. Five outputs add real diagonal D with P*(D\S)*Q = L*U. L, U and packed LU retain the coefficient native class/domain; indexing outputs are double, and D is real in the coefficient floating class.
A scalar threshold lies in [0,1]. Up to three outputs default to 1; four/five outputs default to [0.1,0.001] and accept one or two thresholds. Public sparse pivoting uses original-pattern row degrees as its structural heuristic. With a symmetric pattern and nonzero diagonal, the second threshold controls diagonal preference; otherwise only the first is used. Exact permutations are implementation-dependent, not promised to match MATLAB's multifrontal ordering.
Five-output row scaling uses each row's largest absolute real/imaginary component, with one for an empty row. It avoids overflowing an otherwise finite complex modulus or row sum. The returned D describes this actual scaling; it is not an unreported change to the input.
Numerical fill, CSC canonicalization, control backing and outputs are physically admitted from the original execution owner. Empty elimination carries identity permutations without traversing a virtual row axis. Sparse output owners validate topology incrementally; errors/control retain their original cause and cannot replay a selected factor attempt.
Acceleration and residency
When an acceleration provider implements the lu hook, the factorization executes through that provider and the combined LU factor, L, U, and permutation outputs remain on the exact input owner. Every returned handle is validated for shape, precision, real storage metadata, ownership, and non-aliasing before use.
The 'vector' option likewise returns a GPU-resident pivot vector when a provider hook is active.
If no provider hook is available, RunMat gathers for CPU fallback. Automatic residency may return host factors; explicit residency restores every requested factor to the original owner or fails atomically.
When the active provider implements lu, all requested factors remain on the input's exact GPU owner. If provider execution is unavailable, automatically resident inputs may return host factors; explicitly resident inputs require every requested factor to be restored to the same owner or the operation returns an error.
Uses the provider lu hook when available. All requested provider outputs are validated for exact owner, expected shape and precision, storage metadata, and non-aliasing before use.
Examples
Checking sparse row scaling and both permutations
S = sparse([1 2; 3 4; 5 7]);
[L,U,P,Q,D] = lu(S);Using sparse row and column permutation vectors
S = sparse([1 2 0; 3 4 5]);
[L,U,p,q] = lu(S,1,'vector');Factoring a singular rectangular matrix without discarding it
S = sparse([0 1; 0 2; 0 3]);
[L,U] = lu(S);Factorizing a square matrix with lu
A = [2 1 1; 4 -6 0; -2 7 2];
[L, U, P] = lu(A)Expected output:
L =
1 0 0
0.5 1 0
-0.5 1 1
U =
4 -6 0
0 4 1
0 0 1
P =
0 1 0
1 0 0
0 0 1Obtaining only the combined LU factor
LU = lu([1 3 5; 2 4 7; 1 1 0])Expected output:
LU =
2 4 7
0.5 1 1.5
0.5 -1 -2Requesting the permutation vector with the 'vector' option
[L, U, p] = lu([4 3; 6 3], 'vector')Expected output:
p =
2
1LU factorization of a rectangular matrix
A = [3 1 2; 6 3 4];
[L, U, P] = lu(A)Expected output:
L =
1 0
0.5 1
U =
6 3 4
0 -0.5 0
P =
0 1
1 0Using LU factors to solve a linear system
A = [3 1; 6 3];
b = [1; 2];
[L, U, P] = lu(A);
y = L \ (P * b);
x = U \ yExpected output:
x = [1/3; 0]Running lu on a gpuArray
G = gpuArray([10 7; 3 2]);
[L, U, P] = lu(G);
class(L)
class(U)
class(P)Expected output:
ans =
'gpuArray'
ans =
'gpuArray'
ans =
'gpuArray'Using lu with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how lu changes the result.
Run a small lu example, explain the result, then change one input and compare the output.
FAQ
When can I request four or five outputs?⌄
For sparse single or double coefficients. Four outputs return row/column permutations; five additionally return the actual row scaling D. Dense/provider calls retain their one-, two-, and three-output contract.
Does the permutation vector use MATLAB’s 1-based indexing?⌄
Yes. When you request 'vector', the returned pivot vector contains 1-based row indices so that A(p, :) = L * U.
How are singular matrices handled?⌄
Partial pivoting proceeds exactly as in MATLAB. If a pivot column is entirely zero, the corresponding diagonal entries in U become zero. No warning is emitted yet.
Are complex matrices supported?⌄
Yes on the host. Complex inputs produce complex L, U, and LU, while the permutation remains real. Interactive complex gpuArray execution remains an implementation gap because the current LU provider contract and fallback gather path are real-only.
Will the factors stay on the GPU when I pass a gpuArray?⌄
When the active provider exposes the lu hook, every requested factor remains on the exact input owner. On fallback, automatic residency may return host factors, while explicit residency restores all outputs to the original owner or reports an error.
Can I call lu on logical arrays?⌄
Yes, when RunMat extensions are enabled. Logical inputs are promoted before factorization; this is not presented as part of the documented MATLAB input contract.
Is pivoting deterministic?⌄
The implementation is deterministic, but sparse structural ordering and threshold pivoting can choose different permutations from dense partial pivoting or another MATLAB implementation.
How accurate is the factorization?⌄
Single inputs use single-precision real or complex factors, and double inputs use double precision. Enabled integer and logical RunMat extensions are promoted before factorization.
What happens if I pass more than one option argument?⌄
Dense calls accept one permutation-format string. Sparse calls additionally accept a floating pivot threshold before that format; the threshold may have two elements only with four or five outputs.
Can I reuse the combined LU factor to solve systems?⌄
Yes. The combined matrix returned by lu(A) stores L in the strictly lower-triangular part (with an implicit unit diagonal) and U in the upper-triangular part, just like MATLAB. You can use forward/back substitution routines that understand this layout.
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 · ilu · 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 lu is executed, line by line, in Rust.
- View the source for lu 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.