                       readme for sparse directory
/*D
   SpIntro -  This is the introductory manual page for the sparse library. 

Overview:
The Sp* package is a set of routines for manipulating sparse
matrices. The actual storage format of the sparse matrices is implementation 
dependent, the application program should at no time manipulate the 
sparse matrix data structures directly, it should only access
them through the Sp* routines.

  Brief listing of the routines and data structures.

$    SpMat      *mat -  a pointer to a sparse matrix
$    SpMatSplit *factor - a pointer to a sparse matrix in LU factored form

   Routines related to creating and destroying matrices:

    SpCreate(), SpDestroy(), SpCreateSplit(), SpDestroySplit(), SpCopy()

    Routines related to inserting/changing elements in matrices.
    
    SpAddValue(), SpSetValue(), SpAddInRow(), SpSetInRow(), ...

    Routines related to factorization
 
    SpQuickFactor(), SpComputeFill(), SpComputeILUFill(), SpFactor(),
    SpOrder(), ...

  Others:

   SpSolve(), SpSolveTranspose(), SpSolveAdd(), SpPrint(), SpScaleSym(),
   SpNz(), SpSubmatrix(), ....

D*/

/*D
    SpDataStructures - Extending SParse with user-defined datastructures

    Overview:

    Users may install their own datastructures and routines for sparse
    matrix operations.  This is done by defining functions to carry
    out some key operations.

    Method:
    The easiest way to define a new datastructure is to take an existing
    one and modify it.  The file sparse/row/alloc.c contains the most
    complete example (the row-oriented format implemented there is the
    default sparse matrix format).  Basically, the following routines
    must be provided
$   Sp<name>Create - Create a matrix with the desired data structure. 
    Also sets the routines that will be used to perform the basic operations.
$   Sp<name>Destroy - Destroy a matrix, recovering any allocated space.

    In addition, the three routines
$   Sp<name>ScatterToRow
$   Sp<name>GatherFromRow
$   Sp<name>GatherAddFromRow
    are needed to interface with most of the sparse matrix support routines,
    including routines to display a matrix and manipulate it.

    For greater efficiency, some operations may be defined with routines
    that are customized for the particular datastructure.  These include
$   Sp<name>Mult     - compute M*v
$   Sp<name>MultAdd  - compute w + M*v
$   Sp<name>MultTrans - compute M' * v
$   Sp<name>ComputeFill - compute the fill for factorization of a matrix 
	         (symbolic factorization)
$   Sp<name>ComputeFactor - compute the actual factor (numeric factorization)
$   Sp<name>Solve - solve a linear system
$   Sp<name>SolveTrans - solve a linear system with the transpose

    
    
D*/
