/*
* EXPORTS for sparse matrix routines.
*
* Author: Advising professor:
* Kenneth S. Kundert Alberto Sangiovanni-Vincentelli
* UC Berkeley
*
* This file contains definitions that are useful to the calling
* program. In particular, this file contains error keyword
* definitions, some macro functions that are used to quickly enter
* data into the matrix and the type definition of a data structure
* that acts as a template for entering admittances into the matrix.
* Also included is the type definitions for the various functions
* available to the user.
*/
/*
* Revision and copyright information.
*
* Copyright (c) 1985,86,87,88
* by Kenneth S. Kundert and the University of California.
*
* Permission to use, copy, modify, and distribute this software and
* its documentation for any purpose and without fee is hereby granted,
* provided that the copyright notices appear in all copies and
* supporting documentation and that the authors and the University of
* California are properly credited. The authors and the University of
* California make no representations as to the suitability of this
* software for any purpose. It is provided `as is', without express
* or implied warranty.
*
* $Date: 88/06/18 11:14:02 $
* $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.
*
* >>> Error descriptions:
* spOKAY
* No error has occurred.
* spSMALL_PIVOT
* When reordering the matrix, no element was found which satisfies the
* absolute threshold criteria. The largest element in the matrix was
* chosen as pivot. Non-fatal.
* spZERO_DIAG
* Fatal error. A zero was encountered on the diagonal the matrix. This
* does not necessarily imply that the matrix is singular. When this
* error occurs, the matrix should be reconstructed and factored using
* spOrderAndFactor().
* spSINGULAR
* Fatal error. Matrix is singular, so no unique solution exists.
* spNO_MEMORY
* Fatal error. Indicates that not enough memory is available to handle
* the matrix.
* spPANIC
* Fatal error indicating that the routines are not prepared to
* handle the matrix that has been requested. This may occur when
* the matrix is specified to be real and the routines are not
* compiled for real matrices, or when the matrix is specified to
* be complex and the routines are not compiled to handle complex
* matrices.
* spFATAL
* Not an error flag, but rather the dividing line between fatal errors
* and warnings.
*/
/* Begin error macros. */
#define spOKAY 0
#define spSMALL_PIVOT 1
#define spZERO_DIAG 2
#define spSINGULAR 3
#define spNO_MEMORY 4
#define spPANIC 5
#define spFATAL 2
/*
* KEYWORD DEFINITIONS
*
* Here we define what precision arithmetic Sparse will use. Double
* precision is suggested as being most appropriate for circuit
* simulation and for C. However, it is possible to change spREAL
* to a float for single precision arithmetic. Note that in C, single
* precision arithmetic is often slower than double precision. Sparse
* internally refers to spREALs as RealNumbers.
*
* Some C compilers, notably the old VMS compiler, do not handle the keyword
* "void" correctly. If this is true for your compiler, remove the
* comment delimiters from the redefinition of void to int below.
*/
#define spREAL double
/* #define void int */
/*
* 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
*
* >>> Macro descriptions:
* spADD_REAL_ELEMENT
* Macro function that adds data to a real element in the matrix by a
* pointer.
* spADD_IMAG_ELEMENT
* Macro function that adds data to a imaginary element in the matrix by
* a pointer.
* spADD_COMPLEX_ELEMENT
* Macro function that adds data to a complex element in the matrix by a
* pointer.
* spADD_REAL_QUAD
* Macro function that adds data to each of the four real matrix elements
* specified by the given template.
* spADD_IMAG_QUAD
* Macro function that adds data to each of the four imaginary matrix
* elements specified by the given template.
* spADD_COMPLEX_QUAD
* Macro function that adds data to each of the four complex matrix
* elements specified by the given template.
*/
/* 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 COMPONENT TEMPLATE
*
* This data structure is used to hold pointers to four related elements in
* matrix. It is used in conjunction with the routines
* spGetAdmittance
* spGetQuad
* spGetOnes
* These routines stuff the structure which is later used by the spADD_QUAD
* macro functions above. It is also possible for the user to collect four
* pointers returned by spGetElement and stuff them into the template.
* The spADD_QUAD routines stuff data into the matrix in locations specified
* by Element1 and Element2 without changing the data. The data is negated
* before being placed in Element3 and Element4.
*/
/* Begin `spTemplate'. */
struct spTemplate
{ spREAL *Element1 ;
spREAL *Element2 ;
spREAL *Element3Negated;
spREAL *Element4Negated;
};
/*
* FUNCTION TYPE DEFINITIONS
*
* The type of every user accessible function is declared here.
*/
/* Begin function declarations. */
#ifdef __STDC__
/* For compilers that understand function prototypes. */
extern void spClear( char* );
extern spREAL spCondition( char*, spREAL, int* );
extern char *spCreate( int, int, int* );
extern void spDeleteRowAndCol( char*, int, int );
extern void spDestroy( char* );
extern int spElementCount( char* );
extern int spError( char* );
extern int spFactor( char* );
extern int spFileMatrix( char*, char*, char*, int, int, int );
extern int spFileStats( char*, char*, char* );
extern int spFillinCount( char* );
extern int spGetAdmittance( char*, int, int, struct spTemplate* );
extern spREAL *spGetElement( char*, int, int );
extern char *spGetInitInfo( spREAL* );
extern int spGetOnes( char*, int, int, int, struct spTemplate* );
extern int spGetQuad( char*, int, int, int, int, struct spTemplate* );
extern int spGetSize( char*, int );
extern int spInitialize( char*, int (*)() );
extern void spInstallInitInfo( spREAL*, char* );
extern spREAL spLargestElement( char* );
extern void spMNA_Preorder( char* );
extern spREAL spNorm( char* );
extern int spOrderAndFactor( char*, spREAL[], spREAL, spREAL, int );
extern void spPartition( char*, int );
extern void spPrint( char*, int, int, int );
extern spREAL spPseudoCondition( char* );
extern spREAL spRoundoff( char*, spREAL );
extern void spScale( char*, spREAL[], spREAL[] );
extern void spSetComplex( char* );
extern void spSetReal( char* );
extern void spStripFills( char* );
extern void spWhereSingular( char*, int*, int* );
/* Functions with argument lists that are dependent on options. */
#if spCOMPLEX
extern void spDeterminant ( char*, int*, spREAL*, spREAL* );
#else /* NOT spCOMPLEX */
extern void spDeterminant ( char*, int*, spREAL* );
#endif /* NOT spCOMPLEX */
#if spCOMPLEX && spSEPARATED_COMPLEX_VECTORS
extern int spFileVector( char*, char* , spREAL[], spREAL[]);
extern void spMultiply( char*, spREAL[], spREAL[], spREAL[], spREAL[] );
extern void spMultTransposed(char*,spREAL[],spREAL[],spREAL[],spREAL[]);
extern void spSolve( char*, spREAL[], spREAL[], spREAL[], spREAL[] );
extern void spSolveTransposed(char*,spREAL[],spREAL[],spREAL[],spREAL[]);
#else /* NOT (spCOMPLEX && spSEPARATED_COMPLEX_VECTORS) */
extern int spFileVector( char*, char* , spREAL[] );
extern void spMultiply( char*, spREAL[], spREAL[] );
extern void spMultTransposed( char*, spREAL[], spREAL[] );
extern void spSolve( char*, spREAL[], spREAL[] );
extern void spSolveTransposed( char*, spREAL[], spREAL[] );
#endif /* NOT (spCOMPLEX && spSEPARATED_COMPLEX_VECTORS) */
#else /* NOT defined(__STDC__) */
/* For compilers that do not understand function prototypes. */
extern void spClear();
extern spREAL spCondition();
extern char *spCreate();
extern void spDeleteRowAndCol();
extern void spDestroy();
extern void spDeterminant ();
extern int spElementCount();
extern int spError();
extern int spFactor();
extern int spFileMatrix();
extern int spFileStats();
extern int spFileVector();
extern int spFillinCount();
extern int spGetAdmittance();
extern spREAL *spGetElement();
extern char *spGetInitInfo();
extern int spGetOnes();
extern int spGetQuad();
extern int spGetSize();
extern int spInitialize();
extern void spInstallInitInfo();
extern spREAL spLargestElement();
extern void spMNA_Preorder();
extern void spMultiply();
extern void spMultTransposed();
extern spREAL spNorm();
extern int spOrderAndFactor();
extern void spPartition();
extern void spPrint();
extern spREAL spPseudoCondition();
extern spREAL spRoundoff();
extern void spScale();
extern void spSetComplex();
extern void spSetReal();
extern void spSolve();
extern void spSolveTransposed();
extern void spStripFills();
extern void spWhereSingular();
#endif /* defined(__STDC__) */
#endif /* spOKAY */