Jspice3
spdefs.h
Go to the documentation of this file.
1 /*
2  * DATA STRUCTURE AND MACRO DEFINITIONS for Sparse.
3  *
4  * Author: Advising professor:
5  * Kenneth S. Kundert Alberto Sangiovanni-Vincentelli
6  * UC Berkeley
7  *
8  * This file contains common type definitions and macros for the sparse
9  * matrix routines. These definitions are of no interest to the user.
10  */
11 
12 
13 /*
14  * Revision and copyright information.
15  *
16  * Copyright (c) 1985,86,87,88,89,90
17  * by Kenneth S. Kundert and the University of California.
18  *
19  * Permission to use, copy, modify, and distribute this software and
20  * its documentation for any purpose and without fee is hereby granted,
21  * provided that the copyright notices appear in all copies and
22  * supporting documentation and that the authors and the University of
23  * California are properly credited. The authors and the University of
24  * California make no representations as to the suitability of this
25  * software for any purpose. It is provided `as is', without express
26  * or implied warranty.
27  *
28  * $Date: 88/06/18 11:13:40 $
29  * $Revision: 1.2 $
30  */
31 
32 
33 
34 
35 /*
36  * IMPORTS
37  */
38 
39 #include <stdio.h>
40 #include "misc.h"
41 
42 
43 /*
44  * If running lint, change some of the compiler options to get a more
45  * complete inspection.
46  */
47 
48 #ifdef lint
49 #undef REAL
50 #undef spCOMPLEX
51 #undef EXPANDABLE
52 #undef TRANSLATE
53 #undef INITIALIZE
54 #undef DELETE
55 #undef STRIP
56 #undef MODIFIED_NODAL
57 #undef QUAD_ELEMENT
58 #undef TRANSPOSE
59 #undef SCALING
60 #undef DOCUMENTATION
61 #undef MULTIPLICATION
62 #undef DETERMINANT
63 #undef CONDITION
64 #undef PSEUDOCONDITION
65 #undef FORTRAN
66 #undef DEBUG
67 #undef spCOMPATIBILITY
68 
69 #define REAL YES
70 #define spCOMPLEX YES
71 #define EXPANDABLE YES
72 #define TRANSLATE YES
73 #define INITIALIZE YES
74 #define DELETE YES
75 #define STRIP YES
76 #define MODIFIED_NODAL YES
77 #define QUAD_ELEMENT YES
78 #define TRANSPOSE YES
79 #define SCALING YES
80 #define DOCUMENTATION YES
81 #define MULTIPLICATION YES
82 #define DETERMINANT YES
83 #define CONDITION YES
84 #define PSEUDOCONDITION YES
85 #define FORTRAN YES
86 #define DEBUG YES
87 #define spCOMPATIBILITY YES
88 
89 #define LINT YES
90 #else /* not lint */
91 #define LINT NO
92 #endif /* not lint */
93 
94 
95 
96 
97 
98 
99 
100 /*
101  * MACRO DEFINITIONS
102  *
103  * Macros are distinguished by using solely capital letters in their
104  * identifiers. This contrasts with C defined identifiers which are strictly
105  * lower case, and program variable and procedure names which use both upper
106  * and lower case.
107  */
108 
109 /* Begin macros. */
110 
111 /* Boolean data type */
112 #define BOOLEAN int
113 #define NO 0
114 #define YES 1
115 #define NOT !
116 #define AND &&
117 #define OR ||
118 
119 /* NULL pointer */
120 #ifndef NULL
121 #define NULL 0
122 #endif
123 
124 #define SPARSE_ID 0x772773 /* Arbitrary (is Sparse on phone). */
125 #define IS_SPARSE(matrix) ((matrix) != NULL && \
126  (matrix)->ID == SPARSE_ID)
127 #define IS_VALID(matrix) ((matrix) != NULL && \
128  (matrix)->ID == SPARSE_ID && \
129  (matrix)->Error >= spOKAY && \
130  (matrix)->Error < spFATAL)
131 #define IS_FACTORED(matrix) ((matrix)->Factored && !(matrix)->NeedsOrdering)
132 
133 /* Macro commands */
134 /* Macro functions that return the maximum or minimum independent of type. */
135 #define MAX(a,b) ((a) > (b) ? (a) : (b))
136 #define MIN(a,b) ((a) < (b) ? (a) : (b))
137 
138 /* Macro function that returns the absolute value of a floating point number. */
139 #define ABS(a) ((a) < 0 ? -(a) : (a))
140 
141 /* Macro function that returns the square of a number. */
142 #define SQR(a) ((a)*(a))
143 
144 /* Macro procedure that swaps two entities. */
145 #define SWAP(type, a, b) {type swapx; swapx = a; a = b; b = swapx;}
146 
147 /* Macro function that returns the approx absolute value of a complex number. */
148 
149 /* SRW -- changed this so that if spCOMPLEX is defined and the matrix
150  * is real, the imaginary part is ignored. Then we can cache stuff
151  * in the imaginary part without screwing up pivot selection.
152  */
153 #if spCOMPLEX
154 /* original
155 #define ELEMENT_MAG(ptr) (ABS((ptr)->Real) + ABS((ptr)->Imag))
156 */
157 #define ELEMENT_MAG(ptr) (Matrix->Complex ? \
158  (ABS((ptr)->Real) + ABS((ptr)->Imag)) : \
159  ((ptr)->Real < 0.0 ? -(ptr)->Real : (ptr)->Real))
160 #else
161 #define ELEMENT_MAG(ptr) ((ptr)->Real < 0.0 ? -(ptr)->Real : (ptr)->Real)
162 #endif
163 
164 /* Complex assignment statements. */
165 #define CMPLX_ASSIGN(to,from) \
166 { (to).Real = (from).Real; \
167  (to).Imag = (from).Imag; \
168 }
169 #define CMPLX_CONJ_ASSIGN(to,from) \
170 { (to).Real = (from).Real; \
171  (to).Imag = -(from).Imag; \
172 }
173 #define CMPLX_NEGATE_ASSIGN(to,from) \
174 { (to).Real = -(from).Real; \
175  (to).Imag = -(from).Imag; \
176 }
177 #define CMPLX_CONJ_NEGATE_ASSIGN(to,from) \
178 { (to).Real = -(from).Real; \
179  (to).Imag = (from).Imag; \
180 }
181 #define CMPLX_CONJ(a) (a).Imag = -(a).Imag
182 #define CMPLX_NEGATE(a) \
183 { (a).Real = -(a).Real; \
184  (a).Imag = -(a).Imag; \
185 }
186 
187 /* Macro that returns the approx magnitude (L-1 norm) of a complex number. */
188 #define CMPLX_1_NORM(a) (ABS((a).Real) + ABS((a).Imag))
189 
190 /* Macro that returns the approx magnitude (L-infinity norm) of a complex. */
191 #define CMPLX_INF_NORM(a) (MAX (ABS((a).Real),ABS((a).Imag)))
192 
193 /* Macro function that returns the magnitude (L-2 norm) of a complex number. */
194 #define CMPLX_2_NORM(a) (sqrt((a).Real*(a).Real + (a).Imag*(a).Imag))
195 
196 /* Macro function that performs complex addition. */
197 #define CMPLX_ADD(to,from_a,from_b) \
198 { (to).Real = (from_a).Real + (from_b).Real; \
199  (to).Imag = (from_a).Imag + (from_b).Imag; \
200 }
201 
202 /* Macro function that performs complex subtraction. */
203 #define CMPLX_SUBT(to,from_a,from_b) \
204 { (to).Real = (from_a).Real - (from_b).Real; \
205  (to).Imag = (from_a).Imag - (from_b).Imag; \
206 }
207 
208 /* Macro function that is equivalent to += operator for complex numbers. */
209 #define CMPLX_ADD_ASSIGN(to,from) \
210 { (to).Real += (from).Real; \
211  (to).Imag += (from).Imag; \
212 }
213 
214 /* Macro function that is equivalent to -= operator for complex numbers. */
215 #define CMPLX_SUBT_ASSIGN(to,from) \
216 { (to).Real -= (from).Real; \
217  (to).Imag -= (from).Imag; \
218 }
219 
220 /* Macro function that multiplies a complex number by a scalar. */
221 #define SCLR_MULT(to,sclr,cmplx) \
222 { (to).Real = (sclr) * (cmplx).Real; \
223  (to).Imag = (sclr) * (cmplx).Imag; \
224 }
225 
226 /* Macro function that multiply-assigns a complex number by a scalar. */
227 #define SCLR_MULT_ASSIGN(to,sclr) \
228 { (to).Real *= (sclr); \
229  (to).Imag *= (sclr); \
230 }
231 
232 /* Macro function that multiplies two complex numbers. */
233 #define CMPLX_MULT(to,from_a,from_b) \
234 { (to).Real = (from_a).Real * (from_b).Real - \
235  (from_a).Imag * (from_b).Imag; \
236  (to).Imag = (from_a).Real * (from_b).Imag + \
237  (from_a).Imag * (from_b).Real; \
238 }
239 
240 /* Macro function that implements to *= from for complex numbers. */
241 #define CMPLX_MULT_ASSIGN(to,from) \
242 { RealNumber to_real_ = (to).Real; \
243  (to).Real = to_real_ * (from).Real - \
244  (to).Imag * (from).Imag; \
245  (to).Imag = to_real_ * (from).Imag + \
246  (to).Imag * (from).Real; \
247 }
248 
249 /* Macro function that multiplies two complex numbers, the first of which is
250  * conjugated. */
251 #define CMPLX_CONJ_MULT(to,from_a,from_b) \
252 { (to).Real = (from_a).Real * (from_b).Real + \
253  (from_a).Imag * (from_b).Imag; \
254  (to).Imag = (from_a).Real * (from_b).Imag - \
255  (from_a).Imag * (from_b).Real; \
256 }
257 
258 /* Macro function that multiplies two complex numbers and then adds them
259  * to another. to = add + mult_a * mult_b */
260 #define CMPLX_MULT_ADD(to,mult_a,mult_b,add) \
261 { (to).Real = (mult_a).Real * (mult_b).Real - \
262  (mult_a).Imag * (mult_b).Imag + (add).Real; \
263  (to).Imag = (mult_a).Real * (mult_b).Imag + \
264  (mult_a).Imag * (mult_b).Real + (add).Imag; \
265 }
266 
267 /* Macro function that subtracts the product of two complex numbers from
268  * another. to = subt - mult_a * mult_b */
269 #define CMPLX_MULT_SUBT(to,mult_a,mult_b,subt) \
270 { (to).Real = (subt).Real - (mult_a).Real * (mult_b).Real + \
271  (mult_a).Imag * (mult_b).Imag; \
272  (to).Imag = (subt).Imag - (mult_a).Real * (mult_b).Imag - \
273  (mult_a).Imag * (mult_b).Real; \
274 }
275 
276 /* Macro function that multiplies two complex numbers and then adds them
277  * to another. to = add + mult_a* * mult_b where mult_a* represents mult_a
278  * conjugate. */
279 #define CMPLX_CONJ_MULT_ADD(to,mult_a,mult_b,add) \
280 { (to).Real = (mult_a).Real * (mult_b).Real + \
281  (mult_a).Imag * (mult_b).Imag + (add).Real; \
282  (to).Imag = (mult_a).Real * (mult_b).Imag - \
283  (mult_a).Imag * (mult_b).Real + (add).Imag; \
284 }
285 
286 /* Macro function that multiplies two complex numbers and then adds them
287  * to another. to += mult_a * mult_b */
288 #define CMPLX_MULT_ADD_ASSIGN(to,from_a,from_b) \
289 { (to).Real += (from_a).Real * (from_b).Real - \
290  (from_a).Imag * (from_b).Imag; \
291  (to).Imag += (from_a).Real * (from_b).Imag + \
292  (from_a).Imag * (from_b).Real; \
293 }
294 
295 /* Macro function that multiplies two complex numbers and then subtracts them
296  * from another. */
297 #define CMPLX_MULT_SUBT_ASSIGN(to,from_a,from_b) \
298 { (to).Real -= (from_a).Real * (from_b).Real - \
299  (from_a).Imag * (from_b).Imag; \
300  (to).Imag -= (from_a).Real * (from_b).Imag + \
301  (from_a).Imag * (from_b).Real; \
302 }
303 
304 /* Macro function that multiplies two complex numbers and then adds them
305  * to the destination. to += from_a* * from_b where from_a* represents from_a
306  * conjugate. */
307 #define CMPLX_CONJ_MULT_ADD_ASSIGN(to,from_a,from_b) \
308 { (to).Real += (from_a).Real * (from_b).Real + \
309  (from_a).Imag * (from_b).Imag; \
310  (to).Imag += (from_a).Real * (from_b).Imag - \
311  (from_a).Imag * (from_b).Real; \
312 }
313 
314 /* Macro function that multiplies two complex numbers and then subtracts them
315  * from the destination. to -= from_a* * from_b where from_a* represents from_a
316  * conjugate. */
317 #define CMPLX_CONJ_MULT_SUBT_ASSIGN(to,from_a,from_b) \
318 { (to).Real -= (from_a).Real * (from_b).Real + \
319  (from_a).Imag * (from_b).Imag; \
320  (to).Imag -= (from_a).Real * (from_b).Imag - \
321  (from_a).Imag * (from_b).Real; \
322 }
323 
324 /*
325  * Macro functions that provide complex division.
326  */
327 
328 /* Complex division: to = num / den */
329 #define CMPLX_DIV(to,num,den) \
330 { RealNumber r_, s_; \
331  if (((den).Real >= (den).Imag AND (den).Real > -(den).Imag) OR \
332  ((den).Real < (den).Imag AND (den).Real <= -(den).Imag)) \
333  { r_ = (den).Imag / (den).Real; \
334  s_ = (den).Real + r_*(den).Imag; \
335  (to).Real = ((num).Real + r_*(num).Imag)/s_; \
336  (to).Imag = ((num).Imag - r_*(num).Real)/s_; \
337  } \
338  else \
339  { r_ = (den).Real / (den).Imag; \
340  s_ = (den).Imag + r_*(den).Real; \
341  (to).Real = (r_*(num).Real + (num).Imag)/s_; \
342  (to).Imag = (r_*(num).Imag - (num).Real)/s_; \
343  } \
344 }
345 
346 /* Complex division and assignment: num /= den */
347 #define CMPLX_DIV_ASSIGN(num,den) \
348 { RealNumber r_, s_, t_; \
349  if (((den).Real >= (den).Imag AND (den).Real > -(den).Imag) OR \
350  ((den).Real < (den).Imag AND (den).Real <= -(den).Imag)) \
351  { r_ = (den).Imag / (den).Real; \
352  s_ = (den).Real + r_*(den).Imag; \
353  t_ = ((num).Real + r_*(num).Imag)/s_; \
354  (num).Imag = ((num).Imag - r_*(num).Real)/s_; \
355  (num).Real = t_; \
356  } \
357  else \
358  { r_ = (den).Real / (den).Imag; \
359  s_ = (den).Imag + r_*(den).Real; \
360  t_ = (r_*(num).Real + (num).Imag)/s_; \
361  (num).Imag = (r_*(num).Imag - (num).Real)/s_; \
362  (num).Real = t_; \
363  } \
364 }
365 
366 /* Complex reciprocation: to = 1.0 / den */
367 #define CMPLX_RECIPROCAL(to,den) \
368 { RealNumber r_; \
369  if (((den).Real >= (den).Imag AND (den).Real > -(den).Imag) OR \
370  ((den).Real < (den).Imag AND (den).Real <= -(den).Imag)) \
371  { r_ = (den).Imag / (den).Real; \
372  (to).Imag = -r_*((to).Real = 1.0/((den).Real + r_*(den).Imag)); \
373  } \
374  else \
375  { r_ = (den).Real / (den).Imag; \
376  (to).Real = -r_*((to).Imag = -1.0/((den).Imag + r_*(den).Real));\
377  } \
378 }
379 
380 
381 
382 
383 
384 
385 /*
386  * ASSERT and ABORT
387  *
388  * Macro used to assert that if the code is working correctly, then
389  * a condition must be true. If not, then execution is terminated
390  * and an error message is issued stating that there is an internal
391  * error and giving the file and line number. These assertions are
392  * not evaluated unless the DEBUG flag is true.
393  */
394 
395 #if DEBUG
396 #define ASSERT(condition) if (NOT(condition)) ABORT()
397 #else
398 #define ASSERT(condition)
399 #endif
400 
401 #if DEBUG
402 #define ABORT() \
403 { (void)fflush(stdout); \
404  (void)fprintf(stderr, "sparse: panic in file `%s' at line %d.\n", \
405  __FILE__, __LINE__); \
406  (void)fflush(stderr); \
407  abort(); \
408 }
409 #else
410 #define ABORT()
411 #endif
412 
413 
414 
415 
416 
417 /*
418  * IMAGINARY VECTORS
419  *
420  * The imaginary vectors iRHS and iSolution are only needed when the
421  * options spCOMPLEX and spSEPARATED_COMPLEX_VECTORS are set. The following
422  * macro makes it easy to include or exclude these vectors as needed.
423  */
424 
425 #if spCOMPLEX AND spSEPARATED_COMPLEX_VECTORS
426 #define IMAG_VECTORS , iRHS, iSolution
427 #define IMAG_RHS , iRHS
428 #else
429 #define IMAG_VECTORS
430 #define IMAG_RHS
431 #endif
432 
433 #define ALLOC(type,number) ((type *)tmalloc((unsigned)(sizeof(type)*(number))))
434 #define REALLOC(ptr,type,number) \
435  ptr = (type *)trealloc((char *)ptr,(unsigned)(sizeof(type)*(number)))
436 #define FREE(ptr) { if ((ptr) != NULL) txfree((char *)(ptr)); (ptr) = NULL; }
437 
438 
439 /* Calloc that properly handles allocating a cleared vector. */
440 #define CALLOC(ptr,type,number) \
441 { int i; ptr = ALLOC(type, number); \
442  if (ptr != (type *)NULL) \
443  for(i=(number)-1;i>=0; i--) ptr[i] = (type) 0; \
444 }
445 
446 
447 
448 
449 
450 
451 
452 /*
453  * REAL NUMBER
454  */
455 
456 /* Begin `RealNumber'. */
457 
459 
460 
461 
462 
463 
464 
465 
466 
467 /*
468  * COMPLEX NUMBER DATA STRUCTURE
469  *
470  * >>> Structure fields:
471  * Real (RealNumber)
472  * The real portion of the number. Real must be the first
473  * field in this structure.
474  * Imag (RealNumber)
475  * The imaginary portion of the number. This field must follow
476  * immediately after Real.
477  */
478 
479 /* Begin `ComplexNumber'. */
480 
481 typedef struct
485 
486 
487 
488 
489 
490 
491 
492 
493 /*
494  * MATRIX ELEMENT DATA STRUCTURE
495  *
496  * Every nonzero element in the matrix is stored in a dynamically allocated
497  * MatrixElement structure. These structures are linked together in an
498  * orthogonal linked list. Two different MatrixElement structures exist.
499  * One is used when only real matrices are expected, it is missing an entry
500  * for imaginary data. The other is used if complex matrices are expected.
501  * It contains an entry for imaginary data.
502  *
503  * >>> Structure fields:
504  * Real (RealNumber)
505  * The real portion of the value of the element. Real must be the first
506  * field in this structure.
507  * Imag (RealNumber)
508  * The imaginary portion of the value of the element. If the matrix
509  * routines are not compiled to handle complex matrices, then this
510  * field does not exist. If it exists, it must follow immediately after
511  * Real.
512  * Row (int)
513  * The row number of the element.
514  * Col (int)
515  * The column number of the element.
516  * NextInRow (struct MatrixElement *)
517  * NextInRow contains a pointer to the next element in the row to the
518  * right of this element. If this element is the last nonzero in the
519  * row then NextInRow contains NULL.
520  * NextInCol (struct MatrixElement *)
521  * NextInCol contains a pointer to the next element in the column below
522  * this element. If this element is the last nonzero in the column then
523  * NextInCol contains NULL.
524  * pInitInfo (char *)
525  * Pointer to user data used for initialization of the matrix element.
526  * Initialized to NULL.
527  *
528  * >>> Type definitions:
529  * ElementPtr
530  * A pointer to a MatrixElement.
531  * ArrayOfElementPtrs
532  * An array of ElementPtrs. Used for FirstInRow, FirstInCol and
533  * Diag pointer arrays.
534  */
535 
536 /* Begin `MatrixElement'. */
537 
540 #if spCOMPLEX
541  RealNumber Imag;
542 #endif
543  RealNumber Init; /* SRW, used to initialize */
544  int Row;
545  int Col;
548 #if INITIALIZE
549  char *pInitInfo;
550 #endif
551 };
552 
553 typedef struct MatrixElement *ElementPtr;
554 typedef ElementPtr *ArrayOfElementPtrs;
555 
556 
557 
558 
559 
560 
561 
562 
563 /*
564  * ALLOCATION DATA STRUCTURE
565  *
566  * The sparse matrix routines keep track of all memory that is allocated by
567  * the operating system so the memory can later be freed. This is done by
568  * saving the pointers to all the chunks of memory that are allocated to a
569  * particular matrix in an allocation list. That list is organized as a
570  * linked list so that it can grow without a priori bounds.
571  *
572  * >>> Structure fields:
573  * AllocatedPtr (char *)
574  * Pointer to chunk of memory that has been allocated for the matrix.
575  * NextRecord (struct AllocationRecord *)
576  * Pointer to the next allocation record.
577  */
578 
579 /* Begin `AllocationRecord'. */
581 { char *AllocatedPtr;
583 };
584 
586 
587 
588 
589 
590 
591 
592 
593 
594 
595 /*
596  * FILL-IN LIST DATA STRUCTURE
597  *
598  * The sparse matrix routines keep track of all fill-ins separately from
599  * user specified elements so they may be removed by spStripFills(). Fill-ins
600  * are allocated in bunched in what is called a fill-in lists. The data
601  * structure defined below is used to organize these fill-in lists into a
602  * linked-list.
603  *
604  * >>> Structure fields:
605  * pFillinList (ElementPtr)
606  * Pointer to a fill-in list, or a bunch of fill-ins arranged contiguously
607  * in memory.
608  * NumberOfFillinsInList (int)
609  * Seems pretty self explanatory to me.
610  * Next (struct FillinListNodeStruct *)
611  * Pointer to the next fill-in list structures.
612  */
613 
614 /* Begin `FillinListNodeStruct'. */
616 { ElementPtr pFillinList;
619 };
620 
621 
622 
623 
624 
625 
626 
627 
628 
629 
630 /*
631  * MATRIX FRAME DATA STRUCTURE
632  *
633  * This structure contains all the pointers that support the orthogonal
634  * linked list that contains the matrix elements. Also included in this
635  * structure are other numbers and pointers that are used globally by the
636  * sparse matrix routines and are associated with one particular matrix.
637  *
638  * >>> Type definitions:
639  * MatrixPtr
640  * A pointer to MatrixFrame. Essentially, a pointer to the matrix.
641  *
642  * >>> Structure fields:
643  * AbsThreshold (RealNumber)
644  * The absolute magnitude an element must have to be considered as a
645  * pivot candidate, except as a last resort.
646  * AllocatedExtSize (int)
647  * The allocated size of the arrays used to translate external row and
648  * column numbers to their internal values.
649  * AllocatedSize (int)
650  * The currently allocated size of the matrix; the size the matrix can
651  * grow to when EXPANDABLE is set true and AllocatedSize is the largest
652  * the matrix can get without requiring that the matrix frame be
653  * reallocated.
654  * Complex (BOOLEAN)
655  * The flag which indicates whether the matrix is complex (true) or
656  * real.
657  * CurrentSize (int)
658  * This number is used during the building of the matrix when the
659  * TRANSLATE option is set true. It indicates the number of internal
660  * rows and columns that have elements in them.
661  * Diag (ArrayOfElementPtrs)
662  * Array of pointers that points to the diagonal elements.
663  * DoCmplxDirect (BOOLEAN *)
664  * Array of flags, one for each column in matrix. If a flag is true
665  * then corresponding column in a complex matrix should be eliminated
666  * in spFactor() using direct addressing (rather than indirect
667  * addressing).
668  * DoRealDirect (BOOLEAN *)
669  * Array of flags, one for each column in matrix. If a flag is true
670  * then corresponding column in a real matrix should be eliminated
671  * in spFactor() using direct addressing (rather than indirect
672  * addressing).
673  * Elements (int)
674  * The number of original elements (total elements minus fill ins)
675  * present in matrix.
676  * Error (int)
677  * The error status of the sparse matrix package.
678  * ExtSize (int)
679  * The value of the largest external row or column number encountered.
680  * ExtToIntColMap (int [])
681  * An array that is used to convert external columns number to internal
682  * external column numbers. Present only if TRANSLATE option is set true.
683  * ExtToIntRowMap (int [])
684  * An array that is used to convert external row numbers to internal
685  * external row numbers. Present only if TRANSLATE option is set true.
686  * Factored (BOOLEAN)
687  * Indicates if matrix has been factored. This flag is set true in
688  * spFactor() and spOrderAndFactor() and set false in spCreate()
689  * and spClear().
690  * Fillins (int)
691  * The number of fill-ins created during the factorization the matrix.
692  * FirstInCol (ArrayOfElementPtrs)
693  * Array of pointers that point to the first nonzero element of the
694  * column corresponding to the index.
695  * FirstInRow (ArrayOfElementPtrs)
696  * Array of pointers that point to the first nonzero element of the row
697  * corresponding to the index.
698  * ID (unsigned long int)
699  * A constant that provides the sparse data structure with a signature.
700  * When DEBUG is true, all externally available sparse routines check
701  * this signature to assure they are operating on a valid matrix.
702  * Intermediate (RealVector)
703  * Temporary storage used in the spSolve routines. Intermediate is an
704  * array used during forward and backward substitution. It is
705  * commonly called y when the forward and backward substitution process is
706  * denoted Ax = b => Ly = b and Ux = y.
707  * InternalVectorsAllocated (BOOLEAN)
708  * A flag that indicates whether the Markowitz vectors and the
709  * Intermediate vector have been created.
710  * These vectors are created in spcCreateInternalVectors().
711  * IntToExtColMap (int [])
712  * An array that is used to convert internal column numbers to external
713  * external column numbers.
714  * IntToExtRowMap (int [])
715  * An array that is used to convert internal row numbers to external
716  * external row numbers.
717  * MarkowitzCol (int [])
718  * An array that contains the count of the non-zero elements excluding
719  * the pivots for each column. Used to generate and update MarkowitzProd.
720  * MarkowitzProd (long [])
721  * The array of the products of the Markowitz row and column counts. The
722  * element with the smallest product is the best pivot to use to maintain
723  * sparsity.
724  * MarkowitzRow (int [])
725  * An array that contains the count of the non-zero elements excluding
726  * the pivots for each row. Used to generate and update MarkowitzProd.
727  * MaxRowCountInLowerTri (int)
728  * The maximum number of off-diagonal element in the rows of L, the
729  * lower triangular matrix. This quantity is used when computing an
730  * estimate of the roundoff error in the matrix.
731  * NeedsOrdering (BOOLEAN)
732  * This is a flag that signifies that the matrix needs to be ordered
733  * or reordered. NeedsOrdering is set true in spCreate() and
734  * spGetElement() or spGetAdmittance() if new elements are added to the
735  * matrix after it has been previously factored. It is set false in
736  * spOrderAndFactor().
737  * NumberOfInterchangesIsOdd (BOOLEAN)
738  * Flag that indicates the sum of row and column interchange counts
739  * is an odd number. Used when determining the sign of the determinant.
740  * Partitioned (BOOLEAN)
741  * This flag indicates that the columns of the matrix have been
742  * partitioned into two groups. Those that will be addressed directly
743  * and those that will be addressed indirectly in spFactor().
744  * PivotsOriginalCol (int)
745  * Column pivot was chosen from.
746  * PivotsOriginalRow (int)
747  * Row pivot was chosen from.
748  * PivotSelectionMethod (char)
749  * Character that indicates which pivot search method was successful.
750  * PreviousMatrixWasComplex (BOOLEAN)
751  * This flag in needed to determine how to clear the matrix. When
752  * dealing with real matrices, it is important that the imaginary terms
753  * in the matrix elements be zero. Thus, if the previous matrix was
754  * complex, then the current matrix will be cleared as if it were complex
755  * even if it is real.
756  * RelThreshold (RealNumber)
757  * The magnitude an element must have relative to others in its row
758  * to be considered as a pivot candidate, except as a last resort.
759  * Reordered (BOOLEAN)
760  * This flag signifies that the matrix has been reordered. It
761  * is cleared in spCreate(), set in spMNA_Preorder() and
762  * spOrderAndFactor() and is used in spPrint().
763  * RowsLinked (BOOLEAN)
764  * A flag that indicates whether the row pointers exist. The AddByIndex
765  * routines do not generate the row pointers, which are needed by some
766  * of the other routines, such as spOrderAndFactor() and spScale().
767  * The row pointers are generated in the function spcLinkRows().
768  * SingularCol (int)
769  * Normally zero, but if matrix is found to be singular, SingularCol is
770  * assigned the external column number of pivot that was zero.
771  * SingularRow (int)
772  * Normally zero, but if matrix is found to be singular, SingularRow is
773  * assigned the external row number of pivot that was zero.
774  * Singletons (int)
775  * The number of singletons available for pivoting. Note that if row I
776  * and column I both contain singletons, only one of them is counted.
777  * Size (int)
778  * Number of rows and columns in the matrix. Does not change as matrix
779  * is factored.
780  * TrashCan (MatrixElement)
781  * This is a dummy MatrixElement that is used to by the user to stuff
782  * data related to the zero row or column. In other words, when the user
783  * adds an element in row zero or column zero, then the matrix returns
784  * a pointer to TrashCan. In this way the user can have a uniform way
785  * data into the matrix independent of whether a component is connected
786  * to ground.
787  *
788  * >>> The remaining fields are related to memory allocation.
789  * TopOfAllocationList (AllocationListPtr)
790  * Pointer which points to the top entry in a list. The list contains
791  * all the pointers to the segments of memory that have been allocated
792  * to this matrix. This is used when the memory is to be freed on
793  * deallocation of the matrix.
794  * RecordsRemaining (int)
795  * Number of slots left in the list of allocations.
796  * NextAvailElement (ElementPtr)
797  * Pointer to the next available element which has been allocated but as
798  * yet is unused. Matrix elements are allocated in groups of
799  * ELEMENTS_PER_ALLOCATION in order to speed element allocation and
800  * freeing.
801  * ElementsRemaining (int)
802  * Number of unused elements left in last block of elements allocated.
803  * NextAvailFillin (ElementPtr)
804  * Pointer to the next available fill-in which has been allocated but
805  * as yet is unused. Fill-ins are allocated in a group in order to keep
806  * them physically close in memory to the rest of the matrix.
807  * FillinsRemaining (int)
808  * Number of unused fill-ins left in the last block of fill-ins
809  * allocated.
810  * FirstFillinListNode (FillinListNodeStruct *)
811  * A pointer to the head of the linked-list that keeps track of the
812  * lists of fill-ins.
813  * LastFillinListNode (FillinListNodeStruct *)
814  * A pointer to the tail of the linked-list that keeps track of the
815  * lists of fill-ins.
816  */
817 
818 /* Begin `MatrixFrame'. */
825  ArrayOfElementPtrs Diag;
828  int Elements;
829  int Error;
830  int ExtSize;
834  int Fillins;
835  ArrayOfElementPtrs FirstInCol;
836  ArrayOfElementPtrs FirstInRow;
837  unsigned long ID;
859  int Size;
860  struct MatrixElement TrashCan;
861 
862  AllocationListPtr TopOfAllocationList;
864  ElementPtr NextAvailElement;
866  ElementPtr NextAvailFillin;
870 };
871 typedef struct MatrixFrame *MatrixPtr;
872 
873 
874 
875 
876 /*
877  * Function declarations
878  */
879 
880 #ifdef __STDC__
881 extern ElementPtr spcGetElement( MatrixPtr );
882 extern ElementPtr spcGetFillin( MatrixPtr );
883 extern ElementPtr spcFindElementInCol( MatrixPtr, ElementPtr*, int, int, int );
884 extern ElementPtr spcCreateElement( MatrixPtr, int, int, ElementPtr*, int );
885 extern void spcCreateInternalVectors( MatrixPtr );
886 extern void spcLinkRows( MatrixPtr );
887 extern void spcColExchange( MatrixPtr, int, int );
888 extern void spcRowExchange( MatrixPtr, int, int );
889 #else /* __STDC__ */
890 extern ElementPtr spcGetElement();
891 extern ElementPtr spcGetFillin();
892 extern ElementPtr spcFindElementInCol();
893 extern ElementPtr spcCreateElement();
894 extern void spcCreateInternalVectors();
895 extern void spcLinkRows();
896 extern void spcColExchange();
897 extern void spcRowExchange();
898 #endif /* __STDC__ */
BOOLEAN Partitioned
Definition: spdefs.h:848
ElementPtr NextAvailFillin
Definition: spdefs.h:866
ElementPtr spcGetElement()
RealNumber RelThreshold
Definition: spdefs.h:853
RealNumber Init
Definition: spdefs.h:543
int * MarkowitzRow
Definition: spdefs.h:842
int * MarkowitzCol
Definition: spdefs.h:843
char PivotSelectionMethod
Definition: spdefs.h:851
ArrayOfElementPtrs FirstInRow
Definition: spdefs.h:836
int Size
Definition: spdefs.h:859
int PivotsOriginalRow
Definition: spdefs.h:850
#define BOOLEAN
Definition: spdefs.h:112
int SingularCol
Definition: spdefs.h:856
BOOLEAN * DoRealDirect
Definition: spdefs.h:827
int NumberOfFillinsInList
Definition: spdefs.h:617
int SingularRow
Definition: spdefs.h:857
int RecordsRemaining
Definition: spdefs.h:863
struct FillinListNodeStruct * FirstFillinListNode
Definition: spdefs.h:868
RealNumber Real
Definition: spdefs.h:539
long * MarkowitzProd
Definition: spdefs.h:844
int * ExtToIntRowMap
Definition: spdefs.h:832
spREAL * RealVector
Definition: spdefs.h:458
struct ComplexNumber * ComplexVector
BOOLEAN PreviousMatrixWasComplex
Definition: spdefs.h:852
BOOLEAN NumberOfInterchangesIsOdd
Definition: spdefs.h:847
int Singletons
Definition: spdefs.h:858
void spcCreateInternalVectors()
struct MatrixElement * NextInCol
Definition: spdefs.h:547
BOOLEAN Factored
Definition: spdefs.h:833
BOOLEAN NeedsOrdering
Definition: spdefs.h:846
struct MatrixElement * ElementPtr
Definition: spdefs.h:553
struct FillinListNodeStruct * LastFillinListNode
Definition: spdefs.h:869
ElementPtr pFillinList
Definition: spdefs.h:616
struct AllocationRecord * AllocationListPtr
Definition: spdefs.h:585
RealNumber AbsThreshold
Definition: spdefs.h:820
int FillinsRemaining
Definition: spdefs.h:867
ElementPtr spcCreateElement()
RealNumber Imag
Definition: spdefs.h:483
int PivotsOriginalCol
Definition: spdefs.h:849
int * IntToExtColMap
Definition: spdefs.h:840
int ExtSize
Definition: spdefs.h:830
ElementPtr spcFindElementInCol()
ElementPtr spcGetFillin()
int * IntToExtRowMap
Definition: spdefs.h:841
int Fillins
Definition: spdefs.h:834
#define spREAL
Definition: spmatrix.h:145
void spcLinkRows()
ElementPtr NextAvailElement
Definition: spdefs.h:864
struct AllocationRecord * NextRecord
Definition: spdefs.h:582
int Error
Definition: spdefs.h:829
int CurrentSize
Definition: spdefs.h:824
BOOLEAN Complex
Definition: spdefs.h:823
RealVector Intermediate
Definition: spdefs.h:838
void spcColExchange()
BOOLEAN RowsLinked
Definition: spdefs.h:855
RealNumber Real
Definition: spdefs.h:482
void spcRowExchange()
spREAL RealNumber
Definition: spdefs.h:458
unsigned long ID
Definition: spdefs.h:837
BOOLEAN InternalVectorsAllocated
Definition: spdefs.h:839
int AllocatedExtSize
Definition: spdefs.h:822
int Elements
Definition: spdefs.h:828
struct MatrixElement * NextInRow
Definition: spdefs.h:546
ArrayOfElementPtrs Diag
Definition: spdefs.h:825
int * ExtToIntColMap
Definition: spdefs.h:831
BOOLEAN Reordered
Definition: spdefs.h:854
int ElementsRemaining
Definition: spdefs.h:865
struct MatrixFrame * MatrixPtr
Definition: spdefs.h:871
struct FillinListNodeStruct * Next
Definition: spdefs.h:618
char * AllocatedPtr
Definition: spdefs.h:581
ElementPtr * ArrayOfElementPtrs
Definition: spdefs.h:554
int MaxRowCountInLowerTri
Definition: spdefs.h:845
BOOLEAN * DoCmplxDirect
Definition: spdefs.h:826
ArrayOfElementPtrs FirstInCol
Definition: spdefs.h:835
AllocationListPtr TopOfAllocationList
Definition: spdefs.h:862
int AllocatedSize
Definition: spdefs.h:821