linsolve — Solve linear systems with structural hints in MATLAB and RunMat.
X = linsolve(A, B) solves A * X = B. The implemented opts surface supports triangular, rectangular, symmetric, positive-definite, and transpose controls, with the extension boundaries described below.
Syntax
X = linsolve(A, B)
X = linsolve(A, B, opts)
[X, R] = linsolve(A, B)
[X, R] = linsolve(A, B, opts)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Coefficient matrix. |
B | Any | Yes | — | Right-hand side matrix or vector. |
opts | Any | No | — | Structural options (LT, UT, RECT, SYM, POSDEF, TRANSA, RCOND). |
Returns
| Name | Type | Description |
|---|---|---|
X | NumericArray | Solution to A * X = B. |
R | NumericScalar | Reciprocal condition estimate. |
Returned values from linsolve depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:linsolve:InvalidArgument | Options/output count/auxiliary arguments are malformed or unsupported. | linsolve: invalid argument |
RunMat:linsolve:InvalidInput | Input shape/type cannot be solved under linsolve semantics. | linsolve: invalid input |
RunMat:linsolve:Internal | Runtime fails while solving or executing provider fallback paths. | linsolve: internal runtime failure |
How linsolve works
- Inputs must behave like 2-D matrices (trailing singleton dimensions are accepted).
size(A, 1)must matchsize(B, 1)after accounting foropts.TRANSA. - When
opts.LToropts.UTare supplied,linsolveperforms forward/back substitution instead of a full factorization. Singular pivots trigger the MATLAB error"linsolve: matrix is singular to working precision." - A logical
opts.TRANSAis supported in compatibility mode (falsemeans no transpose andtruemeans conjugate transpose). Text values'N','T', and'C'are a RunMat-only extension. opts.POSDEF,opts.SYM, andopts.RECTare parsed and forwarded to acceleration providers. On the host, general non-triangular cases currently use the shared SVD-based dense solver rather than specialised structural algorithms.- For a square system, the optional second output is a reciprocal condition estimate. For a rectangular system, the second output is the estimated rank.
- Logical and integer coefficient inputs are RunMat-only extensions and are promoted to double; integer values must be exactly representable in binary64. Complex floating inputs use complex arithmetic, while typed complex-integer inputs are rejected.
- Typed-integer values for
LT,UT,RECT,SYM, andPOSDEF, theRCONDoption, and two-output calls with explicitgpuArrayoperands are RunMat-only extensions.
Does RunMat run linsolve on the GPU?
For eligible real matrix operands, RunMat offers the solve to the exact owner's linsolve hook and validates that the returned solution is non-aliased, real, floating, correctly shaped, on the expected device, and owned by that provider. WGPU supports selected real F32 triangular, transpose, positive-definite, square, and rectangular routes. Provider-declined, complex, scalar, or otherwise unsupported cases gather to the shared host solver and return a host result. Explicit-GPU two-output calls are available only in RunMat extension mode.
GPU memory and residency
No additional residency management is required for supported real matrix operands. RunMat selects the exact provider that owns the first resident operand and requires every other resident operand to have that same owner. It validates provider results and preserves explicit or automatic provenance. If the provider declines the solve, or if the operands are complex or scalar, RunMat gathers through the normal host path; that fallback returns a host value rather than automatically re-uploading it.
Examples
Solving a 2×2 linear system
A = [4 -2; 1 3];
b = [6; 7];
x = linsolve(A, b)Expected output:
x =
2
1Using a lower-triangular hint
L = [3 0 0; -1 2 0; 4 1 5];
b = [9; 1; 12];
opts.LT = true;
x = linsolve(L, b, opts)Expected output:
x =
3
2
1Solving the transposed system
A = [2 1 0; 0 3 4; 0 0 5];
b = [3; 11; 5];
opts.UT = true;
opts.TRANSA = 'T';
x = linsolve(A, b, opts)Expected output:
x =
1
2
1Complex triangular solve
U = [2+1i -1i; 0 4-2i];
b = [3+2i; 7];
opts.UT = true;
x = linsolve(U, b, opts)Expected output:
x =
2.0000 + 0.0000i
1.7500 + 0.8750iEstimating the reciprocal condition number for a square system
A = [1 1; 1 1+1e-12];
b = [2; 2+1e-12];
[x, rcond_est] = linsolve(A, b)Expected output:
x =
1
1
rcond_est =
4.4409e-12Using linsolve with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how linsolve changes the result.
Run a small linsolve example, explain the result, then change one input and compare the output.
FAQ
What happens if I pass both opts.LT and opts.UT?⌄
RunMat raises the MATLAB error "linsolve: LT and UT are mutually exclusive."—a matrix cannot be simultaneously strictly lower- and upper-triangular.
Does opts.TRANSA accept lowercase characters?⌄
In RunMat extension mode, text values are case-insensitive and accept 'N', 'T', or 'C'. In compatibility mode, use a logical scalar: false selects no transpose and true selects conjugate transpose.
How is opts.RCOND used?⌄
In RunMat extension mode, opts.RCOND provides a non-negative lower bound on the acceptable reciprocal condition estimate. If the estimate falls below it, the builtin raises "linsolve: matrix is singular to working precision." Compatibility mode rejects this option.
Do opts.SYM or opts.POSDEF change the algorithm today?⌄
They are parsed and forwarded to providers. The host path currently uses the general dense SVD solver for non-triangular systems, so these hints do not select specialised host algorithms. WGPU implements a selected real F32 positive-definite path; support for other cases remains provider-specific.
Can I use higher-dimensional arrays?⌄
Inputs must behave like matrices. Trailing singleton dimensions are permitted, but other higher-rank arrays should be reshaped before calling linsolve, just like in MATLAB.
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 linsolve is executed, line by line, in Rust.
- View the source for linsolve 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.