spdoc.txt

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

                       June 23, 1988





                           - 22 -




4.10:  spFileMatrix()

Writes matrix to file in format suitable to be read back in by  the  matrix
test  program.   Normally, spFileMatrix() should be executed before the ma-
trix is factored, otherwise matrix is output in factored form.  If the  ma-
trix  is  sent  to  a file without the header or data, it will be in a form
that is easily plotted by typical plotting programs.

int spFileMatrix( Matrix, File, Label, Reordered, Data, Header )

o Returns:
     One is returned if routine was successful, otherwise zero is returned.
     The  calling  function  can query errno (the system global error vari-
     able) as to the reason why this routine failed.

o Arguments:

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

     File  input  (char *)
          Name of output file.

     Label  input  (char *)
          String that is transferred to file and used as a  label.   String
          should fit on one line and have no embedded line feeds.

     Reordered  input  (int)
          Specifies whether the matrix should be output using the  original
          order or in reordered form.  Zero specifies original order.

     Data  input  (int)
          Indicates that the element values should be output along with the
          indices  for each element.  Element values are not output if Data
          is zero.  This parameter must be nonzero if matrix is to be  read
          by the Sparse test program.

     Header  input  (int)
          If nonzero a header is output that includes that size of the  ma-
          trix  and the label.  This parameter must be nonzero if matrix is
          to be read by the Sparse test program.

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











                       June 23, 1988





                           - 23 -





4.11:  spFileStats()

Appends useful information concerning the matrix to the end of a file.   If
file  does  not  exist, it is created.  This file should not be the same as
one used to hold the matrix or vector if the matrix is to be  read  by  the
Sparse test program.  Should be executed after the matrix is factored.

int spFileStats( Matrix, File, Label )

o Returns:
     One is returned if routine was successful, otherwise zero is returned.
     The  calling  function  can query errno (the system global error vari-
     able) as to the reason why this routine failed.

o Arguments:

     Matrix  input  (char *)
          Pointer to matrix for which statistics are desired.

     File  input  (char *)
          Name of output file.

     Label  input  (char *)
          String that is transferred to file and is used as a label. String
          should fit on one line and have no embedded line feeds.

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



























                       June 23, 1988





                           - 24 -





4.12:  spFileVector()

Appends the RHS vector to the end of a file in a format suitable to be read
back in by the matrix test program.  If file does not exist, it is created.
To be compatible with the test program, if spFileVector() is run,  it  must
be run after spFileMatrix() and use the same file.

int spFileVector( Matrix, File, RHS )
int spFileVector( Matrix, File, RHS, iRHS )

o Returns:
     One is returned if routine was successful, otherwise zero is returned.
     The  calling  function  can query errno (the system global error vari-
     able) as to the reason why this routine failed.

o Arguments:

     Matrix  input  (char *)
          Pointer to matrix that corresponds to the vector to be output.

     File  input  (char *)
          Name of file where output is to be written.

     RHS  input  (spREAL[])
          The right-hand side vector.  RHS contains only the  real  portion
          of  the  right-hand  side  vector  if  the  matrix is complex and
          spSEPARATED COMPLEX VECTORS is set true.

     iRHS  input  (spREAL[])
          Right-hand side vector, imaginary portion.  Not necessary if  ma-
          trix is real or if spSEPARATED COMPLEX VECTORS is set false.

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





















                       June 23, 1988





                           - 25 -





4.13:  spFillinCount()

Returns the total number of fill-ins in the matrix.  A fill-in is  an  ele-
ment  that  is originally structurally zero, but becomes nonzero during the
factorization.

int spFillinCount( Matrix )

o Returns:
     The total number of fill-ins.

o Argument:

     Matrix  input  (char *)
          Pointer to the matrix.








































                       June 23, 1988





                           - 26 -





4.14:  spGetAdmittance()

