intro_solvers(3S)

NAME
     INTRO_SOLVERS - Introduction to SGI-developed linear equation solvers

IMPLEMENTATION
     See individual man pages for implementation information

DESCRIPTION
     SCSL provides two direct solvers, PSLDLT and PSLDU, and one iterative
     solver, DIterative, for sparse linear systems of equations.  These
     solvers are optimized and parallelized for the SGI platforms.  For direct
     solvers for dense linear systems of equations, see the INTRO_LAPACK(3S)
     man page.

     The following data types are used in these routines:

     *   Double precision: Fortran "double precision" data type, C/C++
         "double" data type, 64-bit floating point; these routine names begin
         with D.

     *   Double precision complex: Fortran "double complex" data type, C/C++
         "scsl_zomplex" data type (defined in <scsl_sparse.h>), C++ STL
         "complex<double>" data type (defined in <complex.h>), two 64-bit
         floating point doubles; these routine names begin with Z.

     By default, the integer arguments are 4 bytes (32 bits) in size; this is
     the size obtained when one links to the SCSL library with -lscs or
     -lscs_mp. Another version of SCSL is available, however, in which
     integers are 8 bytes (64 bits).  This version allows the user access to
     larger memory sizes and helps when porting legacy Cray codes.  It can be
     loaded by using either the -lscs_i8 or -lscs_i8_mp link option.  Note
     that any program may use only one of the two versions; 4-byte integer and
     8-byte integer library calls cannot be mixed.

     C/C++ function prototypes for sparse solver routines are provided in
     <scsl_sparse.h>, when using the default 4-byte integers, and
     <scsl_sparse_i8.h>, when using 8-byte integers. These header files define
     the complex types scsl_complex and scsl_zomplex, which are used in the
     prototypes. Alternatively, C++ programs may declare arguments using the
     types complex<float> and complex<double> from the standard template
     library. But if these types are used, <complex.h> must be included before
     <scsl_sparse.h> (or <scsl_sparse_i8.h>). Note, though, that both complex
     types are equivalent: they simply represent (real, imaginary) pairs of
     floating point numbers stored contiguously in memory. With the proper
     casts, you can simply pass arrays of floating point data to the routines
     where complex arguments are expected.

     Casts, however, can be avoided. The header files <scsl_sparse.h> and
     <scsl_sparse_i8.h> directly support the use of user-defined complex types
     or disabling prototype checking for complex arguments completely.  By
     defining the symbol SCSL_VOID_ARGS before including <scsl_sparse.h> or
     <scsl_sparse_i8.h> all complex arguments will be prototyped as void *.
     To define the symbol SCSL_VOID_ARGS at compile time use the -D compiler
     option (i.e., -DSCSL_VOID_ARGS) or use an explicit #define SCSL_VOID_ARGS
     in the source code.  This allows the use of any complex data structure
     without warnings from the compiler, provided the structure is as
     described above; that is:

     1.   The real and imaginary components must be contiguous in memory.

     2.   Sequential array elements must also be contiguous in memory.

     While this allows the use of non-standard complex types without
     generating compiler warnings, it has the disadvantage that the compiler
     will not catch type mismatches.

     Strong type checking can be enabled employing user-defined complex types
     instead of SCSL's standard complex types. To do this, define
     SCSL_USER_COMPLEX_T=my_complex and SCSL_USER_ZOMPLEX_T=my_zomplex, where
     my_complex and my_zomplex are the names of user-defined complex types.
     These complex types must be defined before including the <scsl_sparse.h>
     (or <scsl_sparse_i8.h>) header file.

     Fortran 90 users on IRIX systems can perform compile-time checking of
     SCSL sparse solver subroutine and function calls by adding USE
     SCSL_SPARSE (for 4-byte integer arguments) or USE SCSL_SPARSE_I8 (for 8-
     byte integer arguments) to the source code from which the sparse solver
     calls are made.  Alternatively, the compile-time checking can be invoked
     without any source code modifications by using the -auto_use compiler
     option, e.g.,

          f90 -auto_use SCSL_SPARSE test.f -lscs
          f90 -auto_use SCSL_SPARSE_I8 -i8 test.f -lscs_i8


Direct solver routines
     DPSLDLT and ZPSLDLT solve sparse symmetric linear systems of the form Ax
     = b where A is an n-by-n symmetric input matrix, b is an input vector of
     length n, and x is a vector of unknowns of length n.

     The symmetric solver uses a direct method. A is factored into the
     following form:

          A = L D LT

     where L is a lower triangular matrix with unit diagonal and D is a
     diagonal matrix.

     The symmetric solver supports both real and complex double precision data
     types and is available in the multi-processing versions of SCSL.  See the
     DPSLDLT(3S) and ZPSLDLT(3S) man pages for details.

     DPSLDU and ZPSLDU solve sparse unsymmetric linear systems of the form Ax
     = b where A is an n-by-n input matrix with symmetric non-zero pattern but
     unsymmetric non-zero values, b is an input vector of length n, and x is a
     vector of unknowns of length n.

     The unsymmetric solver uses a direct method. A is factored into the
     following form:

          A = L D U

     where L is a lower triangular matrix with unit diagonal, D is a diagonal
     matrix, and U is an upper triangular matrix with unit diagonal.

     The unsymmetric solver supports both real and complex double precision
     data types and is available in the multi-processing versions of SCSL. See
     the DPSLDU(3S) and ZPSLDU(3S) man pages for details.

Iterative solver routines
     DIterative solves sparse linear systems of the form Ax = b where A is a
     n-by-n sparse input matrix in Compressed Sparse Column (CSC) or
     Compressed Sparse Row (CSR) format, b is an input vector of length n, and
     x is a vector of unknowns of length n.

     The iterative solver uses on of four preconditioned iterative methods:
     conjugate gradient (CG) and conjugate residual (CR) for symmetric
     systems, and conjugate gradient squared (CGS) and BiCGSTAB, a variant of
     of CGS with smoother convergence properties,  for unsymmetric systems.
     Four different types of preconditioners are available: Jacobi, symmetric
     successive over-relaxation (SSOR), ILDLT (incomplete LDLT) by pattern,
     and ILDLT by value. The ILDLT preconditioners are only available for
     symmetric matrices, and ILDLT by value is currently not parallel.

     The iterative solver supports only real double precision data.  See the
     ITERATIVE(3S) man page for details.

NOTES
     No pivoting is done in the direct sparse solver routines.

     SCSL does not currently support reshaped arrays.

SEE ALSO
     INTRO_SCSL(3S), INTRO_LAPACK(3S)