00001 /* 00002 * EXPORTS for sparse matrix routines. 00003 * 00004 * Author: Advising professor: 00005 * Kenneth S. Kundert Alberto Sangiovanni-Vincentelli 00006 * UC Berkeley 00007 * 00008 * This file contains definitions that are useful to the calling 00009 * program. In particular, this file contains error keyword 00010 * definitions, some macro functions that are used to quickly enter 00011 * data into the matrix and the type definition of a data structure 00012 * that acts as a template for entering admittances into the matrix. 00013 * Also included is the type definitions for the various functions 00014 * available to the user. 00015 * 00016 * Revision and copyright information. 00017 * 00018 * Copyright (c) 1985,86,87,88 00019 * by Kenneth S. Kundert and the University of California. 00020 * 00021 * Permission to use, copy, modify, and distribute this software and 00022 * its documentation for any purpose and without fee is hereby granted, 00023 * provided that the copyright notices appear in all copies and 00024 * supporting documentation and that the authors and the University of 00025 * California are properly credited. The authors and the University of 00026 * California make no representations as to the suitability of this 00027 * software for any purpose. It is provided `as is', without express 00028 * or implied warranty. 00029 * 00030 * $Date: 88/06/18 11:14:02 $ 00031 * $Revision: 1.2 $ 00032 */ 00033 #ifndef spOKAY 00034 #include "spdefs.h" 00035 #include "spconfig.h" 00036 00037 /* 00038 * ERROR KEYWORDS 00039 * 00040 * The actual numbers used in the error codes are not sacred, they can be 00041 * changed under the condition that the codes for the nonfatal errors are 00042 * less than the code for spFATAL and similarly the codes for the fatal 00043 * errors are greater than that for spFATAL. 00044 * 00045 * >>> Error descriptions: 00046 * spOKAY 00047 * No error has occurred. 00048 * spSMALL_PIVOT 00049 * When reordering the matrix, no element was found which satisfies the 00050 * absolute threshold criteria. The largest element in the matrix was 00051 * chosen as pivot. Non-fatal. 00052 * spZERO_DIAG 00053 * Fatal error. A zero was encountered on the diagonal the matrix. This 00054 * does not necessarily imply that the matrix is singular. When this 00055 * error occurs, the matrix should be reconstructed and factored using 00056 * spOrderAndFactor(). 00057 * spSINGULAR 00058 * Fatal error. Matrix is singular, so no unique solution exists. 00059 * spNO_MEMORY 00060 * Fatal error. Indicates that not enough memory is available to handle 00061 * the matrix. 00062 * spPANIC 00063 * Fatal error indicating that the routines are not prepared to 00064 * handle the matrix that has been requested. This may occur when 00065 * the matrix is specified to be real and the routines are not 00066 * compiled for real matrices, or when the matrix is specified to 00067 * be complex and the routines are not compiled to handle complex 00068 * matrices. 00069 * spFATAL 00070 * Not an error flag, but rather the dividing line between fatal errors 00071 * and warnings. 00072 */ 00073 /* Begin error macros. */ 00074 #define spOKAY 0 00075 #define spSMALL_PIVOT 1 00076 #define spZERO_DIAG 2 00077 #define spSINGULAR 3 00078 #define spNO_MEMORY 4 00079 #define spPANIC 5 00080 #define spFATAL 2 00081 /* 00082 * KEYWORD DEFINITIONS 00083 * 00084 * Here we define what precision arithmetic Sparse will use. Double 00085 * precision is suggested as being most appropriate for circuit 00086 * simulation and for C. However, it is possible to change double 00087 * to a float for single precision arithmetic. Note that in C, single 00088 * precision arithmetic is often slower than double precision. Sparse 00089 * internally refers to spREALs as RealNumbers. 00090 * 00091 * Some C compilers, notably the old VMS compiler, do not handle the keyword 00092 * "void" correctly. If this is true for your compiler, remove the 00093 * comment delimiters from the redefinition of void to int below. 00094 * 00095 * PARTITION TYPES 00096 * 00097 * When factoring a previously ordered matrix using spFactor(), Sparse 00098 * operates on a row-at-a-time basis. For speed, on each step, the row 00099 * being updated is copied into a full vector and the operations are 00100 * performed on that vector. This can be done one of two ways, either 00101 * using direct addressing or indirect addressing. Direct addressing 00102 * is fastest when the matrix is relatively dense and indirect addressing 00103 * is quite sparse. The user can select which partitioning mode is used. 00104 * The following keywords are passed to spPartition() and indicate that 00105 * Sparse should use only direct addressing, only indirect addressing, or 00106 * that it should choose the best mode on a row-by-row basis. The time 00107 * required to choose a partition is of the same order of the cost to factor 00108 * the matrix. 00109 * 00110 * If you plan to factor a large number of matrices with the same structure, 00111 * it is best to let Sparse choose the partition. Otherwise, you should 00112 * choose the partition based on the predicted density of the matrix. 00113 */ 00114 00115 /* Begin partition keywords. */ 00116 00117 #define spDEFAULT_PARTITION 0 00118 #define spDIRECT_PARTITION 1 00119 #define spINDIRECT_PARTITION 2 00120 #define spAUTO_PARTITION 3 00121 /* 00122 * MACRO FUNCTION DEFINITIONS 00123 * 00124 * >>> Macro descriptions: 00125 * spADD_REAL_ELEMENT 00126 * Macro function that adds data to a real element in the matrix by a 00127 * pointer. 00128 * spADD_IMAG_ELEMENT 00129 * Macro function that adds data to a imaginary element in the matrix by 00130 * a pointer. 00131 * spADD_COMPLEX_ELEMENT 00132 * Macro function that adds data to a complex element in the matrix by a 00133 * pointer. 00134 * spADD_REAL_QUAD 00135 * Macro function that adds data to each of the four real matrix elements 00136 * specified by the given template. 00137 * spADD_IMAG_QUAD 00138 * Macro function that adds data to each of the four imaginary matrix 00139 * elements specified by the given template. 00140 * spADD_COMPLEX_QUAD 00141 * Macro function that adds data to each of the four complex matrix 00142 * elements specified by the given template. 00143 */ 00144 00145 /* Begin Macros. */ 00146 #define spADD_REAL_QUAD(templ, real) { templ->Element1->Real += real; templ->Element2->Real += real; \ 00147 templ->Element3Negated->Real -= real; templ->Element4Negated->Real -= real; } 00148 00149 /* 00150 * TYPE DEFINITION FOR COMPONENT TEMPLATE 00151 * 00152 * This data structure is used to hold pointers to four related elements in 00153 * matrix. It is used in conjunction with the routines 00154 * spGetAdmittance 00155 * spGetQuad 00156 * spGetOnes 00157 * These routines stuff the structure which is later used by the spADD_QUAD 00158 * macro functions above. It is also possible for the user to collect four 00159 * pointers returned by spGetElement and stuff them into the template. 00160 * The spADD_QUAD routines stuff data into the matrix in locations specified 00161 * by Element1 and Element2 without changing the data. The data is negated 00162 * before being placed in Element3 and Element4. 00163 */ 00164 struct spTemplate { ElementPtr Element1, Element2, Element3Negated, Element4Negated; }; 00165 00166 extern void spClear(MatrixPtr Matrix); 00167 extern double spCondition(MatrixPtr Matrix, double, int* ); 00168 extern MatrixPtr spCreate(int, int*); 00169 extern void spDeleteRowAndCol(MatrixPtr Matrix, int, int ); 00170 extern void spDestroy(MatrixPtr Matrix); 00171 extern int spElementCount(MatrixPtr Matrix); 00172 extern int spError(MatrixPtr Matrix); 00173 extern int spFactor(MatrixPtr Matrix); 00174 extern int spFileMatrix(MatrixPtr Matrix, char*, char*, int, int, int ); 00175 extern int spFileStats(MatrixPtr Matrix, char*, char* ); 00176 extern int spFillinCount(MatrixPtr Matrix); 00177 extern int spGetAdmittance(MatrixPtr Matrix, int, int, struct spTemplate* ); 00178 extern ElementPtr spGetElement(MatrixPtr Matrix, int, int ); 00179 extern double *spGetInitInfo(ElementPtr); 00180 extern int spGetOnes(MatrixPtr Matrix, int, int, int, struct spTemplate* ); 00181 extern int spGetQuad(MatrixPtr Matrix, int, int, int, int, struct spTemplate* ); 00182 extern int spGetSize(MatrixPtr Matrix, int ); 00183 extern int spInitialize(MatrixPtr Matrix, int (*)() ); 00184 extern void spInstallInitInfo(ElementPtr, double* ); 00185 extern double spLargestElement(MatrixPtr Matrix); 00186 extern void spMNA_Preorder(MatrixPtr Matrix); 00187 extern double spNorm(MatrixPtr Matrix); 00188 extern int spOrderAndFactor(MatrixPtr Matrix, double*, double, double, int ); 00189 extern void spPartition(MatrixPtr Matrix, int ); 00190 extern void spPrint(MatrixPtr Matrix, int, int, int ); 00191 extern double spPseudoCondition(MatrixPtr Matrix); 00192 extern double spRoundoff(MatrixPtr Matrix, double ); 00193 extern void spScale(MatrixPtr Matrix, double*, double* ); 00194 extern void spSetComplex(MatrixPtr Matrix); 00195 extern void spSetReal(MatrixPtr Matrix); 00196 extern void spStripFills(MatrixPtr Matrix); 00197 extern void spWhereSingular(MatrixPtr Matrix, int*, int* ); 00198 extern void spDeterminant (MatrixPtr Matrix, int*, double* ); 00199 extern int spFileVector(MatrixPtr Matrix, char* , double* ); 00200 extern void spMultiply(MatrixPtr Matrix, double*, double* ); 00201 extern void spMultTransposed(MatrixPtr Matrix, double*, double* ); 00202 extern void spSolve(MatrixPtr Matrix, double*, double*); 00203 extern void spSolveTransposed(MatrixPtr Matrix, double*, double* ); 00204 00205 #endif /* spOKAY */