spdoc.txt

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

                           - 29 -




4.17:  spGetOnes()

Performs a similar function  to  spGetAdmittance()  except  that  the  four
reserved  matrix  elements  are  assumed to be structural ones generated by
components without  admittance  representations  during  a  modified  nodal
analysis.  Positive ones are placed at [Pos,Eqn] and [Eqn,Pos] and negative
ones are placed at [Neg,Eqn] and [Eqn,Neg].  This function returns a  group
of  pointers  to  the  four  elements through Template, which is an output.
They are used by the spADD QUAD() macros to add the ones  directly  to  the
matrix  elements  during  subsequent  loads of the matrix.  This routine is
only to be used before spMNA Preorder(), spFactor()  or  spOrderAndFactor()
unless the compiler flag TRANSLATE is set true.

int spGetOnes( Matrix, Pos, Neg, Eqn, Template )

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

o Arguments:

     Matrix  input  (char *)
          Pointer to the matrix that ones are to be entered in.

     Pos  input  (int)
          Number of positive node.  Must be in the range of  [0..Size]  un-
          less  either  the options EXPANDABLE or TRANSLATE are used.  Zero
          is the ground row.  In no case may Pos be less than zero.

     Neg input  (int)
          Number of negative node.  Must be in the range of  [0..Size]  un-
          less either the options EXPANDABLE or TRANSLATE are used. Zero is
          the ground row.  In no case may Neg be less than zero.

     Eqn input  (int)
          Row that contains the branch equation.  Must be in the  range  of
          [1..Size]  unless  either the options EXPANDABLE or TRANSLATE are
          used. In no case may Eqn be less than one.

     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





                           - 30 -



























































                       June 23, 1988





                           - 31 -





4.18:  spGetQuad()

Similar to spGetAdmittance(), except that  spGetAdmittance()  only  handles
2-terminal  components,  whereas  spGetQuad() handles simple 4-terminals as
well.  These 4-terminals are simply generalized 2-terminals with the option
of having the sense terminals different from the source and sink terminals.
spGetQuad() installs four  elements  into  the  matrix  and  returns  their
pointers  in  the Template structure, which is an output.  The pointers are
arranged in Template such that when passed to one of the spADD QUAD()  mac-
ros  along with an admittance, the admittance will be added to the elements
at  [Row1,Col1]  and  [Row2,Col2]  and  subtracted  from  the  elements  at
[Row1,Col2] and [Row2,Col1].  The routine works fine if any of the rows and
columns are zero.  This routine is only to be used before spMNA Preorder(),
spFactor() or spOrderAndFactor() unless TRANSLATE is set true.

int spGetQuad( Matrix, Row1, Row2, Col1, Col2, Template )

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

o Arguments:

     Matrix  input  (char *)
          Pointer to the matrix that quad is to be entered in.

     Row1  input  (int)
          First row index for the elements.  Row1  must  be  in  the  range
          [0..Size]  unless  either  the  TRANSLATE  or EXPANDABLE compiler
          flags are set true.  In either case Row1 must not be negative.

     Row2  input  (int)
          Second row index for the elements.  Row2 must  be  in  the  range
          [0..Size]  unless  either  the  TRANSLATE  or EXPANDABLE compiler
          flags are set true.  In either case Row2 must not be negative.

     Col1  input  (int)
          First column index for the elements.  Col1 must be in  the  range
          [0..Size]  unless  either  the  TRANSLATE  or EXPANDABLE compiler
          flags are set true.  In either case Col1 must not be negative.

     Col2  input  (int)
          Second column index for the elements.  Col2 must be in the  range
          [0..Size]  unless  either  the  TRANSLATE  or EXPANDABLE compiler
          flags are set true.  In either case Col2 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.



                       June 23, 1988





                           - 32 -


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





4.19:  spGetSize()

Returns the size of the matrix, either the internal or external size of the
matrix  is  returned.   The  internal size is the actual number of rows and
columns in the matrix.  The external size is equal to the  largest  row  or
column  number.  These numbers will be the same unless the TRANSLATE option
is enabled.