Performs same function as spGetElement() except rather  than  one  element,
all four matrix elements for a floating admittance are reserved.  This rou-
tine also works if the admittance is grounded (zero is  the  ground  node).
This function returns a group of pointers to the four elements through Tem-
plate, which is an output.  They are used by  the  spADD QUAD()  macros  to
directly  access  matrix  elements  during  subsequent loads of the matrix.
spGetAdmittance()  arranges  the  pointers  in   Template   so   that   the
spADD QUAD()  routines  add the admittance to the elements at [Node1,Node1]
and  [Node2,Node2]  and  subtract  the  admittance  from  the  elements  at
[Node1,Node2]  and  [Node2,Node1].  This  routine is only to be used before
spMNA Preorder(), spFactor() or spOrderAndFactor() unless the compiler flag
TRANSLATE is enabled.

int spGetAdmittance( Matrix, Node1, Node2, Template )

o Returned:
     The error  code  is  returned.   Possible  errors  are  listed  below.
     spGetAdmittance() does not clear the error state, so it is possible to
     ignore the return code of each spGetAdmittance() call, and  check  for
     errors after constructing the whole matrix by calling spError().

o Arguments:

     Matrix  input  (char *)
          Pointer to the matrix that admittance is to be installed.

     Node1  input  (int)
          One node number for the admittance.  Node1 must be in  the  range
          [0..Size]  unless  either  the  TRANSLATE  or EXPANDABLE compiler
          flags are set true.  In either case Node1 must not be negative.

     Node2  input  (int)
          Other node number for the admittance.  Node2 must be in the range
          [0..Size]  unless  either  the  TRANSLATE  or EXPANDABLE compiler
          flags are set true.  In either case Node2 must not be negative.

     Template  output  (struct spTemplate *)
          Collection of pointers to four elements that are  later  used  to
          directly  address  elements.  User must supply the template, this
          routine will fill it.

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

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






                       June 23, 1988





                           - 27 -





4.15:  spGetElement()

Reserves an element at [Row,Col] and returns a pointer to it.   If  element
is  not found then it is created and spliced into matrix.  A pointer to the
real portion of the element is returned.  This pointer is later used by the
spADD ELEMENT()  macros  to  directly  access the element.  This routine is
only to be used before spMNA Preorder(), spFactor()  or  spOrderAndFactor()
unless the compiler option TRANSLATE is set true.

spREAL *spGetElement( Matrix, Row, Col )

o Returned:
     Returns a pointer to the  element.   This  pointer  is  then  used  to
     directly access the element during successive builds.  Returns NULL if
     insufficient memory is available.  spGetElement() does not  clear  the
     error  state,  so  it  is  possible  to ignore the return code of each
     spGetElement() call, and check for errors after constructing the whole
     matrix by calling spError().

o Arguments:

     Matrix  input  (char *)
          Pointer to the matrix that the element is to be added to.

     Row  input  (int)
          Row index for element. Row must be in the range [0..Size]  unless
          either  the  TRANSLATE or EXPANDABLE compiler flags are set true.
          In either case Row must not be negative though it  may  be  zero.
          If  zero  then the element is not entered into the matrix, but is
          otherwise treated normally.

     Col  input  (int)
          Column index for element. Col must be in the range [0..Size]  un-
          less  either  the  TRANSLATE or EXPANDABLE compiler flags are set
          true.  In either case Col must not be negative though it  may  be
          zero.   If  zero then the element is not entered into the matrix,
          but is otherwise treated normally.

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














                       June 23, 1988





                           - 28 -





4.16:  spGetInitInfo()

With the INITIALIZE compiler option enabled Sparse allows the user to  keep
initialization  information  with each structurally nonzero matrix element.
Each element has a pointer (referred to as pInitInfo) that is set and  used
by  the user.  This routine returns pInitInfo from a particular matrix ele-
ment.

char *spGetInitInfo( pElement )

o Returned:
     The user installed pointer pInitInfo.

o Argument:

     pElement  input  (spREAL *)
          Pointer to the element to which pInitInfo is attached.

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



































                       June 23, 1988