RunMat
  • Pricing
RunMat
GitHub
GitHub
Sign inTry in browser
DesktopRuntimePhysicsCADAdministrationAgent

Get RunMat updates

New releases, guides and examples.

Product+
  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download
Math+
  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting
Physics+
  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA
Industries+
  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance
Learn+
  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students
Compare+
  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons
Company+
  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms

Product

  • Runtime
  • GPU
  • Parallel
  • Compile
  • Interop and MEX
  • Simulation
  • MCAD
  • ECAD
  • Enterprise
  • AI integrations
  • Pricing
  • Download

Math

  • Signal processing
  • Linear algebra
  • Statistics
  • Curve fitting
  • Differential equations
  • Control systems
  • Optimization
  • Finance
  • Data and tables
  • Plotting

Physics

  • Simulation overview
  • Structural
  • Thermal
  • Electromagnetic
  • Joule heating
  • Thermal stress
  • Acoustics
  • Fluid flow
  • Conjugate heat transfer
  • Fluid–structure
  • What is FEA

Industries

  • Aerospace
  • Automotive and transportation
  • Defense
  • Electronics and semiconductors
  • Energy
  • Industrial machinery
  • Life sciences
  • Quantitative finance

Learn

  • Guides
  • Docs
  • Function reference
  • Language reference
  • Migration guide
  • Changelog
  • MATLAB Online
  • MATLAB AI agent
  • For students

Compare

  • RunMat vs MATLAB
  • RunMat vs Ansys
  • RunMat vs SOLIDWORKS
  • RunMat vs Altium
  • RunMat vs Cadence
  • RunMat vs COMSOL
  • RunMat vs Python
  • RunMat vs Julia
  • RunMat vs Physics AI
  • RunMat vs Octave
  • Benchmarks
  • MATLAB alternatives
  • All comparisons

Company

  • About
  • Blog
  • Contact
  • Source code↗
  • License
  • Privacy
  • Terms
GitHubXLinkedIn

© Dystr, Inc. · RunMat v0.7.1, Nov 17, 2026

RunMat® is a registered trademark of Dystr, Inc. MATLAB® is a registered trademark of The MathWorks, Inc. RunMat is not affiliated with, endorsed by, or sponsored by The MathWorks, Inc.

/
See all docs
Builtin Reference
    • 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

gmres — Solve a square linear system with restarted generalized minimum residual iteration.

GMRES over native floating dense, sparse CSC and callable operators, with reusable left preconditioners and residual diagnostics.

Syntax

[x,flag,relres,iter,resvec] = gmres(A,b,restart,tol,maxit,M1,M2,x0)

Inputs

A
Type
Any
Required
Yes
Default
—
Description
Square native single/double dense or CSC matrix, or a repeatable n-vector operator.
b
Type
NumericArray
Required
Yes
Default
—
Description
Native single/double real or complex column vector matching A.
args
Type
Any
Required
Variadic
Default
—
Description
Optional restart, tol, maxit, M1, M2, and x0 positions.
NameTypeRequiredDefaultDescription
AAnyYes—Square native single/double dense or CSC matrix, or a repeatable n-vector operator.
bNumericArrayYes—Native single/double real or complex column vector matching A.
argsAnyVariadic—Optional restart, tol, maxit, M1, M2, and x0 positions.

Returns

x
Type
NumericArray
Description
Approximate solution column vector in b's native class.
flag
Type
NumericScalar
Description
0 converged, 1 iteration limit, 2 numerical preconditioner failure, 3 stagnation, or 4 scalar breakdown. Callback language and allocation/authority failures remain errors.
relres
Type
NumericScalar
Description
Relative norm of the left-preconditioned residual of the returned iterate.
iter
Type
NumericArray
Description
One-by-two outer and inner iteration counts.
resvec
Type
NumericArray
Description
Left-preconditioned residual norm history, beginning with the initial residual.
NameTypeDescription
xNumericArrayApproximate solution column vector in b's native class.
flagNumericScalar0 converged, 1 iteration limit, 2 numerical preconditioner failure, 3 stagnation, or 4 scalar breakdown. Callback language and allocation/authority failures remain errors.
relresNumericScalarRelative norm of the left-preconditioned residual of the returned iterate.
iterNumericArrayOne-by-two outer and inner iteration counts.
resvecNumericArrayLeft-preconditioned residual norm history, beginning with the initial residual.

Returned values from gmres depend on how many outputs the caller requests.

Errors

RunMat:gmres:InvalidInput
When
Input count, geometry, restart, tolerance, or iteration count is invalid.
Message
gmres: invalid input
RunMat:gmres:UnsupportedInput
When
A selected class, residency, or operator route is unavailable.
Message
gmres: unsupported input form
RunMat:gmres:HostAllocation
When
Exact host scratch or retained output storage cannot be admitted.
Message
gmres: host admission failed
IdentifierWhenMessage
RunMat:gmres:InvalidInputInput count, geometry, restart, tolerance, or iteration count is invalid.gmres: invalid input
RunMat:gmres:UnsupportedInputA selected class, residency, or operator route is unavailable.gmres: unsupported input form
RunMat:gmres:HostAllocationExact host scratch or retained output storage cannot be admitted.gmres: host admission failed

