spdoc.txt

Delphi Pascal 数据挖掘领域算法包 稀疏线性系统分析包

                       June 23, 1988





                           - 15 -


4:  SPARSE ROUTINES

This section contains a complete list  of  the  Sparse  routines  that  are
available  to  the  user.  Each routine is described as to its function and
how to use it.  The routines are listed in alphabetic order.





4.1:  spClear()

Sets every element in the matrix  to  zero.   The  Sparse  error  state  is
cleared to spOKAY in this routine.

void spClear( Matrix )

o Argument:

     Matrix  input  (char *)
          Pointer to matrix that is to be cleared.





































                       June 23, 1988





                           - 16 -





4.2:  spCondition()

spCondition() computes an estimate of the condition number using  a  varia-
tion  on  the LINPACK condition number estimation algorithm.  This quantity
is an measure of ill-conditioning in the matrix.  To  avoid  problems  with
overflow,  the  reciprocal  of  the  condition number is returned.  If this
number is small, and if the matrix is scaled such that uncertainties in the
RHS  and  the  matrix  entries  are  equilibrated,  then the matrix is ill-
conditioned.  If the this number is near one, the  matrix  is  well  condi-
tioned.  This routine must only be used after a matrix has been factored by
spOrderAndFactor() or spFactor() and before it is cleared by  spClear()  or
spInitialize().

Unlike the LINPACK condition number estimator, this routines returns the  L
infinity  condition  number.  This is an artifact of Sparse placing ones on
the diagonal of the upper triangular matrix rather than  the  lower.   This
difference should be of no importance.

spREAL spCondition( Matrix, NormOfMatrix, Error )

o Returns:
     An estimate of the L infinity condition number of the matrix.

o Arguments:

     Matrix  input  (char *)
          The matrix for which the condition number is desired.

     NormOfMatrix  input  (spREAL)
          The L-infinity norm of  the  unfactored  matrix  as  computed  by
          spNorm().

     Error  output  (int *)
          Used to return the error code.

o Possible errors:
     spSINGULAR
     spNO MEMORY
     Error is not cleared in this routine.

o Compiler options that must be set for this routine to exist:
     CONDITION













                       June 23, 1988





                           - 17 -





4.3:  spCreate()

Allocates and initializes the data structures  associated  with  a  matrix.
This  routine  is  necessarily the first routine run for any particular ma-
trix.

char *spCreate( Size, Complex, Error )

o Returned:
     A pointer to the matrix is returned cast into the form of a pointer to
     a character.  This pointer is then passed and used by the other matrix
     routines to refer to a particular matrix.  If  an  error  occurs,  the
     NULL pointer is returned.

o Arguments:

     Size  input  (int)
          Size of matrix.  When the compiler option  EXPANDABLE  is  turned
          on,  Size  is  used  as  a lower bound on the size of the matrix.
          Size must not be negative.

     Complex  input  (int)
          Type of matrix.  If Complex is 0 then the matrix is real,  other-
          wise  the  matrix will be complex.  Note that if the routines are
          not set up to handle the type of matrix requested, then a spPANIC
          error will occur.

     Error  output  (int *)
          Returns error flag, needed because function  spError()  will  not
          work correctly if spCreate() returns NULL.

o Possible errors:
     spNO MEMORY
     spPANIC





















                       June 23, 1988





                           - 18 -





4.4:  spDeleteRowAndCol()

This function is used to delete a row and column from the matrix.  The ele-
ments  removed from the matrix are never used again and are not freed until
the matrix is destroyed and so the pointers to these elements remain valid.

void spDeleteRowAndCol( Matrix, Row, Col )

o Arguments:

     Matrix  input  (char *)
          The matrix from which the row and column are to be deleted.

     Row  input  (int)
          The row to be deleted.

     Col  input  (int)
          The column to be deleted.

o Compiler options that must be set for this routine to exist:
     DELETE
     TRANSLATE





4.5:  spDestroy()

Destroys a matrix frame and reclaims the memory.

void spDestroy( Matrix )

o Argument:

     Matrix  input  (char *)
          Pointer to the matrix frame which is to be removed from memory.



















                       June 23, 1988





                           - 19 -





4.6:  spDeterminant()

This routine in capable of calculating the determinant of the  matrix  once
the  LU  factorization  has  been  performed.  Hence, only use this routine
after spFactor() or spOrderAndFactor() and before spClear()  or  spInitial-
ize().   Note  that  the determinants of matrices can be very large or very
small.  On large matrices, the determinant can be  far  larger  or  smaller
than  can  be  represented by a floating point number.  For this reason the
mantissa and exponent of the determinant are returned separately.

void spDeterminant( Matrix, Exponent, Determinant )
void spDeterminant( Matrix, Exponent, Determinant, iDeterminant )

o Arguments:

     Matrix  input  (char *)
          The matrix for which the determinant is desired.

     Exponent  output  (int *)
          The logarithm base 10 of the scale factor  for  the  determinant.
          To  find  the actual determinant, Exponent should be added to the
          exponent of Determinant and iDeterminant.

     Determinant  output  (spREAL *)
          The real portion of the determinant.  If the matrix is real, then
          the  magnitude  of  this  number  is scaled to be greater than or
          equal to 1.0 and less than 10.0. Otherwise the magnitude  of  the
          complex determinant will be scaled such.

     iDeterminant  output  (spREAL *)
          The imaginary portion of the determinant.   When  the  matrix  is
          real this pointer need not be supplied; nothing will be returned.

o Compiler options that must be set for this routine to exist:
     DETERMINANT

o Bugs:
     The sign of determinant may be in error if rows and columns have  been
     added or deleted from matrix.
















                       June 23, 1988





                           - 20 -





4.7:  spElementCount()

Returns the total number of structurally nonzero elements in the matrix.

int spElementCount( Matrix )

o Returns:
     The total number of structurally nonzero elements.

o Argument:

     Matrix  input  (char *)
          Pointer to the matrix.





4.8:  spError()

This function returns the error status of a matrix.

int MatrixError( Matrix )

o Returned:
     The error status of the given matrix.

o Argument:

     Matrix  input  (char *)
          The matrix for which the error status is desired.

o Possible errors:
     spOKAY
     spILL CONDITIONED
     spZERO PIVOT
     spSINGULAR
     spNO MEMORY
     spPANIC
     Error is not cleared in this routine.
















                       June 23, 1988





                           - 21 -





4.9:  spFactor()

This routine factors the matrix into LU form and is the  companion  routine
to spOrderAndFactor().  Unlike spOrderAndFactor(), spFactor() cannot change
the ordering.  Its utility is that it is considerably faster.  The standard
way  to  use  these two routines is to first use spOrderAndFactor() for the
initial factorization.  For subsequent factorizations, spFactor() is  used.
If  spFactor()  is called for the initial factorization of the matrix, then
it will automatically call spOrderAndFactor() with the default  thresholds.
If  spFactor()  finds  a  zero on the diagonal, it will terminate early and
complain.  This does not necessarily mean that matrix is singular.   Before
a  matrix  is  condemned  as being singular, it should be run through spOr-
derAndFactor(), which can reorder the matrix and remove the offensive  zero
from the diagonal.

int spFactor( Matrix )

o Returned:
     The error code is returned.  Possible errors are listed below.

o Argument:

     Matrix  input  (char *)
          Pointer to matrix to be factored.

o Possible errors:
     spZERO PIVOT
     spNO MEMORY
     spSINGULAR
     spILL CONDITIONED