---

spMatrix.h

Go to the documentation of this file.

/*  EXPORTS for sparse matrix routines. */
/*
 *  Revision and copyright information.
 *
 *  Copyright (c) 1985-2003 by Kenneth S. Kundert
 *
 *  $Date: 2003/06/29 04:19:52 $
 *  $Revision: 1.2 $
 */




#ifndef  spOKAY

/*
 *  IMPORTS
 *
 *  >>> Import descriptions:
 *  spConfig.h
 *      Macros that customize the sparse matrix routines.
 */

#include "spConfig.h"






/*
 *  ERROR KEYWORDS
 *
 *  The actual numbers used in the error codes are not sacred, they can be
 *  changed under the condition that the codes for the nonfatal errors are
 *  less than the code for spFATAL and similarly the codes for the fatal
 *  errors are greater than that for spFATAL.
 */

/* Begin error macros. */
#define  spOKAY         0  
#define  spSMALL_PIVOT  1  
#define  spZERO_DIAG    2  
#define  spSINGULAR     3  
#define  spMANGLED      4  
#define  spNO_MEMORY    5  
#define  spPANIC        6  
#define  spFATAL        2  
/*
 *  KEYWORD DEFINITIONS
 */

#define  spREAL double  
/*
 *  PARTITION TYPES
 *
 *  When factoring a previously ordered matrix using spFactor(), Sparse
 *  operates on a row-at-a-time basis.  For speed, on each step, the row
 *  being updated is copied into a full vector and the operations are
 *  performed on that vector.  This can be done one of two ways, either
 *  using direct addressing or indirect addressing.  Direct addressing
 *  is fastest when the matrix is relatively dense and indirect addressing
 *  is quite sparse.  The user can select which partitioning mode is used.
 *  The following keywords are passed to spPartition() and indicate that
 *  Sparse should use only direct addressing, only indirect addressing, or
 *  that it should choose the best mode on a row-by-row basis.  The time
 *  required to choose a partition is of the same order of the cost to factor
 *  the matrix.
 *
 *  If you plan to factor a large number of matrices with the same structure,
 *  it is best to let Sparse choose the partition.  Otherwise, you should
 *  choose the partition based on the predicted density of the matrix.
 */

/* Begin partition keywords. */

#define spDEFAULT_PARTITION     0 
#define spDIRECT_PARTITION      1 
#define spINDIRECT_PARTITION    2 
#define spAUTO_PARTITION        3 

/*
 *  MACRO FUNCTION DEFINITIONS
 */

/* Begin Macros. */
#define  spADD_REAL_ELEMENT(element,real)       *(element) += real

#define  spADD_IMAG_ELEMENT(element,imag)       *(element+1) += imag

#define  spADD_COMPLEX_ELEMENT(element,real,imag)       \
{   *(element) += real;                                 \
    *(element+1) += imag;                               \
}

#define  spADD_REAL_QUAD(template,real)         \
{   *((template).Element1) += real;             \
    *((template).Element2) += real;             \
    *((template).Element3Negated) -= real;      \
    *((template).Element4Negated) -= real;      \
}

#define  spADD_IMAG_QUAD(template,imag)         \
{   *((template).Element1+1) += imag;           \
    *((template).Element2+1) += imag;           \
    *((template).Element3Negated+1) -= imag;    \
    *((template).Element4Negated+1) -= imag;    \
}

#define  spADD_COMPLEX_QUAD(template,real,imag) \
{   *((template).Element1) += real;             \
    *((template).Element2) += real;             \
    *((template).Element3Negated) -= real;      \
    *((template).Element4Negated) -= real;      \
    *((template).Element1+1) += imag;           \
    *((template).Element2+1) += imag;           \
    *((template).Element3Negated+1) -= imag;    \
    *((template).Element4Negated+1) -= imag;    \
}







/*
 *   TYPE DEFINITION FOR EXTERNAL MATRIX ELEMENT REFERENCES
 *
 *   External type definitions for Sparse data objects.
 */

typedef spGenericPtr spMatrix;

typedef spREAL spElement;

typedef int spError;





/* TYPE DEFINITION FOR COMPONENT TEMPLATE */
/* Begin `spTemplate'. */
struct  spTemplate
{   spElement   *Element1;
    spElement   *Element2;
    spElement   *Element3Negated;
    spElement   *Element4Negated;
};





/*
 *   FUNCTION TYPE DEFINITIONS
 *
 *   The type of every user accessible function is declared here.
 */

/* Begin function declarations. */

