lu — Compute LU decompositions with partial pivoting in MATLAB and RunMat.
lu(A) computes the dense LU factorization of a real or complex matrix using partial pivoting. One-, two-, and three-output forms are implemented, including row-permutation matrix and vector options. Sparse four- and five-output forms are not implemented.
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)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | NumericArray | Yes | — | Input matrix to factorize. |
pivotMode | StringScalar | Yes | "matrix" | Permutation mode (`"matrix"` or `"vector"`). |
Returns
| Name | Type | Description |
|---|---|---|
LU | NumericArray | Combined LU factors. |
L | NumericArray | Lower-triangular factor. |
U | NumericArray | Upper-triangular factor. |
P | NumericArray | Permutation matrix or vector based on pivot mode. |
Returned values from lu depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:lu:InvalidArgument | Option arguments or requested output count are invalid. | lu currently supports at most three outputs |
RunMat:lu:InvalidInput | Input is unsupported for LU factorization. | lu: expected numeric or logical input values |
RunMat:lu:Internal | Runtime cannot materialize LU outputs. | lu: internal runtime failure |
How lu works
- Partial pivoting is applied to improve numerical stability. The permutation is encoded either as a dense matrix (
'matrix', default) or as a pivot vector ('vector'). - Rectangular inputs are supported.
Lis alwaysm × m(unit lower-triangular), andUism × n, wheremandnare the row and column counts ofA. - Singular matrices are permitted. Zero pivots propagate into the
Ufactor 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.
- Only dense one-, two-, and three-output forms are implemented. Sparse input and the sparse four- and five-output threshold, column-permutation (
Q), and scaling (R/D) forms are not available.
Does RunMat run lu on the GPU?
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.
GPU memory and residency
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.
Examples
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
-1 1 0
0 -1 1
U =
4 -6 0
0 1 1
0 0 3
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 -0.5 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 2; 6 3 4];
b = [1; 2];
[L, U, P] = lu(A);
y = L \ (P * b);
x = U \ yExpected output:
x =
0.0
0.5
-0.0Running 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
Why does RunMat currently stop at three outputs?⌄
Sparse input and the sparse four- and five-output threshold, column-permutation (Q), and scaling (R/D) contracts are not implemented. Dense one-, two-, and three-output forms are available.
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?⌄
Yes. Partial pivoting always chooses the first maximal entry in each column, mirroring MATLAB’s behaviour for dense matrices.
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?⌄
RunMat currently supports at most one option string ('matrix' or 'vector'). Passing additional options raises an error.
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
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. 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 an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 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.