MATLAB Function Reference

pcg - Preconditioned conjugate gradients method

Syntax

x = pcg(A,b)
pcg(A,b,tol)
pcg(A,b,tol,maxit)
pcg(A,b,tol,maxit,M)
pcg(A,b,tol,maxit,M1,M2)
pcg(A,b,tol,maxit,M1,M2,x0)
[x,flag] = pcg(A,b,...)
[x,flag,relres] = pcg(A,b,...)
[x,flag,relres,iter] = pcg(A,b,...)
[x,flag,relres,iter,resvec] = pcg(A,b,...)

Description

x = pcg(A,b) attempts to solve the system of linear equations A*x=b for x. The n-by-n coefficient matrix A must be symmetric and positive definite, and should also be large and sparse. The column vector b must have length n. A can be a function handle afun such that afun(x) returns A*x. See Function Handles in the MATLAB^® Programming documentation for more information.

, in the MATLAB Mathematics documentation, explains how to provide additional parameters to the function afun, as well as the preconditioner function mfun described below, if necessary.

If pcg converges, a message to that effect is displayed. If pcg 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.

pcg(A,b,tol) specifies the tolerance of the method. If tol is [], then pcg uses the default, 1e-6.

pcg(A,b,tol,maxit) specifies the maximum number of iterations. If maxit is [], then pcg uses the default, min(n,20).

pcg(A,b,tol,maxit,M) and pcg(A,b,tol,maxit,M1,M2) use symmetric positive definite preconditioner M or M = M1*M2 and effectively solve the system inv(M)*A*x = inv(M)*b for x. If M is [] then pcg applies no preconditioner. M can be a function handle mfun such that mfun(x) returns M\x.

pcg(A,b,tol,maxit,M1,M2,x0) specifies the initial guess. If x0 is [], then pcg uses the default, an all-zero vector.

[x,flag] = pcg(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] = pcg(A,b,...) also returns the relative residual norm(b-A*x)/norm(b). If flag is 0, relres <= tol.

[x,flag,relres,iter] = pcg(A,b,...) also returns the iteration number at which x was computed, where 0 <= iter <= maxit.

[x,flag,relres,iter,resvec] = pcg(A,b,...) also returns a vector of the residual norms at each iteration including norm(b-A*x0).

Examples

Example 1

n1 = 21; 
A = gallery('moler',n1);  
b1 = A*ones(n1,1);
tol = 1e-6;  
maxit = 15;  
M = diag([10:-1:1 1 1:10]);
[x1,flag1,rr1,iter1,rv1] = pcg(A,b1,tol,maxit,M);

Alternatively, you can use the following parameterized matrix-vector product function afun in place of the matrix A:

afun = @(x,n)gallery('moler',n)*x;
n2 = 21; 
b2 = afun(ones(n2,1),n2);
[x2,flag2,rr2,iter2,rv2] = pcg(@(x)afun(x,n2),b2,tol,maxit,M);

Example 2

A = delsq(numgrid('C',25));
b = ones(length(A),1);
[x,flag] = pcg(A,b)

flag is 1 because pcg does not converge to the default tolerance of 1e-6 within the default 20 iterations.

R = cholinc(A,1e-3);
[x2,flag2,relres2,iter2,resvec2] = pcg(A,b,1e-8,10,R',R)

flag2 is 0 because pcg converges to the tolerance of 1.2e-9 (the value of relres2) at the sixth iteration (the value of iter2) when preconditioned by the incomplete Cholesky factorization with a drop tolerance of 1e-3. resvec2(1) = norm(b) and resvec2(7) = norm(b-A*x2). You can follow the progress of pcg by plotting the relative residuals at each iteration starting from the initial estimate (iterate number 0).

semilogy(0:iter2,resvec2/norm(b),'-o')
xlabel('iteration number')
ylabel('relative residual')

See Also

bicg, bicgstab, cgs, cholinc, gmres, lsqr, minres, qmr, symmlq

function_handle (@), mldivide (\)

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.

pbaspect

pchip