MATLAB Function Reference

gmres

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:

flag = 0	gmres converged to the desired tolerance tol within maxit outer iterations.
flag = 1	gmres iterated maxit times but did not converge.
flag = 2	Preconditioner M was ill-conditioned.
flag = 3	gmres stagnated. (Two consecutive iterates were the same.)

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

Example 1.

• 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

• function y = afun(x,n)
  y = [0; 
       x(1:n-1)] + [((n-1)/2:-1:0)'; 
       (1:(n-1)/2)'] .*x + [x(2:n); 
       0];
  

and this preconditioner backsolve function

• function y = mfun(r,n)
  y = r ./ [((n-1)/2:-1:1)'; 1; (1:(n-1)/2)'];
  

as inputs to gmres

• x1 = gmres(@afun,b,10,tol,maxit,@mfun,[],[],21);
  

Note that both afun and mfun must accept the gmres extra input n=21.

Example 2.

• load west0479
  A = west0479
  b = sum(A,2)
  [x,flag] = gmres(A,b,5)
  

flag is 1 because gmres does not converge to the default tolerance 1e-6 within the default 10 outer iterations.

• [L1,U1] = luinc(A,1e-5);
  [x1,flag1] = gmres(A,b,5,1e-6,5,L1,U1);
  

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