decomposition — Create MATLAB-compatible matrix decomposition objects for reusable linear solves.
dA = decomposition(A) creates a decomposition object that can be reused with dA \ b and b / dA. RunMat stores a validated coefficient matrix and routes solves through the same MATLAB-compatible mldivide and mrdivide engines used by ordinary matrix division.
Syntax
dA = decomposition(A)
dA = decomposition(A, type)
dA = decomposition(A, type, triangularFlag)
dA = decomposition(___, Name, Value)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
args | Any | Variadic | — | Coefficient matrix, optional type, triangular flag, and name-value options. |
Returns
| Name | Type | Description |
|---|---|---|
dA | Any | Matrix decomposition object. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:decomposition:InvalidInput | The matrix, type, option, or object operation is invalid. | decomposition: invalid input |
RunMat:decomposition:Internal | Runtime cannot materialize a decomposition object or transformed coefficient matrix. | decomposition: internal runtime failure |
How decomposition works
- The constructor accepts dense real, dense complex, scalar numeric, logical scalar, and integer scalar coefficient matrices. Sparse inputs are rejected until RunMat has a sparse solve path behind the decomposition object.
- Supported type strings are
'auto','lu','qr','chol','triangular', and'diagonal'. The default'auto'selectsdiagonal,triangular,lu, orqrbased on the matrix shape and structure. - Square-only types reject rectangular matrices. The
diagonalandtriangulartypes validate the corresponding structure. The optional'upper'or'lower'triangular flag is supported fordecomposition(A, 'triangular', flag)and ignores the opposite triangle. - Name-value options include
CheckConditionandRankTolerance.CheckConditionis exposed as an object property;RankToleranceis accepted and stored for QR compatibility metadata. - Object properties include
MatrixSize,Type,CheckCondition,Datatype,IsConjugateTransposed,IsReal,IsSparse, andScaleFactor. Internal coefficient storage is not publicly readable. - Unary plus returns the same decomposition. Unary minus, scalar multiplication, and scalar division return a new decomposition with an adjusted scale factor.
- Conjugate transpose (
dA') togglesIsConjugateTransposed, conjugates the scale factor, and solves against the conjugate-transposed coefficient matrix. - Left division (
dA \ b) and right division (b / dA) support the same real, complex, square, rectangular, and least-squares behavior as RunMat'smldivideandmrdividebuiltins.
Does RunMat run decomposition on the GPU?
Constructing a decomposition object gathers any gpuArray coefficient matrix to host storage because the object owns normalized matrix metadata.
Solves through dA \ b and b / dA call the existing mldivide and mrdivide implementations with the effective coefficient matrix. If a provider accepts that solve, residency follows the same provider behavior as direct matrix division; otherwise RunMat uses the host fallback.
Examples
Solving a square system with a reusable decomposition
A = [2 0; 0 4];
dA = decomposition(A);
x = dA \ [8; 12]Expected output:
x =
4
3Right division through a decomposition object
A = [2 0; 0 4];
dA = decomposition(A);
y = [8 12] / dAExpected output:
y =
4 3Declaring a triangular matrix and using only the upper triangle
A = [2 0; 99 4];
dA = decomposition(A, 'triangular', 'upper');
x = dA \ [8; 12]Expected output:
x =
4
3Scaling and transposing a decomposition
A = [1 2; 0 1];
dA = decomposition(A);
z = (2*dA)' \ [3; 1]Expected output:
z =
1.5
-2.5Using decomposition with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how decomposition changes the result.
Run a small decomposition example, explain the result, then change one input and compare the output.
FAQ
Does decomposition expose the raw LU or QR factors?⌄
No. MATLAB's decomposition object is an opaque solve object, and RunMat follows that surface. Use lu, qr, chol, or svd when you need explicit factors.
Does RunMat cache native factor arrays internally?⌄
The current implementation stores the normalized coefficient matrix plus decomposition metadata and delegates each solve to the shared matrix-division solvers. This preserves MATLAB solve semantics across square, rectangular, and complex cases; dedicated cached factor storage can be added behind the same object surface later.
Which object operations are supported?⌄
RunMat supports property access, unary plus/minus, conjugate transpose, scalar multiplication, scalar division, left division, and right division for decomposition objects.
Are condition warnings emitted?⌄
No. The CheckCondition property is parsed and preserved, but RunMat does not yet emit MATLAB-compatible condition warnings during decomposition construction or solve.
Are sparse decomposition objects supported?⌄
Not yet. RunMat rejects sparse coefficient matrices instead of silently densifying them, because large sparse matrices need a dedicated sparse solve path to be safe and MATLAB-compatible.
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 decomposition is executed, line by line, in Rust.
- View the source for decomposition 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.