298 lines
11 KiB
C
298 lines
11 KiB
C
/*
|
||
* EXPORTS for sparse matrix routines with SPICE3.
|
||
*
|
||
* 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.
|
||
*
|
||
* This file is a modified version of spMatrix.h that is used when
|
||
* interfacing to Spice3.
|
||
*/
|
||
|
||
|
||
/*
|
||
* Revision and copyright information.
|
||
*
|
||
* Copyright (c) 1985,86,87,88,89,90
|
||
* 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.
|
||
*/
|
||
|
||
|
||
|
||
|
||
#ifndef spOKAY
|
||
|
||
|
||
|
||
|
||
|
||
/*
|
||
* 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
|
||
* 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.
|
||
*/
|
||
|
||
#include "ngspice/sperror.h" /* Spice error definitions. */
|
||
|
||
/* Begin error macros. */
|
||
#define spOKAY OK
|
||
#define spSMALL_PIVOT OK
|
||
#define spZERO_DIAG E_SINGULAR
|
||
#define spSINGULAR E_SINGULAR
|
||
#define spNO_MEMORY E_NOMEM
|
||
#define spPANIC E_BADMATRIX
|
||
|
||
#define spFATAL E_BADMATRIX
|
||
|
||
|
||
|
||
|
||
|
||
|
||
/*
|
||
* 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;
|
||
};
|
||
|
||
|
||
typedef struct MatrixFrame *MatrixPtr;
|
||
|
||
|
||
/*
|
||
* FUNCTION TYPE DEFINITIONS
|
||
*
|
||
* The type of every user accessible function is declared here.
|
||
*/
|
||
|
||
/* Begin function declarations. */
|
||
|
||
extern void spClear( MatrixPtr );
|
||
extern spREAL spCondition( MatrixPtr, spREAL, int* );
|
||
extern MatrixPtr spCreate( int, int, int* );
|
||
extern void spDeleteRowAndCol( MatrixPtr, int, int );
|
||
extern void spDestroy( MatrixPtr);
|
||
extern int spElementCount( MatrixPtr );
|
||
extern int spError( MatrixPtr );
|
||
extern int spFactor( MatrixPtr );
|
||
extern int spFileMatrix( MatrixPtr, char *, char *, int, int, int );
|
||
extern int spFileStats( MatrixPtr, char *, char * );
|
||
extern int spFillinCount( MatrixPtr );
|
||
extern int spGetAdmittance( MatrixPtr, int, int, struct spTemplate* );
|
||
extern spREAL *spFindElement(MatrixPtr Matrix, int Row, int Col );
|
||
extern spREAL *spGetElement(MatrixPtr, int, int );
|
||
extern void *spGetInitInfo( spREAL* );
|
||
extern int spGetOnes( MatrixPtr, int, int, int, struct spTemplate* );
|
||
extern int spGetQuad( MatrixPtr, int, int, int, int, struct spTemplate* );
|
||
extern int spGetSize( MatrixPtr, int );
|
||
extern int spInitialize(MatrixPtr, int (*pInit)(spREAL*, void *InitInfo, int, int Col));
|
||
extern void spInstallInitInfo( spREAL*, void * );
|
||
extern spREAL spLargestElement( MatrixPtr );
|
||
extern void spMNA_Preorder( MatrixPtr );
|
||
extern spREAL spNorm( MatrixPtr );
|
||
extern int spOrderAndFactor(MatrixPtr, spREAL*, spREAL, spREAL, int );
|
||
extern int spOriginalCount( MatrixPtr);
|
||
extern void spPartition( MatrixPtr, int );
|
||
extern void spPrint(MatrixPtr, int, int, int );
|
||
extern spREAL spPseudoCondition( MatrixPtr );
|
||
extern spREAL spRoundoff( MatrixPtr, spREAL );
|
||
extern void spScale( MatrixPtr, spREAL*, spREAL* );
|
||
extern void spSetComplex( MatrixPtr );
|
||
extern void spSetReal( MatrixPtr );
|
||
extern void spStripFills( MatrixPtr );
|
||
extern void spWhereSingular(MatrixPtr, int*, int* );
|
||
extern void spConstMult(MatrixPtr, double);
|
||
|
||
/* Functions with argument lists that are dependent on options. */
|
||
|
||
extern void spDeterminant ( MatrixPtr, int*, spREAL*, spREAL* );
|
||
extern int spFileVector( MatrixPtr, char * , spREAL*, spREAL*);
|
||
extern void spMultiply( MatrixPtr, spREAL*, spREAL*, spREAL*, spREAL* );
|
||
extern void spMultTransposed(MatrixPtr,spREAL*,spREAL*,spREAL*,spREAL*);
|
||
extern void spSolve( MatrixPtr, spREAL*, spREAL*, spREAL*, spREAL* );
|
||
extern void spSolveTransposed(MatrixPtr,spREAL*,spREAL*,spREAL*,spREAL*);
|
||
|
||
#endif /* spOKAY */
|