spcEXTERN  void       spClear( spMatrix );
spcEXTERN  spREAL     spCondition( spMatrix, spREAL, int* );
spcEXTERN  spMatrix   spCreate( int, int, spError* );
spcEXTERN  void       spDeleteRowAndCol( spMatrix, int, int );
spcEXTERN  void       spDestroy( spMatrix );
spcEXTERN  int        spElementCount( spMatrix );
spcEXTERN  spError    spErrorState( spMatrix );
#ifdef EOF
    spcEXTERN void    spErrorMessage( spMatrix, FILE*, char* );
#else
#   define spErrorMessage(a,b,c) spcFUNC_NEEDS_FILE(_spErrorMessage,stdio)
#endif


spcEXTERN  spError    spFactor( spMatrix );
spcEXTERN  int        spFileMatrix( spMatrix, char*, char*, int, int, int );
spcEXTERN  int        spFileStats( spMatrix, char*, char* );
spcEXTERN  int        spFillinCount( spMatrix );
spcEXTERN  spElement *spFindElement( spMatrix, int, int );
spcEXTERN  spError    spGetAdmittance( spMatrix, int, int,
                                struct spTemplate* );
spcEXTERN  spElement *spGetElement( spMatrix, int, int );
spcEXTERN  spGenericPtr spGetInitInfo( spElement* );
spcEXTERN  spError    spGetOnes( spMatrix, int, int, int,
                                struct spTemplate* );
spcEXTERN  spError    spGetQuad( spMatrix, int, int, int, int,
                                struct spTemplate* );
spcEXTERN  int        spGetSize( spMatrix, int );
spcEXTERN  int        spInitialize( spMatrix, int (*pInit)(spElement *, spGenericPtr, int, int) );
spcEXTERN  void       spInstallInitInfo( spElement*, spGenericPtr );
spcEXTERN  spREAL     spLargestElement( spMatrix );
spcEXTERN  void       spMNA_Preorder( spMatrix );
spcEXTERN  spREAL     spNorm( spMatrix );
spcEXTERN  spError    spOrderAndFactor( spMatrix, spREAL[], spREAL,
                                spREAL, int );
spcEXTERN  void       spPartition( spMatrix, int );
spcEXTERN  void       spPrint( spMatrix, int, int, int );
spcEXTERN  spREAL     spPseudoCondition( spMatrix );
spcEXTERN  spREAL     spRoundoff( spMatrix, spREAL );
spcEXTERN  void       spScale( spMatrix, spREAL[], spREAL[] );
spcEXTERN  void       spSetComplex( spMatrix );
spcEXTERN  void       spSetReal( spMatrix );
spcEXTERN  void       spStripFills( spMatrix );
spcEXTERN  void       spWhereSingular( spMatrix, int*, int* );

/* Functions with argument lists that are dependent on options. */

#if spCOMPLEX
spcEXTERN  void       spDeterminant( spMatrix, int*, spREAL*, spREAL* );
#else /* NOT spCOMPLEX */
spcEXTERN  void       spDeterminant( spMatrix, int*, spREAL* );
#endif /* NOT spCOMPLEX */
#if spCOMPLEX && spSEPARATED_COMPLEX_VECTORS
spcEXTERN  int        spFileVector( spMatrix, char* ,
                                spREAL[], spREAL[]);
spcEXTERN  void       spMultiply( spMatrix, spREAL[], spREAL[],
                                spREAL[], spREAL[] );
spcEXTERN  void       spMultTransposed( spMatrix, spREAL[], spREAL[],
                                spREAL[], spREAL[] );
spcEXTERN  void       spSolve( spMatrix, spREAL[], spREAL[], spREAL[],
                                spREAL[] );
spcEXTERN  void       spSolveTransposed( spMatrix, spREAL[], spREAL[],
                                spREAL[], spREAL[] );
#else /* NOT  (spCOMPLEX && spSEPARATED_COMPLEX_VECTORS) */
spcEXTERN  int        spFileVector( spMatrix, char* , spREAL[] );
spcEXTERN  void       spMultiply( spMatrix, spREAL[], spREAL[] );
spcEXTERN  void       spMultTransposed( spMatrix,
                                spREAL[], spREAL[] );
spcEXTERN  void       spSolve( spMatrix, spREAL[], spREAL[] );
spcEXTERN  void       spSolveTransposed( spMatrix,
                                spREAL[], spREAL[] );
#endif /* NOT  (spCOMPLEX && spSEPARATED_COMPLEX_VECTORS) */
#endif  /* spOKAY */

---