Inputs and iteration

gmres(A,b,restart,tol,maxit,M1,M2,x0) solves a square nonsymmetric system. A is a host single/double real or complex dense matrix, CSC matrix, or callable n-vector operator. Scalar double and complex-double systems are supported as order-one operators. b, x0 and matrix preconditioners must match its floating precision and real/complex domain. Sparse coefficients remain sparse; GPU and distributed operands are rejected without gathering.

Optional positions can be empty. By default the method does not restart and takes at most min(n,10) steps. With 1 <= restart < n, maxit counts outer cycles and defaults to min(ceil(n/restart),10). With restart empty or n, maxit counts total inner steps. Tolerance defaults to 1e-6 for double and 1e-3 for single; the default initial guess is zero.

M1 and M2 are matrix inverse actions or callable inverse actions, applied in that order. A matrix is prepared once and reused. Triangular factors are borrowed; general dense matrices use pivoted LU. General sparse matrix preconditioners use an execution context and support finite managed allocation with individually admitted sparse fill growth and reusable solve workspace. Callable operators require an execution context and use its selected callable authority.

Outputs and failures

The outputs are [x,flag,relres,iter,resvec]. relres is norm(M2\(M1\(b-A*x)))/norm(M2\(M1\b)); absent preconditioners are identity actions. resvec begins with the preconditioned initial residual norm and records each completed inner step. iter is a double row vector [outer inner] identifying the returned iterate. Nonconvergence returns the iterate with the smallest independently recomputed preconditioned residual.

Flags are 0 for convergence, 1 for the iteration limit, 2 for numerical failure of a preconditioner, 3 for stagnation, and 4 for scalar numerical breakdown. If the preconditioner fails before any residual can be evaluated, RunMat returns the initial guess, iter [0 0], infinite relres and an empty resvec. Resource denial, cancellation, stale authority and callback language errors remain errors, never convergence flags. Requesting flag suppresses status text; otherwise a concise status is printed.

Precision and execution

Matrix-vector products, basis vectors and the solution preserve native single/double real or complex storage. Norms and inner-product accumulation, the small complex Hessenberg system and rotations use binary64; residual history uses b's floating precision. This mixed-accumulator policy does not promise bit-for-bit MATLAB iteration histories. Mixed input classes are rejected rather than silently widened.

Finite-policy execution admits iteration workspace, each escaping callable input vector and final outputs independently. A callback may retain its input without retaining or aliasing the mutable recurrence scratch. Matrix products, Arnoldi vector work, callback vector/result copies and solution/history publication use bounded work chunks and the execution service's CPU cooperation budget. A receipt-less solve or factor fails if its allocation policy becomes finite; an unpublished output constructor owns and refunds its exact backing across suspension or drop. Dense LU factorization and solves use an owned native CPU job; its scratch remains owned until physical completion even if the caller cancels. The synchronous faer kernel does not yield within a browser task.

Examples

Solve a nonsymmetric system

A = [3 2; 0 1]; b = [5; 1]; [x,flag,relres,iter,resvec] = gmres(A,b);

Restart with a reusable preconditioner

A = [4 1; 2 3]; b = [1; 0]; M = [2 1; 1 2]; [x,flag,relres,iter] = gmres(A,b,1,1e-8,50,M);

Using gmres with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how gmres changes the result.

Run a small gmres example, explain the result, then change one input and compare the output.

Related Linalg functions

Factor

chol · decomposition · decomposition.ctranspose · decomposition.mldivide · decomposition.mrdivide · decomposition.mtimes · decomposition.rdivide · decomposition.subsref · decomposition.times · decomposition.uminus · decomposition.uplus · eig · eigs · ichol · ilu · lu · ordeig · ordqz · ordschur · pcg · qr · qz · rsf2csf · schur · svd

Structure

bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm

Solve

cond · det · inv · linsolve · norm · null · pinv · rank · rcond · rref · vecnorm

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 gmres is executed, line by line, in Rust.

  • View the source for gmres 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.

Getting started · Benchmarks · Pricing

Download RunMat

Download RunMat for full performance, or use RunMat in your browser for zero setup.

Download RunMatOpen Sandbox
On this page
  • Syntax
  • Inputs
  • Returns
  • Errors
  • Inputs and iteration
  • Outputs and failures
  • Precision and execution
  • Examples
  • Solve a nonsymmetric system
  • Restart with a reusable preconditioner
  • Using gmres with coding agents
  • Related Linalg functions
  • Factor
  • Structure
  • Solve
  • Ops
  • Source you can read
  • About RunMat