cgs

Conjugate Gradients Squared method

Syntax

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

Description

x = cgs(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.

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

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

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

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

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

cgs(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...) passes parameters p1,p2,... to functions afun(x,p1,p2,...), m1fun(x,p1,p2,...), and m2fun(x,p1,p2,...)

[x,flag] = cgs(A,b,...) returns a solution x and a flag that describes the convergence of cgs.

Flag	Convergence
0	cgs converged to the desired tolerance tol within maxit iterations.
1	cgs iterated maxit times but did not converge.
2	Preconditioner M was ill-conditioned.
3	cgs stagnated. (Two consecutive iterates were the same.)
4	One of the scalar quantities calculated during cgs became too small or too large to continue computing.

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

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

[x,flag,relres,iter,resvec] = cgs(A,b,...) also returns a vector of the residual norms at each 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 = cgs(A,b,tol,maxit,M1,[],[]);
  

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 cgs.

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

Note that both afun and mfun must accept cgs's extra input n=21.

Example 2.

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

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

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

flag1 is 2 because the upper triangular U1 has a zero on its diagonal, and cgs fails in the first iteration when it tries to solve a system such as U1*y = r for y with backslash.

• [L2,U2] = luinc(A,1e-6)
  [x2,flag2,relres2,iter2,resvec2] = cgs(A,b,1e-15,10,L2,U2)
  

flag2 is 0 because cgs converges to the tolerance of 6.344e-16 (the value of relres2) at the fifth iteration (the value of iter2) when preconditioned by the incomplete LU factorization with a drop tolerance of 1e-6. resvec2(1) = norm(b) and resvec2(6) = norm(b-A*x2). You can follow the progress of cgs by plotting the relative residuals at each iteration starting from the initial estimate (iterate number 0) with

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

char

Create character array (string)

Syntax

• S = char(X)
  S = char(C)
  S = char(t1,t2,t3...)
  

Description

S = char(X) converts the array X that contains positive integers representing character codes into a MATLAB character array (the first 127 codes are ASCII). The actual characters displayed depend on the character set encoding for a given font. The result for any elements of X outside the range from 0 to 65535 is not defined (and may vary from platform to platform). Use double to convert a character array into its numeric codes.

S = char(C) when C is a cell array of strings, places each element of C into the rows of the character array s. Use cellstr to convert back.

S = char(t1,t2,t3,..) forms the character array S containing the text strings T1,T2,T3,... as rows, automatically padding each string with blanks to form a valid matrix. Each text parameter, Ti, can itself be a character array. This allows the creation of arbitrarily large character arrays. Empty strings are significant.

Remarks

Ordinarily, the elements of A are integers in the range 32:127, which are the printable ASCII characters, or in the range 0:255, which are all 8-bit values. For noninteger values, or values outside the range 0:255, the characters printed are determined by fix(rem(A,256)).

Examples

To print a 3-by-32 display of the printable ASCII characters:

• ascii = char(reshape(32:127,32,3)')
  ascii =
  ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
  @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _
  ' a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~

checkin

Check file into source control system

Graphical Interface

As an alternative to the checkin function, use Source Control Check In in the Editor, Simulink, or Stateflow File menu.

Syntax

• checkin('filename','comments','string')
  checkin({'filename1','filename2','filename3', ...},'comments',
  'string')
  checkin('filename','option','value', ...)
  

Description

checkin('filename','comments','string') checks in the file named filename to the source control system. Use the full pathname for the filename. You must save the file before checking it in. The file can be open or closed when you use checkin. The string argument is a MATLAB string containing check-in comments for the source control system. You must supply the comments argument and 'string'.

checkin({'filename1','filename2','filename3', ...},'comments', 'string') checks in the files named filename1 through filenamen to the source control system. Use the full pathnames for the files. Additional arguments apply to all files checked in.

checkin('filename','option','value', ...) provides additional checkin options. The option and value arguments are shown in the table below.

option Argument	Purpose	value Argument
'force'	When set to on, filename is checked in even if the file has not changed since it was checked out. The default value for force is off.	'on' 'off' (default)
'lock'	When set to on, filename remains checked out. Comments are submitted. The default value for lock is off.	'on' 'off' (default)

You can check in a file that you checked out in a previous MATLAB session or that you checked out directly from your source control system.

Examples

Check in a File with Comments

Typing

• checkin('/matlab/mymfiles/clock.m','comments','Adjustment for
  Y2K')
  

checks in the file /matlab/mymfiles/clock.m to the source control system with the comment Adjustment for Y2K.

Check in Multiple Files with Comments

Typing

• checkin({'/matlab/mymfiles/clock.m', ...
  '/matlab/mymfiles/calendar.m'},'comments','Adjustment for Y2K')
  

checks two files into the source control system using the same comment for each.

Check a File in and Keep It Checked out

Typing

• checkin('/matlab/mymfiles/clock.m','comments','Adjustment for
  Y2K','lock','on')
  

checks the file /matlab/mymfiles/clock.m into the source control system and keeps the file checked out.

checkout

Check file out of source control system

Graphical Interface

As an alternative to the checkout function, use Source Control Check Out in the Editor, Simulink, or Stateflow File menu.

Syntax

• checkout('filename')
  checkout({'filename1','filename2','filename3', ...})
  checkout('filename','option','value', ...)
  

Description

checkout('filename') checks out the file named filename from the source control system. filename must be the full pathname for the file. The file can be open or closed when you use checkout.

checkout({'filename1','filename2','filename3', ...}) checks out the files named filename1 through filenamen from the source control system. Use the full pathnames for the files. Additional arguments apply to all files checked out.

checkout('filename','option','value', ...) provides additional checkout options. The option and value arguments are shown in the following table.

option Argument	Purpose	value Argument
'force'	When set to on, the checkout is forced, even if you already have the file checked out. This is effectively an undocheckout followed by a checkout. When force is set to off, you can't check out the file if you already have it checked out.	'on' 'off' (default)
'lock'	When set to on, the checkout gets the file, allows you to write to it, and locks the file so that access to the file for others is read only. When set to off, the checkout gets a read-only version of the file, allowing another user to check out the file for updating. With lock set to off, you don't have to check in a file after checking it out.	'on' (default) 'off'
'revision'	Checks out the specified revision of the file.	'version_num'

If you end the MATLAB session, the file remains checked out. You can check in the file from within MATLAB during a later session, or directly from your source control system.

Examples

Check out a File

Typing

• checkout('/matlab/mymfiles/clock.m')
  

checks out the file /matlab/mymfiles/clock.m from the source control system.

Check out Multiple Files

Typing

• checkout({'/matlab/mymfiles/clock.m',...
  '/matlab/mymfiles/calendar.m'})
  

checks out /matlab/mymfiles/clock.m and
/matlab/mymfiles/calendar.m from the source control system.

Force a Checkout, Even If File Is Already Checked out

Typing

• checkout('/matlab/mymfiles/clock.m','force','on')
  

checks out /matlab/mymfiles/clock.m even if clock.m is already checked out to you.

Check out Specified Revision of File

Typing

• checkout('/matlab/mymfiles/clock.m','revision','1.1')
  

checks out revision 1.1 of clock.m.