decomposition — Create matrix decomposition objects for reusable linear solves, with explicitly gated RunMat extensions.
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 MATLAB-compatible surface accepts full real or complex coefficient matrices of class
singleordouble. With RunMat extensions enabled, all eight integer coefficient classes and logical coefficients are accepted and retained exactly in the object; strict compatibility mode rejects those forms before gathering a resident value. Sparse inputs remain 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. MATLAB-compatibleCheckConditionvalues are logical; accepting an integer scalar is a separately gated RunMat extension.CheckConditionis exposed as an object property, whileRankToleranceis accepted and stored for QR compatibility metadata. - Typed-integer
RankToleranceand real or paired-complex typed-integer scale factors are independently gated RunMat extensions. Each authoritative integer component must be exactly representable before crossing into binary64 scale or tolerance 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. GPU scalar operands are gated before provider access because the public decomposition surface does not document GPU Arrays.
- Conjugate transpose (
dA') togglesIsConjugateTransposed, conjugates the scale factor, and solves against the conjugate-transposed coefficient matrix. Gated integer and logical objects retain exact coefficient storage through this structural operation. - Left division (
dA \ b) and right division (b / dA) support the same real, complex, square, rectangular, and least-squares behavior as RunMat'smldivideandmrdividebuiltins. Integer and logical coefficients are promoted explicitly to binary64 only at this solve boundary, so their solutions are double or complex double. - Element-wise left division (
ldivideor.\) is not a decomposition-object method, anddecomposition.ldivideis absent from the builtin registry.
Does RunMat run decomposition on the GPU?
The compatibility target does not document GPU Array support for decomposition. RunMat retains gpuArray arguments behind its explicit extension mode and gathers them 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.
How are integer and logical coefficient matrices handled?⌄
They are RunMat-only extensions. With extensions enabled, construction and structural transpose preserve exact host storage for all eight integer classes and logical arrays. A solve promotes the effective coefficient matrix to double at the solve boundary and reports a double or complex-double solution. With extensions disabled, construction and later object methods reject the extended object with a stable compatibility identifier.
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.
Which broader decomposition features are still incomplete?⌄
The current object does not implement sparse decomposition, cached native factor storage, condition warnings, algorithmic use of RankTolerance, or the additional banded, Hessenberg, LDL, COD, and permuted-triangular forms. Unsupported type strings are rejected explicitly.
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.