
Welcome to CgCode, a package of subroutines for the iterative solution
of sparse linear systems of equations.  Originally developed by Steven
Ashby  and Thomas Manteuffel  at Los Alamos   National Laboratory, the
package has been recently updated and  expanded to include several new
methods, and to be easier to use.  Each routine  in CgCode is based on
a conjugate gradient method.  This document  is  a  quick guide to the
package; for  further details see  the prologue  to  the subroutine of
interest.

There are ten CG algorithms available. The table  below will guide you
to  the appropriate  subroutine(s).  In  the  table, A is  the  system
matrix,  C is a preconditioning   matrix,  and C(A)  is  a  polynomial
preconditioner. AH and CH denote the  Hermitian transposes of A and C,
respectively.  CgCode is available in single and double precision.  (A
complex version will be available soon.)  The letter X in each routine
name  below should be replaced  by S, D,  or C for the single, double,
and complex versions of each package, respectively.

         Routine                 Method 
         -------                 ------
         XCG            Conjugate Gradients on A, A hpd.
         XCR            Conjugate Residuals on A, A hpd.
         XCRIND         Conjugate Residuals on A, A hermitian.
         XPCG           Preconditioned CG, A and C hpd.
         XCGNR          CG on AH*A, A arbitrary.
         XCGNE          CG on A*AH, A arbitrary.
         XPCGNR         CGNR on A*C, A and C arbitrary.
         XPCGNE         CGNE on C*A, A and C arbitrary.
         XPPCG          Polynomial Preconditioned CG, A and C hpd.
         XPCGCA         CG on C(A)*A, A and C hpd.

An interface routine, XCGDRV, is  also available.  The desired routine
is called by setting  a flag.  This allows the  user to easily try any
of the routines.

In addition to various input parameters, the user must also  provide a
matrix-vector multiply subroutine,  MATVEC.  (Of  course, the user may
call this anything he wishes; MATVEC is  merely the name used here and
in the  code documentation.)  MATVEC must  be declared  in an external
statement  in  the calling program.   The  subroutine  MUST   have the
following parameter list:

                MATVEC (JOB, A, IA, W, X, Y, N)

JOB is  a  flag specifying whether  the product y=A*x  (JOB=0), y=AH*x
(JOB=1), y=w-A*x (JOB=2), or  y=w-AH*x (JOB=3) is  required.  Only the
normal equations subroutines XCGNR, XCGNE,  XPCGNR, and XPCGNE require
y=AH*x; the  remaining  routines require  only   the  y=A*x operation.
Thus, if the user does  not plan to call any  of the normal  equations
routines, he need not implement the JOB>0  products. The vectors x and
w must not be changed.

A and IA are the  base addresses of  a real  and integer  work  array,
respectively.  These arrays are  strictly for  the  user's use; CgCode
makes no reference to them.  Typically, A will contain the nonzeros of
the matrix.  IA will contain  additional information  about A, such as
its leading dimension in the calling program.  This facilitates use of
MATVEC as  an  interface to another matrix-vector multiply subroutine,
one with a parameter list of the user's choosing.  If one or both of A
and IA is not needed, the variable is a dummy argument.

If XPCG, XPCGNR, or XPCGNE  is  called, the user  must provide a  left
preconditioning routine,  PCONDL.  This routine  also must be declared
in an external  statement, and has  a parameter list and usage similar
to MATVEC.  See the  prologue to XPCG, XPCGNR,  or XPCGNE for details.
If either polynomial preconditioning routine (XPPCG, XPCGCA) is called
with  IPC<>0,  the user must provide  an inner preconditioning routine
PCONDL.  See the prologue to either of these routines for details.

If  either  XPPCG or XPCGCA  is called, the user  must   provide a few
additional  parameters, such as the   degree of the   polynomial to be
used.    These  routines     automatically    generate    the  optimal
preconditioning polynomial  for  the   particular problem.  An   inner
preconditioning may     be  used   in   conjunction   with  polynomial
preconditioning; see   the prologue to   one  of  these  routines  for
details.

Since CgCode uses only standard FORTRAN 77 constructs, the code should
run on any machine supporting FORTRAN 77.  Besides MATVEC  and PCONDL,
the  only external  subroutines required by  CgCode are the following:
the BLAS routines XAXPY,  XCOPY, XDOT, XNRM2, and XSCAL;  the  EISPACK
routine RATQR; and the routine X1MACH for generating machine-dependent
constants.  Since these  routines  are  widely  available, we  do  not
include them with CgCode.

The CgCode  package, and specifically  the driver  routine XCGDRV, was
written to  conform  to  the standard  for  iterative  linear  solvers
proposed   by Steven  Ashby and Mark   Seager [1].  For  more detailed
information about CgCode and the basic theory behind  the package, see
[2].


Any questions regarding the use of CgCode can be directed to:

Michael Holst                         Steven Ashby
Univ. of Illinois                     Lawrence Livermore National Lab.
Dept. of Computer Science             Box 808
1304 W. Springfield Ave.              L-316
Urbana, IL 61801                      Livermore, CA 94550

Phone: (217) 333-6172                 Phone: (415) 423-2462
Email: cgcode@martini.cs.uiuc.edu     Email: ashby@lll-crg.llnl.gov


                               DISCLAIMER

The authors of this computer code  material do not  make any warranty,
express or  implied, or assume any legal  liability  or responsibility
for the   accuracy,  completeness or  usefulness of  any  information,
apparatus, product  or process disclosed,  or  represent  that its use
would not infringe privately-owned rights.


                               REFERENCES

[1] S. F. Ashby and  M. K.  Seager,   A proposed standard  for  linear
       iterative solvers (Version 1.0),  Technical Report UCRL-102860, 
       Lawrence Livermore National Laboratory, 1990.  

[2] M.  J. Holst.   CgCode:  Software for Solving  Linear Systems with
       Conjugate Gradient  Methods,  Master's  Thesis, Department   of
       Computer Science, University of Illinois, 1990.


                        --- December 9, 1990 ---



