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
A- Type
Any- Required
- Yes
- Description
- Coefficient matrix.
B- Type
Any- Required
- Yes
- Description
- Right-hand side matrix or vector.
opts- Type
Any- Required
- No
- Description
- Structural options (LT, UT, RECT, SYM, POSDEF, TRANSA, RCOND).
Returns
X- Type
NumericArray- Description
- Solution to A * X = B.
R- Type
NumericScalar- Description
- Reciprocal condition estimate.
Returned values from linsolve depend on how many outputs the caller requests.
Errors
RunMat:linsolve:InvalidArgument- When
- Options/output count/auxiliary arguments are malformed or unsupported.
- Message
linsolve: invalid argument
RunMat:linsolve:InvalidInput- When
- Input shape/type cannot be solved under linsolve semantics.
- Message
linsolve: invalid input
RunMat:linsolve:Internal- When
- Runtime fails while solving or executing provider fallback paths.
- Message
linsolve: internal runtime failure
Behavior
Inputs must behave like 2-D matrices (trailing singleton dimensions are accepted). size(A, 1) must match size(B, 1) after accounting for opts.TRANSA.
When opts.LT or opts.UT are supplied, linsolve performs forward/back substitution instead of a full factorization. Singular pivots trigger the MATLAB error "linsolve: matrix is singular to working precision."
A logical opts.TRANSA is supported in compatibility mode (false means no transpose and true means conjugate transpose). Text values 'N', 'T', and 'C' are a RunMat-only extension.
opts.POSDEF, opts.SYM, and opts.RECT are parsed and forwarded to acceleration providers. On the host, nonsingular square systems use pivoted LU; singular and rectangular systems use the shared SVD minimum-norm solver. These hints do not select specialised structural host algorithms.
For a nonsingular square system, the optional second output estimates reciprocal 1-norm condition using the same LU factors as the solve. 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, and POSDEF, the RCOND option, and two-output calls with explicit gpuArray operands are RunMat-only extensions.
Acceleration and residency
Prefers the exact owner's linsolve hook. WGPU has selected real F32 triangular, transpose, positive-definite, square, and rectangular paths; unsupported cases gather to the shared host solver.
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.
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.
Implementation and validation
Original GPU declarations: precisions f32, f64; elementwise false; reduction false; broadcasting none.
Original fusion declarations: elementwise false; reduction false; max inputs 2; constants uniform.
Examples
Solving a 2×2 linear system
A = [4 -2; 1 3];
b = [6; 7];
x = linsolve(A, b)Expected output:
x = [16/7; 11/7]Using 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; -2/5]Solving 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 = [3/2; 19/6; -23/15]Complex triangular solve
U = [2+1i -1i; 0 4-2i];
b = [3+2i; 7];
opts.UT = true;
x = linsolve(U, b, opts)Expected output:
x = [1.6+0.9i; 1.4+0.7i]Estimating 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 is approximately [1; 1]; rcond_est is small and positiveUsing 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 uses pivoted LU for nonsingular square systems and SVD for singular or rectangular systems; 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
Factor
chol · decomposition · decomposition.ctranspose · decomposition.mldivide · decomposition.mrdivide · decomposition.mtimes · decomposition.rdivide · decomposition.subsref · decomposition.times · decomposition.uminus · decomposition.uplus · eig · eigs · gmres · ichol · ilu · lu · ordeig · ordqz · ordschur · pcg · qr · qz · rsf2csf · schur · svd
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.