psldlt(3F)

NAME
     PSLDLT_Preprocess, PSLDLT_Factor, PSLDLT_Solve, PSLDLT_Destroy,
     PSLDLT_Ordering - parallel sparse symmetric linear system solver

DESCRIPTION
     PSLDLT solves sparse symmetric linear systems of the form
        Ax = b
     where A is an n x n symmetric input matrix, b is an input vector of
     length n, and x is an unknown vector of length n.  PSLDLT uses a direct
     method: A is factored into the form
       A = L D L-transpose
     where L is a lower triangular matrix with unit diagonal and D is a
     diagonal matrix.

     The PSLDLT library contains four main routines.  PSLDLT_Preprocess()
     performs preprocessing operations on the structure of A (heuristic
     reordering to reduce fill in L, symbolic factorization, etc.).
     PSLDLT_Factor() factors the matrix A into L and D, using the previously
     computed preprocessing data.  PSLDLT_Solve() solves for a vector x, given
     an input vector b.  PSLDLT_Destroy() frees all storage associated with
     the matrix A (including L, D, and various data structures computed during
     preprocessing).  Note that the user can call PSLDLT_Factor() several
     times after a single call to PSLDLT_Preprocess() to factor multiple
     matrices with identical non-zero structures but different values.
     Similarly, the user can call PSLDLT_Solve() several times after a single
     call to PSLDLT_Factor() to solve for multiple right-hand-sides.

     Sparse matrix A must be input to PSLDLT in Harwell-Boeing format (also
     known as Compressed Column Storage format).  The matrix is held in three
     arrays: pointers[], indices[], and values[].  The indices[] array
     contains the row indices of the non-zeros in A.  The values[] array holds
     the corresponding non-zero values.  The pointers[] array contains the
     index in indices[] for the first non-zero in each column of A.  Thus, the
     row indices for the non-zeros in column i can be found in locations
     indices[pointers[i]] through indices[pointers[i+1]-1].  The corresponding
     values can be found in location values[pointers[i]] through
     values[pointers[i+1]-1].

     For a symmetric matrix A, the user must input either the lower or upper
     triangle of A, but not both.  Non-zeroes within a column of A can be
     stored in any order.

     To give an example, the following symmetric matrix...
             1.0   symmetric
             0.0 3.0
             2.0 0.0 5.0
             0.0 4.0 0.0 6.0

     would be represented in FORTRAN as follows:

             pointers[] = {1, 3, 5, 6, 7}
             indices[] = {1, 3, 2, 4, 3, 4}
             values[] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0}

     Zero-based indexing is used in C, so the pointers[] and indices[] arrays
     would instead contain:

             pointers[] = {0, 2, 4, 5, 6}
             indices[] = {0, 2, 1, 3, 2, 3}

     The routine PSLDLT_Ordering allows the user to change the ordering method
     used to pre-order the matrix before factorization.  This routine must be
     called before calling PSLDLT_Preprocess.  Three options are currently
     available: method 0 performs no pre-ordering, method 1 (the default)
     performs Approximate Minimum Degree ordering, and method 2 performs
     multi-level nested dissection ordering.  Method 2 is significantly more
     expensive than method 1, but it often produces significantly better
     orderings.

     The environment variable MPC_NUM_THREADS determines the number of
     processors that are used for the numerical factorization.  Setting the
     environment variable PSLDLT_VERBOSE causes PSLDLT to output information
     about the factorization.


FORTRAN SYNOPSIS
     SUBROUTINE PSLDLT_PREPROCESS (TOKEN, N, POINTERS, INDICES, NONZ, OPS)

         INTEGER TOKEN, N

         INTEGER POINTERS( * ), INDICES( *)

         INTEGER NONZ,

         DOUBLE PRECISION OPS


     SUBROUTINE PSLDLT_FACTOR (TOKEN, N, POINTERS, INDICES, VALUES)

         INTEGER TOKEN, N

         INTEGER POINTERS( * ), INDICES( * )

         DOUBLE PRECISION VALUES( * )


     SUBROUTINE PSLDLT_SOLVE (TOKEN, X, B)

         INTEGER TOKEN

         DOUBLE PRECISION X( * ), B( * )

     SUBROUTINE PSLDLT_DESTROY (TOKEN)

         INTEGER TOKEN

     SUBROUTINE PSLDLT_DESTROY (TOKEN, METHOD)

         INTEGER TOKEN

         INTEGER METHOD

C SYNOPSIS
     void PSLDLT_Preprocess (

         int token,

         int n,

         int pointers[],

         int indices[],

         int *nonz,

         double *ops

         );

     void PSLDLT_Factor (

         int token,

         int n,

         int pointers[],

         int indices[],

         double values[]

         );

     void PSLDLT_Solve (

         int token,

         double x[],

         double b[]

         );

     void PSLDLT_Destroy (

         int token

         );

     void PSLDLT_Ordering (

         int token,

         int method

         );


ARGUMENTS
     token (input)
             PSLDLT can handle multiple matrices simultaneously.  The token
             distinguishes between active matrices.  The token passed to
             PSLDLT_Factor() must match the token used in some previous call
             to PSLDLT_Preprocess().  Similarly, the token passed to
             PSLDLT_Solve() must match the token used in some previous call to
             PSLDLT_Factor().

     n (input)
             The number of rows and columns in the matrix A.  n >= 0.

     pointers, indices, values (input)
             The pointers and indices arrays store the non-zero structure of
             sparse input matrix A in Harwell-Boeing or Compressed Sparse
             Column (CSC) format.  The pointers array stores n+1 integers,
             where pointers[i] gives the index in indices of the first non-
             zero in column i of A.  The indices array stores the row indices
             of the non-zeros in A.  The nz array stores the non-zero values
             in the matrix A.

     nonz, ops (output)
             The number of non-zero values in L, and the number of floating-
             point operations required to factor A.

     b (input)
             The right-hand-side vector in a PSLDLT_Solve call.

     x (output)
             The solution vector in a PSLDLT_Solve call.

TUNING
     Optimized and parallelized for the SGI R8000 platform.