int spGetSize( Matrix, External )

o Returned:
     The size of the matrix.

o Arguments:

     Matrix  input  (char *)
          Pointer to the matrix for which the size is desired.

     External  input  (int)
          If External is nonzero, the external size of the  matrix  is  re-
          turned, otherwise the internal size of the matrix is returned.


























                       June 23, 1988





                           - 33 -





4.20:  spInitialize()

spInitialize() is a user customizable way to initialize the matrix.  Passed
to this routine is a function pointer.  spInitialize() sweeps through every
element in the matrix and checks the pInitInfo pointer (the  user  supplied
pointer).   If the pInitInfo is NULL, which is true unless the user changes
it (always true for fill-ins), then the element is zeroed.  Otherwise,  the
function  pointer is called and passed the pInitInfo pointer as well as the
element pointer and the external row and column numbers allowing  the  user
to set the value of each element and perhaps the right-hand side vector.

The user function (pInit()) is expected to  return  a  nonzero  integer  if
there is a fatal error and zero otherwise.  Upon encountering a nonzero re-
turn code, spInitialize() terminates and returns the error code.

The Sparse error state is cleared to spOKAY in this routine.

int spInitialize( Matrix, pInit )

o Returns:
     The error code returned by pInit.

o Arguments:

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

     pInit  input  ((*int)())
          Pointer to a function that, given a  pointer  to  an  element,  a
          pointer to the users data structure containing initialization in-
          formation for that element, and the row and column number of  the
          element, initializes it.


int pInit( pElement, pInitInfo, Row, Col )

o Returns:
     Nonzero if fatal error, zero otherwise.

o Arguments:

     pElement  input  (spREAL *)
          The pointer to the real portion of the element.  The real portion
          can  be accessed using either *pElement or pElement[0].  The ima-
          ginary portion can be  accessed  using  either  *(pElement+1)  or
          pElement[1].

     pInitInfo  input  (char *)
          The user-installed pointer to the initialization data structure.

     Row  input  (int)
          The external row number of the element.



                       June 23, 1988





                           - 34 -


     Col  input  (int)
          The external column number of the element.

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





4.21:  spInstallInitInfo()

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 installs the pointer pInitInfo into a particular
matrix element.

void spInstallInitInfo( pElement, pInitInfo )

o Arguments:

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

     pInitInfo  input  (char *)
          The pointer pInitInfo.

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




























                       June 23, 1988





                           - 35 -





4.22:  spLargestElement()

If this routine is called before the matrix is factored, it returns the ab-
solute value of the largest element in the matrix.  If called after the ma-
trix has been factored, it returns a lower bound on the absolute  value  of
the  largest element that occurred in any of the reduced submatrices during
the factorization.  The ratio of these two numbers (factored/unfactored) is
the  growth,  which  can be used to determine if the pivoting order is ade-
quate.  A large growth implies that considerable error has been made in the
factorization  and  that  it is probably a good idea to reorder the matrix.
If a large growth in encountered after using  spFactor(),  reconstruct  the
matrix and refactor using spOrderAndFactor().  If a large growth is encoun-
tered after using  spOrderAndFactor(),  refactor  using  spOrderAndFactor()
with the pivot threshold increased, say to 0.1.

spREAL spLargestElement( Matrix )

o Returns:
     If matrix is unfactored, returns the magnitude of the largest  element
     in the matrix.  If the matrix is factored, a bound on the magnitude of
     the largest element in any of the reduced submatrices is returned.

o Argument:

     Matrix  input  (char *)
          Pointer to the matrix.

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


























                       June 23, 1988





                           - 36 -





4.23:  spMNA Preorder()

This routine massages modified node admittance matrices to improve the per-
formance  of  spOrderAndFactor().  It tries to remove structural zeros from
the diagonal by exploiting the fact that the row and column associated with
a  zero  diagonal  usually  have structural ones placed symmetrically.  For
this routine to work, the structural ones must be exactly e