MATLAB Function Reference |

Generalized Minimum Residual method (with restarts)

**Syntax**

x = gmres(A,b) gmres(A,b,restart) gmres(A,b,restart,tol) gmres(A,b,restart,tol,maxit) gmres(A,b,restart,tol,maxit,M) gmres(A,b,restart,tol,maxit,M1,M2) gmres(A,b,restart,tol,maxit,M1,M2,x0) gmres(afun,b,restart,tol,maxit,m1fun,m2fun,x0,p1,p2,...) [x,flag] = gmres(A,b,...) [x,flag,relres] = gmres(A,b,...) [x,flag,relres,iter] = gmres(A,b,...) [x,flag,relres,iter,resvec] = gmres(A,b,...)

**Description**

```
x = gmres(A,b)
```

attempts to solve the system of linear equations `A*x = b`

for `x`

. The `n`

-by-`n`

coefficient matrix `A`

must be square and should be large and sparse. The column vector `b`

must have length `n`

. `A`

can be a function `afun`

such that `afun(x)`

returns `A*x`

. For this syntax, `gmres`

does not restart; the maximum number of iterations is `min(n,10)`

.

If `gmres`

converges, a message to that effect is displayed. If `gmres`

fails to converge after the maximum number of iterations or halts for any reason, a warning message is printed displaying the relative residual `norm(b-A*x)/norm(b)`

and the iteration number at which the method stopped or failed.

```
gmres(A,b,restart)
```

restarts the method every `restart`

inner iterations. The maximum number of outer iterations is `min(n/restart,10)`

. The maximum number of total iterations is `restart*min(n/restart,10)`

. If `restart`

is `n`

or `[]`

, then `gmres`

does not restart and the maximum number of total iterations is `min(n,10)`

.

```
gmres(A,b,restart,tol)
```

specifies the tolerance of the method. If `tol`

is `[]`

, then `gmres`

uses the default, `1e-6`

.

```
gmres(A,b,restart,tol,maxit)
```

specifies the maximum number of outer iterations, i.e., the total number of iterations does not exceed `restart*maxit`

. If `maxit`

is `[]`

then `gmres`

uses the default, `min(n/restart,10)`

. If `restart`

is `n`

or `[]`

, then the maximum number of total iterations is `maxit`

(instead of `restart*maxit`

).

```
gmres(A,b,restart,tol,maxit,M) and
gmres(A,b,restart,tol,maxit,M1,M2)
```

use preconditioner `M`

or `M = M1*M2`

and effectively solve the system `inv(M)*A*x = inv(M)*b`

for `x`

. If `M`

is `[]`

then `gmres`

applies no preconditioner. `M`

can be a function that returns `M\x`

.

```
gmres(A,b,restart,tol,maxit,M1,M2,x0)
```

specifies the first initial guess. If `x0`

is `[]`

, then `gmres`

uses the default, an all-zero vector.

```
gmres(afun,b,restart,tol,maxit,m1fun,m2fun,x0,p1,p2,...)
```

passes parameters to functions `afun(x,p1,p2,...)`

, `m1fun(x,p1,p2,...)`

, and `m2fun(x,p1,p2,...)`

.

`[x,flag] = gmres(A,b,`

also returns a convergence flag:`...`

)

Whenever `flag`

is not `0`

, the solution `x`

returned is that with minimal norm residual computed over all the iterations. No messages are displayed if the `flag`

output is specified.

`[x,flag,relres] = gmres(A,b`

also returns the relative residual `,...`

)
`norm(b-A*x)/norm(b)`

. If `flag`

is `0`

, `relres <= tol`

.

`[x,flag,relres,iter] = gmres(A,b,`

also returns both the outer and inner iteration numbers at which `...`

)
`x`

was computed, where `0 <= iter(1) <= maxit`

and `0 <= iter(2) <= restart`

.

`[x,flag,relres,iter,resvec] = gmres(A,b`

also returns a vector of the residual norms at each inner iteration, including `,...`

)
`norm(b-A*x0)`

.

**Examples**

A = gallery('wilk',21); b = sum(A,2); tol = 1e-12; maxit = 15; M1 = diag([10:-1:1 1 1:10]); x = gmres(A,b,10,tol,maxit,M1,[],[]); gmres(10) converged at iteration 2(10) to a solution with relative residual 1.9e-013

Alternatively, use this matrix-vector product function

and this preconditioner backsolve function

Note that both `afun`

and `mfun`

must accept the `gmres`

extra input `n=21`

.

`flag `

is `1`

because `gmres`

does not converge to the default tolerance `1e-6`

within the default 10 outer iterations.

`flag1`

is` 2`

because the upper triangular `U1`

has a zero on its diagonal, and `gmres`

fails in the first iteration when it tries to solve a system such as `U1*y = r`

for `y`

using backslash.

[L2,U2] = luinc(A,1e-6); tol = 1e-15; [x4,flag4,relres4,iter4,resvec4] = gmres(A,b,4,tol,5,L2,U2); [x6,flag6,relres6,iter6,resvec6] = gmres(A,b,6,tol,3,L2,U2); [x8,flag8,relres8,iter8,resvec8] = gmres(A,b,8,tol,3,L2,U2);

`flag4`

, `flag6`

, and `flag8`

are all `0`

because `gmres`

converged when restarted at iterations 4, 6, and 8 while preconditioned by the incomplete LU factorization with a drop tolerance of `1e-6`

. This is verified by the plots of outer iteration number against relative residual. A combined plot of all three clearly shows the restarting at iterations 4 and 6. The total number of iterations computed may be more for lower values of `restart`

, but the number of length `n`

vectors stored is fewer, and the amount of work done in the method decreases proportionally.

**See Also**

`bicg`

, `bicgstab`

, `cgs`

, `lsqr`

, `luinc`

, minres, `pcg`

, `qmr`

, `symmlq`

`@`

(function handle), `\`

(backslash)

**References**

[1] Barrett, R., M. Berry, T. F. Chan, et al., *Templates for the Solution of Linear
Systems: Building Blocks for Iterative Methods*, SIAM, Philadelphia, 1994.

[2] Saad, Youcef and Martin H. Schultz, "GMRES: A generalized minimal
residual algorithm for solving nonsymmetric linear systems", *SIAM J. Sci.
Stat. Comput.*, July 1986, Vol. 7, No. 3, pp. 856-869.

global | gplot |