##### 22.6.2.16 pcg

— Function File: x = pcg (a, b, tol, maxit, m, x0, ...)
— Function File: [x, flag, relres, iter, resvec, eigest] = pcg (...)

> Solves the linear system of equations a`*` x`=` b by means of the Preconditioned Conjugate Gradient iterative method. The input arguments are

> - a can be either a square (preferably sparse) matrix or a function handle, inline function or string containing the name of a function which computes a`*` x. In principle a should be symmetric and positive definite; if `pcg` finds a to not be positive definite, you will get a warning message and the flag output parameter will be set.
> - b is the right hand side vector.
> - tol is the required relative tolerance for the residual error, b`-` a`*` x. The iteration stops if `norm (`b`-` a`*` x`) <=` tol`* norm (`b`-` a`*` x0`)`. If tol is empty or is omitted, the function sets tol`= 1e-6` by default.
> - maxit is the maximum allowable number of iterations; if `[]` is supplied for `maxit`, or `pcg` has less arguments, a default value equal to 20 is used.
> - m is the (left) preconditioning matrix, so that the iteration is (theoretically) equivalent to solving by `pcg` P`*` x`=` m`\` b, with P`=` m`\` a. Note that a proper choice of the preconditioner may dramatically improve the overall performance of the method. Instead of matrix m, the user may pass a function which returns the results of applying the inverse of m to a vector (usually this is the preferred way of using the preconditioner). If `[]` is supplied for m, or m is omitted, no preconditioning is applied.
> - x0 is the initial guess. If x0 is empty or omitted, the function sets x0 to a zero vector by default.

> The arguments which follow x0 are treated as parameters, and passed in a proper way to any of the functions (a or m) which are passed to `pcg`. See the examples below for further details. The output arguments are

> - x is the computed approximation to the solution of a`*` x`=` b.
> - flag reports on the convergence. flag`= 0` means the solution converged and the tolerance criterion given by tol is satisfied. flag`= 1` means that the maxit limit for the iteration count was reached. flag`= 3` reports that the (preconditioned) matrix was found not positive definite.
> - relres is the ratio of the final residual to its initial value, measured in the Euclidean norm.
> - iter is the actual number of iterations performed.
> - resvec describes the convergence history of the method. resvec`(i,1)` is the Euclidean norm of the residual, and resvec`(i,2)` is the preconditioned residual norm, after the (i-1)-th iteration, i`= 1,2,...`iter`+1`. The preconditioned residual norm is defined as `norm (`r`) ^ 2 =` r`' * (`m`\` r`)` where r`=` b`-` a`*` x, see also the description of m. If eigest is not required, only resvec`(:,1)` is returned.
> - eigest returns the estimate for the smallest eigest`(1)` and largest eigest`(2)` eigenvalues of the preconditioned matrix P`=` m`\` a. In particular, if no preconditioning is used, the extimates for the extreme eigenvalues of a are returned. eigest`(1)` is an overestimate and eigest`(2)` is an underestimate, so that eigest`(2) /` eigest`(1)` is a lower bound for `cond (`P`, 2)`, which nevertheless in the limit should theoretically be equal to the actual value of the condition number. The method which computes eigest works only for symmetric positive definite a and m, and the user is responsible for verifying this assumption.

> Let us consider a trivial problem with a diagonal matrix (we exploit the sparsity of A)

>               	N = 10;
>               	A = diag([1:N]); A = sparse(A);
>               	b = rand(N,1);

> Example 1: Simplest use of `pcg`

>                 x = pcg(A,b)

> Example 2: `pcg` with a function which computes a`*` x

>                 function y = applyA(x)
>                   y = [1:N]'.*x;
>                 endfunction

>                 x = pcg('applyA',b)

> Example 3: Preconditioned iteration, with full diagnostics. The preconditioner (quite strange, because even the original matrix a is trivial) is defined as a function

>                 function y = applyM(x)
>                   K = floor(length(x)-2);
>                   y = x;
>                   y(1:K) = x(1:K)./[1:K]';
>                 endfunction

>                 [x, flag, relres, iter, resvec, eigest] = pcg(A,b,[],[],'applyM')
>                 semilogy([1:iter+1], resvec);

> Example 4: Finally, a preconditioner which depends on a parameter k.

>                 function y = applyM(x, varargin)
>                 K = varargin{1};
>                 y = x; y(1:K) = x(1:K)./[1:K]';
>                 endfuntion

>                 [x, flag, relres, iter, resvec, eigest] = ...
>                      pcg(A,b,[],[],'applyM',[],3)

> References

> [1] C.T.Kelley, 'Iterative methods for linear and nonlinear equations', SIAM, 1995 (the base PCG algorithm)

> [2] Y.Saad, 'Iterative methods for sparse linear systems', PWS 1996 (condition number estimate from PCG) Revised version of this book is available online at http://www-users.cs.umn.edu/~saad/books.html

> See also: sparse, pcr.