NEURON
spconfig.h
Go to the documentation of this file.
1 /*
2  * CONFIGURATION MACRO DEFINITIONS for sparse matrix routines
3  *
4  * Author: Advising professor:
5  * Kenneth S. Kundert Alberto Sangiovanni-Vincentelli
6  * U.C. Berkeley
7  *
8  * This file contains macros for the sparse matrix routines that are used
9  * to define the personality of the routines. The user is expected to
10  * modify this file to maximize the performance of the routines with
11  * his/her matrices.
12  *
13  * Macros are distinguished by using solely capital letters in their
14  * identifiers. This contrasts with C defined identifiers which are
15  * strictly lower case, and program variable and procedure names which use
16  * both upper and lower case.
17  */
18 
19 
20 /*
21  * Revision and copyright information.
22  *
23  * Copyright (c) 1985,86,87,88
24  * by Kenneth S. Kundert and the University of California.
25  *
26  * Permission to use, copy, modify, and distribute this software and
27  * its documentation for any purpose and without fee is hereby granted,
28  * provided that the copyright notices appear in all copies and
29  * supporting documentation and that the authors and the University of
30  * California are properly credited. The authors and the University of
31  * California make no representations as to the suitability of this
32  * software for any purpose. It is provided `as is', without express
33  * or implied warranty.
34  *
35  * $Date: 2003-02-11 19:36:05 +0100 (Tue, 11 Feb 2003) $
36  * $Revision: 3 $
37  */
38 
39 
40 #ifndef spCONFIG_DEFS
41 #define spCONFIG_DEFS
42 
43 #if defined(cmplx_spPrefix)
44 #include "cspredef.h"
45 #endif
46 
47 
48 #ifdef spINSIDE_SPARSE
49 /*
50  * OPTIONS
51  *
52  * These are compiler options. Set each option to one to compile that
53  * section of the code. If a feature is not desired, set the macro
54  * to NO. Recommendations are given in brackets, [ignore them].
55  *
56  * >>> Option descriptions:
57  * Arithmetic Precision
58  * The precision of the arithmetic used by Sparse can be set by
59  * changing changing the spREAL macro. This macro is
60  * contained in the file spMatrix.h. It is strongly suggested to
61  * used double precision with circuit simulators. Note that
62  * because C always performs arithmetic operations in double
63  * precision, the only benefit to using single precision is that
64  * less storage is required. There is often a noticeable speed
65  * penalty when using single precision. Sparse internally refers
66  * to a spREAL as a RealNumber.
67  * REAL
68  * This specifies that the routines are expected to handle real
69  * systems of equations. The routines can be compiled to handle
70  * both real and complex systems at the same time, but there is a
71  * slight speed and memory advantage if the routines are complied
72  * to handle only real systems of equations.
73  * spCOMPLEX
74  * This specifies that the routines will be complied to handle
75  * complex systems of equations.
76  * EXPANDABLE
77  * Setting this compiler flag true (1) makes the matrix
78  * expandable before it has been factored. If the matrix is
79  * expandable, then if an element is added that would be
80  * considered out of bounds in the current matrix, the size of
81  * the matrix is increased to hold that element. As a result,
82  * the size of the matrix need not be known before the matrix is
83  * built. The matrix can be allocated with size zero and
84  * expanded.
85  * TRANSLATE
86  * This option allows the set of external row and column numbers
87  * to be non-packed. In other words, the row and column numbers
88  * do not have to be contiguous. The priced paid for this
89  * flexibility is that when TRANSLATE is set true, the time
90  * required to initially build the matrix will be greater because
91  * the external row and column number must be translated into
92  * internal equivalents. This translation brings about other
93  * benefits though. First, the spGetElement() and
94  * spGetAdmittance() routines may be used after the matrix has
95  * been factored. Further, elements, and even rows and columns,
96  * may be added to the matrix, and row and columns may be deleted
97  * from the matrix, after it has been factored. Note that when
98  * the set of row and column number is not a packed set, neither
99  * are the RHS and Solution vectors. Thus the size of these
100  * vectors must be at least as large as the external size, which
101  * is the value of the largest given row or column numbers.
102  * INITIALIZE
103  * Causes the spInitialize(), spGetInitInfo(), and
104  * spInstallInitInfo() routines to be compiled. These routines
105  * allow the user to store and read one pointer in each nonzero
106  * element in the matrix. spInitialize() then calls a user
107  * specified function for each structural nonzero in the matrix,
108  * and includes this pointer as well as the external row and
109  * column numbers as arguments. This allows the user to write
110  * custom matrix initialization routines.
111  * DIAGONAL_PIVOTING
112  * Many matrices, and in particular node- and modified-node
113  * admittance matrices, tend to be nearly symmetric and nearly
114  * diagonally dominant. For these matrices, it is a good idea to
115  * select pivots from the diagonal. With this option enabled,
116  * this is exactly what happens, though if no satisfactory pivot
117  * can be found on the diagonal, an off-diagonal pivot will be
118  * used. If this option is disabled, Sparse does not
119  * preferentially search the diagonal. Because of this, Sparse
120  * has a wider variety of pivot candidates available, and so
121  * presumably fewer fill-ins will be created. However, the
122  * initial pivot selection process will take considerably longer.
123  * If working with node admittance matrices, or other matrices
124  * with a strong diagonal, it is probably best to use
125  * DIAGONAL_PIVOTING for two reasons. First, accuracy will be
126  * better because pivots will be chosen from the large diagonal
127  * elements, thus reducing the chance of growth. Second, a near
128  * optimal ordering will be chosen quickly. If the class of
129  * matrices you are working with does not have a strong diagonal,
130  * do not use DIAGONAL_PIVOTING, but consider using a larger
131  * threshold. When DIAGONAL_PIVOTING is turned off, the following
132  * options and constants are not used: MODIFIED_MARKOWITZ,
133  * MAX_MARKOWITZ_TIES, and TIES_MULTIPLIER.
134  * ARRAY_OFFSET
135  * This determines whether arrays start at an index of zero or one.
136  * This option is necessitated by the fact that standard C
137  * convention dictates that arrays begin with an index of zero but
138  * the standard mathematic convention states that arrays begin with
139  * an index of one. So if you prefer to start your arrays with
140  * zero, or your calling Sparse from FORTRAN, set ARRAY_OFFSET to
141  * NO or 0. Otherwise, set ARRAY_OFFSET to YES or 1. Note that if
142  * you use an offset of one, the arrays that you pass to Sparse
143  * must have an allocated length of one plus the size of the
144  * matrix. ARRAY_OFFSET must be either 0 or 1, no other offsets
145  * are valid.
146  * spSEPARATED_COMPLEX_VECTORS
147  * This specifies the format for complex vectors. If this is set
148  * false then a complex vector is made up of one double sized
149  * array of RealNumber's in which the real and imaginary numbers
150  * are placed in the alternately array in the array. In other
151  * words, the first entry would be Complex[1].Real, then comes
152  * Complex[1].Imag, then Complex[1].Real, etc. If
153  * spSEPARATED_COMPLEX_VECTORS is set true, then each complex
154  * vector is represented by two arrays of RealNumbers, one with
155  * the real terms, the other with the imaginary. [NO]
156  * MODIFIED_MARKOWITZ
157  * This specifies that the modified Markowitz method of pivot
158  * selection is to be used. The modified Markowitz method differs
159  * from standard Markowitz in two ways. First, under modified
160  * Markowitz, the search for a pivot can be terminated early if a
161  * adequate (in terms of sparsity) pivot candidate is found.
162  * Thus, when using modified Markowitz, the initial factorization
163  * can be faster, but at the expense of a suboptimal pivoting
164  * order that may slow subsequent factorizations. The second
165  * difference is in the way modified Markowitz breaks Markowitz
166  * ties. When two or more elements are pivot candidates and they
167  * all have the same Markowitz product, then the tie is broken by
168  * choosing the element that is best numerically. The numerically
169  * best element is the one with the largest ratio of its magnitude
170  * to the magnitude of the largest element in the same column,
171  * excluding itself. The modified Markowitz method results in
172  * marginally better accuracy. This option is most appropriate
173  * for use when working with very large matrices where the initial
174  * factor time represents an unacceptable burden. [NO]
175  * DELETE
176  * This specifies that the spDeleteRowAndCol() routine
177  * should be compiled. Note that for this routine to be
178  * compiled, both DELETE and TRANSLATE should be set true.
179  * STRIP
180  * This specifies that the spStripFills() routine should be compiled.
181  * MODIFIED_NODAL
182  * This specifies that the routine that preorders modified node
183  * admittance matrices should be compiled. This routine results
184  * in greater speed and accuracy if used with this type of
185  * matrix.
186  * QUAD_ELEMENT
187  * This specifies that the routines that allow four related
188  * elements to be entered into the matrix at once should be
189  * compiled. These elements are usually related to an
190  * admittance. The routines affected by QUAD_ELEMENT are the
191  * spGetAdmittance, spGetQuad and spGetOnes routines.
192  * TRANSPOSE
193  * This specifies that the routines that solve the matrix as if
194  * it was transposed should be compiled. These routines are
195  * useful when performing sensitivity analysis using the adjoint
196  * method.
197  * SCALING
198  * This specifies that the routine that performs scaling on the
199  * matrix should be complied. Scaling is not strongly
200  * supported. The routine to scale the matrix is provided, but
201  * no routines are provided to scale and descale the RHS and
202  * Solution vectors. It is suggested that if scaling is desired,
203  * it only be preformed when the pivot order is being chosen [in
204  * spOrderAndFactor()]. This is the only time scaling has
205  * an effect. The scaling may then either be removed from the
206  * solution by the user or the scaled factors may simply be
207  * thrown away. [NO]
208  * DOCUMENTATION
209  * This specifies that routines that are used to document the
210  * matrix, such as spPrint() and spFileMatrix(), should be
211  * compiled.
212  * DETERMINANT
213  * This specifies that the routine spDeterminant() should be complied.
214  * STABILITY
215  * This specifies that spLargestElement() and spRoundoff() should
216  * be compiled. These routines are used to check the stability (and
217  * hence the quality of the pivoting) of the factorization by
218  * computing a bound on the size of the element is the matrix E =
219  * A - LU. If this bound is very high after applying
220  * spOrderAndFactor(), then the pivot threshold should be raised.
221  * If the bound increases greatly after using spFactor(), then the
222  * matrix should probably be reordered.
223  * CONDITION
224  * This specifies that spCondition() and spNorm(), the code that
225  * computes a good estimate of the condition number of the matrix,
226  * should be compiled.
227  * PSEUDOCONDITION
228  * This specifies that spPseudoCondition(), the code that computes
229  * a crude and easily fooled indicator of ill-conditioning in the
230  * matrix, should be compiled.
231  * MULTIPLICATION
232  * This specifies that the routines to multiply the unfactored
233  * matrix by a vector should be compiled.
234  * FORTRAN
235  * This specifies that the FORTRAN interface routines should be
236  * compiled. When interfacing to FORTRAN programs, the ARRAY_OFFSET
237  * options should be set to NO.
238  * DEBUG
239  * This specifies that additional error checking will be compiled.
240  * The type of error checked are those that are common when the
241  * matrix routines are first integrated into a user's program. Once
242  * the routines have been integrated in and are running smoothly, this
243  * option should be turned off.
244  */
245 
246 /* Begin options. */
247 #define REAL YES
248 #define EXPANDABLE YES
249 #if defined(cmplx_spPrefix)
250 /* NEURON's nonlinz.cpp uses cmplx_spGetElement after previous use of matrix */
251 #define TRANSLATE YES
252 #else
253 #define TRANSLATE NO /* instead of YES */
254 #endif
255 #define INITIALIZE NO /* instead of YES */
256 #define DIAGONAL_PIVOTING YES
257 #define ARRAY_OFFSET NOT FORTRAN
258 #define MODIFIED_MARKOWITZ NO
259 #define DELETE YES
260 #define STRIP YES
261 #define MODIFIED_NODAL YES
262 #define QUAD_ELEMENT YES
263 #define TRANSPOSE YES
264 #define SCALING YES
265 #define DOCUMENTATION YES
266 #define MULTIPLICATION YES
267 #define DETERMINANT YES
268 #define STABILITY YES
269 #define CONDITION YES
270 #define PSEUDOCONDITION YES
271 #define FORTRAN NO
272 #define DEBUG YES
273 
274 /*
275  * The following options affect Sparse exports and so are exported as a
276  * side effect. For this reason they use the `sp' prefix. The bool
277  * constants YES an NO are not defined in spMatrix.h to avoid conflicts
278  * with user code, so use 0 for NO and 1 for YES.
279  */
280 #endif /* spINSIDE_SPARSE */
281 #if defined(cmplx_spPrefix)
282 #define spCOMPLEX 1
283 #define spSEPARATED_COMPLEX_VECTORS 1
284 #else
285 #define spCOMPLEX 0 /* instead of 1 */
286 #define spSEPARATED_COMPLEX_VECTORS 0
287 #endif
288 #ifdef spINSIDE_SPARSE
289 
290 
291 
292 
293 
294 
295 
296 /*
297  * MATRIX CONSTANTS
298  *
299  * These constants are used throughout the sparse matrix routines. They
300  * should be set to suit the type of matrix being solved. Recommendations
301  * are given in brackets.
302  *
303  * Some terminology should be defined. The Markowitz row count is the number
304  * of non-zero elements in a row excluding the one being considered as pivot.
305  * There is one Markowitz row count for every row. The Markowitz column
306  * is defined similarly for columns. The Markowitz product for an element
307  * is the product of its row and column counts. It is a measure of how much
308  * work would be required on the next step of the factorization if that
309  * element were chosen to be pivot. A small Markowitz product is desirable.
310  *
311  * >>> Constants descriptions:
312  * DEFAULT_THRESHOLD
313  * The relative threshold used if the user enters an invalid
314  * threshold. Also the threshold used by spFactor() when
315  * calling spOrderAndFactor(). The default threshold should
316  * not be less than or equal to zero nor larger than one. [0.001]
317  * DIAG_PIVOTING_AS_DEFAULT
318  * This indicates whether spOrderAndFactor() should use diagonal
319  * pivoting as default. This issue only arises when
320  * spOrderAndFactor() is called from spFactor().
321  * SPACE_FOR_ELEMENTS
322  * This number multiplied by the size of the matrix equals the number
323  * of elements for which memory is initially allocated in
324  * spCreate(). [6]
325  * SPACE_FOR_FILL_INS
326  * This number multiplied by the size of the matrix equals the number
327  * of elements for which memory is initially allocated and specifically
328  * reserved for fill-ins in spCreate(). [4]
329  * ELEMENTS_PER_ALLOCATION
330  * The number of matrix elements requested from the malloc utility on
331  * each call to it. Setting this value greater than 1 reduces the
332  * amount of overhead spent in this system call. On a virtual memory
333  * machine, its good to allocate slightly less than a page worth of
334  * elements at a time (or some multiple thereof).
335  * [For the VAX, for real only use 41, otherwise use 31]
336  * MINIMUM_ALLOCATED_SIZE
337  * The minimum allocated size of a matrix. Note that this does not
338  * limit the minimum size of a matrix. This just prevents having to
339  * resize a matrix many times if the matrix is expandable, large and
340  * allocated with an estimated size of zero. This number should not
341  * be less than one.
342  * EXPANSION_FACTOR
343  * The amount the allocated size of the matrix is increased when it
344  * is expanded.
345  * MAX_MARKOWITZ_TIES
346  * This number is used for two slightly different things, both of which
347  * relate to the search for the best pivot. First, it is the maximum
348  * number of elements that are Markowitz tied that will be sifted
349  * through when trying to find the one that is numerically the best.
350  * Second, it creates an upper bound on how large a Markowitz product
351  * can be before it eliminates the possibility of early termination
352  * of the pivot search. In other words, if the product of the smallest
353  * Markowitz product yet found and TIES_MULTIPLIER is greater than
354  * MAX_MARKOWITZ_TIES, then no early termination takes place.
355  * Set MAX_MARKOWITZ_TIES to some small value if no early termination of
356  * the pivot search is desired. An array of RealNumbers is allocated
357  * of size MAX_MARKOWITZ_TIES so it must be positive and shouldn't
358  * be too large. Active when MODIFIED_MARKOWITZ is 1 (true). [100]
359  * TIES_MULTIPLIER
360  * Specifies the number of Markowitz ties that are allowed to occur
361  * before the search for the pivot is terminated early. Set to some
362  * large value if no early termination of the pivot search is desired.
363  * This number is multiplied times the Markowitz product to determine
364  * how many ties are required for early termination. This means that
365  * more elements will be searched before early termination if a large
366  * number of fill-ins could be created by accepting what is currently
367  * considered the best choice for the pivot. Active when
368  * MODIFIED_MARKOWITZ is 1 (true). Setting this number to zero
369  * effectively eliminates all pivoting, which should be avoided.
370  * This number must be positive. TIES_MULTIPLIER is also used when
371  * diagonal pivoting breaks down. [5]
372  * DEFAULT_PARTITION
373  * Which partition mode is used by spPartition() as default.
374  * Possibilities include
375  * spDIRECT_PARTITION -- each row used direct addressing, best for
376  * a few relatively dense matrices.
377  * spINDIRECT_PARTITION -- each row used indirect addressing, best
378  * for a few very sparse matrices.
379  * spAUTO_PARTITION -- direct or indirect addressing is chosen on
380  * a row-by-row basis, carries a large overhead, but speeds up
381  * both dense and sparse matrices, best if there is a large
382  * number of matrices that can use the same ordering.
383  */
384 
385 /* Begin constants. */
386 #define DEFAULT_THRESHOLD 1.0e-3
387 #define DIAG_PIVOTING_AS_DEFAULT YES
388 /*#define SPACE_FOR_ELEMENTS 6*/
389 /*#define SPACE_FOR_FILL_INS 4*/
390 #define SPACE_FOR_ELEMENTS 3
391 #define SPACE_FOR_FILL_INS 1
392 #define ELEMENTS_PER_ALLOCATION 31
393 #define MINIMUM_ALLOCATED_SIZE 6
394 #define EXPANSION_FACTOR 1.5
395 #define MAX_MARKOWITZ_TIES 100
396 #define TIES_MULTIPLIER 5
397 #define DEFAULT_PARTITION spAUTO_PARTITION
398 
399 
400 
401 
402 
403 
404 /*
405  * PRINTER WIDTH
406  *
407  * This macro characterize the printer for the spPrint() routine.
408  *
409  * >>> Macros:
410  * PRINTER_WIDTH
411  * The number of characters per page width. Set to 80 for terminal,
412  * 132 for line printer.
413  */
414 
415 /* Begin printer constants. */
416 #define PRINTER_WIDTH 80
417 
418 
419 
420 
421 
422 
423 /*
424  * MACHINE CONSTANTS
425  *
426  * These numbers must be updated when the program is ported to a new machine.
427  */
428 
429 /* Begin machine constants. */
430 
431 #ifdef notdef /* __STDC__ */
432 /*
433  * This code is currently deleted because most ANSI standard C compilers
434  * do not provide the standard header files yet.
435  */
436 #endif
437 #if defined(HAVE_LIMITS_H)
438 # include <limits.h>
439 # include <float.h>
440 # define MACHINE_RESOLUTION DBL_EPSILON
441 # define LARGEST_REAL DBL_MAX
442 # define SMALLEST_REAL DBL_MIN
443 # define LARGEST_SHORT_INTEGER SHRT_MAX
444 # define LARGEST_LONG_INTEGER LONG_MAX
445 #else /* do not have limits.h */ /* NOT defined(__STDC__) */
446 
447 /* VAX machine constants */
448 #ifdef vax
449 # define MACHINE_RESOLUTION 6.93889e-18
450 # define LARGEST_REAL 1.70141e+38
451 # define SMALLEST_REAL 2.938743e-39
452 # define LARGEST_SHORT_INTEGER 32766
453 # define LARGEST_LONG_INTEGER 2147483646
454 #endif
455 
456 /* hp9000 machine constants */
457 #ifdef hpux
458 /* These values are correct for hp9000/300. Should be correct for others. */
459 # define MACHINE_RESOLUTION 8.9e-15
460 # define LARGEST_REAL 1.79769313486231e+308
461 # define SMALLEST_REAL 2.22507385850721e-308
462 # define LARGEST_SHORT_INTEGER 32766
463 # define LARGEST_LONG_INTEGER 2147483646
464 #endif
465 
466 /* Sun machine constants */
467 #ifdef sun
468 /* These values are rumored to be the correct values. */
469 # define MACHINE_RESOLUTION 8.9e-15
470 # define LARGEST_REAL 1.79769313486231e+308
471 # define SMALLEST_REAL 2.22507385850721e-308
472 # define LARGEST_SHORT_INTEGER 32766
473 # define LARGEST_LONG_INTEGER 2147483646
474 #endif
475 #endif /* NOT defined(__STDC__) */
476 
477 
478 
479 
480 
481 
482 /*
483  * ANNOTATION
484  *
485  * This macro changes the amount of annotation produced by the matrix
486  * routines. The annotation is used as a debugging aid. Change the number
487  * associated with ANNOTATE to change the amount of annotation produced by
488  * the program.
489  */
490 
491 /* Begin annotation definitions. */
492 #define ANNOTATE NONE
493 
494 #define NONE 0
495 #define ON_STRANGE_BEHAVIOR 1
496 #define FULL 2
497 
498 #endif /* spINSIDE_SPARSE */
499 #endif /* spCONFIG_DEFS */