lu — Compute LU decompositions with partial pivoting in MATLAB and RunMat.
lu(A) computes the LU factorization of real or complex matrix A using partial pivoting. One-, two-, and three-output forms (including permutation-vector options) follow MATLAB semantics.
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. - Only the first three outputs are implemented today. Column permutations (
Q) and scaling (R) for the five-output sparse form are not yet available.
Does RunMat run lu on the GPU?
When an acceleration provider implements the lu hook (the WGPU provider does), the factorization executes through that provider and the combined LU factor, L, U, and permutation outputs all remain on the device. The current WGPU backend performs the decomposition on the host once and immediately reuploads the factors so residency is preserved until dedicated kernels land.
The 'vector' option likewise returns a GPU-resident pivot vector when a provider hook is active.
If no provider hook is available, RunMat automatically gathers the input to host memory and falls back to the CPU implementation so behaviour stays MATLAB-compatible.
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?⌄
Column pivoting (Q) and scaling (R) from MATLAB’s five-output sparse form are planned but not yet implemented. The dense three-output contract mirrors MATLAB’s default dense behaviour.
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. Complex inputs produce complex L, U, and LU. The permutation remains real because it only contains zeros and ones.
Will the factors stay on the GPU when I pass a gpuArray?⌄
Yes. When the active acceleration provider exposes the lu hook (WGPU today), the combined factor, L, U, and the permutation outputs remain gpuArray values—the provider currently performs the decomposition on the host once and reuploads the results to preserve residency. Without provider support, RunMat gathers to host memory before returning the factors.
Can I call lu on logical arrays?⌄
Yes. Logical inputs are promoted to double precision before factorization, matching MATLAB semantics.
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?⌄
The implementation uses standard double-precision arithmetic (or complex double when needed). Numerical properties therefore match MATLAB’s dense fallback (without iterative refinement).
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
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.