psldu(3F)

NAME
     PSLDU_Preprocess, PSLDU_Factor, PSLDU_Solve, PSLDU_Destroy,
     PSLDU_Ordering - parallel sparse unsymmetric linear system solver

DESCRIPTION
     PSLDU solves sparse unsymmetric linear systems of the form
        Ax = b
     where A is an n x n input matrix with symmetric non-zero pattern but
     unsymmetric non-zero values, b is an input vector of length n, and x is
     an unknown vector of length n.  PSLDU uses a direct method: A is factored
     into the 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 PSLDU library contains four main routines.  PSLDU_Preprocess()
     performs preprocessing operations on the structure of A (heuristic
     reordering to reduce fill in L and U, symbolic factorization, etc.).
     PSLDU_Factor() factors the matrix A into L, D and U, using the previously
     computed preprocessing data.  PSLDU_Solve() solves for a vector x, given
     an input vector b.  PSLDU_Destroy() frees all storage associated with the
     matrix A (including L, D, U, and various data structures computed during
     preprocessing).  Note that the user can call PSLDU_Factor() several times
     after a single call to PSLDU_Preprocess() to factor multiple matrices
     with identical non-zero structures but different values.  Similarly, the
     user can call PSLDU_Solve() several times after a single call to
     PSLDU_Factor() to solve for multiple right-hand-sides.

     Sparse matrix A must be input to PSLDU 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].

     PSLDU imposes one constraint on the representation of the A matrix.  The
     non-zeros within each column must appear in order of increasing row
     number.

     To give an example, the following unsymmetric matrix...

             1.0 0.0 5.0 0.0
             0.0 3.0 0.0 8.0
             2.0 0.0 7.0 0.0
             0.0 4.0 0.0 9.0

     would be represented in FORTRAN as follows:
             pointers[] = {1, 3, 5, 7, 9}
             indices[] = {1, 3, 2, 4, 1, 3, 2, 4}
             values[] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0}

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

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

     The routine PSLDLU_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 PSLDU_VERBOSE causes PSLDU to output information
     about the factorization.


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

         INTEGER TOKEN, N

         INTEGER POINTERS( * ), INDICES( *)

         INTEGER NONZ,

         DOUBLE PRECISION OPS


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

         INTEGER TOKEN, N

         INTEGER POINTERS( * ), INDICES( * )

         DOUBLE PRECISION VALUES( * )


     SUBROUTINE PSLDU_SOLVE (TOKEN, X, B)

         INTEGER TOKEN

         DOUBLE PRECISION X( * ), B( * )


     SUBROUTINE PSLDU_DESTROY (TOKEN)

         INTEGER TOKEN

     SUBROUTINE PSLDU_ORDERING (TOKEN, METHOD)

         INTEGER TOKEN

         INTEGER METHOD

C SYNOPSIS
     void PSLDU_Preprocess (

         int token,

         int n,

         int pointers[],

         int indices[],

         int *nonz,

         double *ops

         );

     void PSLDU_Factor (

         int token,

         int n,

         int pointers[],

         int indices[],

         double values[]

         );

     void PSLDU_Solve (

         int token,

         double x[],

         double b[]

         );

     void PSLDU_Destroy (

         int token

         );

     void PSLDU_Ordering (

         int token,

         int method

         );


ARGUMENTS
     token (input)
             PSLDU can handle multiple matrices simultaneously.  The token
             distinguishes between active matrices.  The token passed to
             PSLDU_Factor() must match the token used in some previous call to
             PSLDU_Preprocess().  Similarly, the token passed to PSLDU_Solve()
             must match the token used in some previous call to
             PSLDU_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 D, and the number of
             floating-point operations required to factor A.

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

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

TUNING
     Optimized and parallelized for the SGI R8000 platform.