Main Page   Compound List   File List   File Members  

spBuild.c File Reference

#include <stdio.h>
#include "spConfig.h"
#include "spMatrix.h"
#include "spDefs.h"

Defines

#define spINSIDE_SPARSE
#define BorderRight   0
#define BorderDown   1
#define DiagRight   2
#define DiagDown   3

Functions

void spClear (spMatrix eMatrix)
spElement * spFindElement (spMatrix eMatrix, int Row, int Col)
spElement * spGetElement (spMatrix eMatrix, int Row, int Col)
spError spGetAdmittance (spMatrix Matrix, int Node1, int Node2, struct spTemplate *Template)
spError spGetQuad (spMatrix Matrix, int Row1, int Row2, int Col1, int Col2, struct spTemplate *Template)
spError spGetOnes (spMatrix Matrix, int Pos, int Neg, int Eqn, struct spTemplate *Template)
ElementPtr spcFindDiag (MatrixPtr Matrix, register int Index)
ElementPtr spcCreateElement (MatrixPtr Matrix, int Row, register int Col, register ElementPtr *ppToLeft, register ElementPtr *ppAbove, BOOLEAN Fillin)
void spcLinkRows (MatrixPtr Matrix)
int spInitialize (spMatrix eMatrix, int(*pInit)(spElement *pElement, spGenericPtr pInitInfo, int Row, int Col))
void spInstallInitInfo (spElement *pElement, spGenericPtr pInitInfo)
spGenericPtr spGetInitInfo (spElement *pElement)

Detailed Description

This file contains the routines associated with clearing, loading and preprocessing the matrix.

Objects that begin with the spc prefix are considered private and should not be used.

Author:
Kenneth S. Kundert <kundert@users.sourceforge.net>

Function Documentation

void spClear (  spMatrix    eMatrix ) 
 

Sets every element of the matrix to zero and clears the error flag.

Parameters:
eMatrix  Pointer to matrix that is to be cleared.

spElement* spFindElement (  spMatrix    eMatrix,
int    Row,
int    Col
) 
 

This routine is used to find an element given its indices. It will not create it if it does not exist.

Returns :
A pointer to the desired element, or NULL if it does not exist.
Parameters:
eMatrix  Pointer to matrix.
Row  Row index for element.
Col  Column index for element.
See also:
spGetElement()

spError spGetAdmittance (  spMatrix    Matrix,
int    Node1,
int    Node2,
struct spTemplate *    Template
) 
 

Performs same function as spGetElement() except rather than one element, all four matrix elements for a floating two terminal admittance component are added. This routine also works if component is grounded. Positive elements are placed at [Node1,Node2] and [Node2,Node1]. This routine is only to be used after spCreate() and before spMNA_Preorder(), spFactor() or spOrderAndFactor().

Returns :
Error code. Possible errors include spNO_MEMORY. Error is not cleared in this routine.
Parameters:
Matrix  Pointer to the matrix that component is to be entered in.
Node1  Row and column indices for elements. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Node zero is the ground node. In no case may Node1 be less than zero.
Node2  Row and column indices for elements. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Node zero is the ground node. In no case may Node2 be less than zero.
Template  Collection of pointers to four elements that are later used to directly address elements. User must supply the template, this routine will fill it.

spElement* spGetElement (  spMatrix    eMatrix,
int    Row,
int    Col
) 
 

Finds element [Row,Col] and returns a pointer to it. If element is not found then it is created and spliced into matrix. This routine is only to be used after spCreate() and before spMNA_Preorder(), spFactor() or spOrderAndFactor(). Returns a pointer to the real portion of an spElement. This pointer is later used by spADD_xxx_ELEMENT to directly access element.

Returns :
Returns a pointer to the element. This pointer is then used to directly access the element during successive builds.
Parameters:
eMatrix  Pointer to the matrix that the element is to be added to.
Row  Row index for element. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Elements placed in row zero are discarded. In no case may Row be less than zero.
Col  Column index for element. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Elements placed in column zero are discarded. In no case may Col be less than zero.
See also:
spFindElement()

spGenericPtr spGetInitInfo (  spElement *    pElement ) 
 

This function returns a pointer to a data structure that is used to contain initialization information to a matrix element.

Returns :
The pointer to the initialiation information data structure that is associated with a particular matrix element.
Parameters:
pElement  Pointer to the matrix element.
See also:
spInitialize()

spError spGetOnes (  spMatrix    Matrix,
int    Pos,
int    Neg,
int    Eqn,
struct spTemplate *    Template
) 
 

Addition of four structural ones to matrix by index. Performs similar function to spGetQuad() except this routine is meant for components that do not have an admittance representation.

The following stamp is used: 

         Pos  Neg  Eqn
  Pos  [  .    .    1  ]
  Neg  [  .    .   -1  ]
  Eqn  [  1   -1    .  ]

Returns :
Error code. Possible errors include spNO_MEMORY. Error is not cleared in this routine.
Parameters:
Matrix  Pointer to the matrix that component is to be entered in.
Pos  See stamp above. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Zero is the ground row. In no case may Pos be less than zero.
Neg  See stamp above. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Zero is the ground row. In no case may Neg be less than zero.
Eqn  See stamp above. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Zero is the ground row. In no case may Eqn be less than zero.
Template  Collection of pointers to four elements that are later used to directly address elements. User must supply the template, this routine will fill it.

spError spGetQuad (  spMatrix    Matrix,
int    Row1,
int    Row2,
int    Col1,
int    Col2,
struct spTemplate *    Template
) 
 

Similar to spGetAdmittance(), except that spGetAdmittance() only handles 2-terminal components, whereas spGetQuad() handles simple 4-terminals as well. These 4-terminals are simply generalized 2-terminals with the option of having the sense terminals different from the source and sink terminals. spGetQuad() adds four elements to the matrix. Positive elements occur at [Row1,Col1] [Row2,Col2] while negative elements occur at [Row1,Col2] and [Row2,Col1]. The routine works fine if any of the rows and columns are zero. This routine is only to be used after spCreate() and before spMNA_Preorder(), spFactor() or spOrderAndFactor() unless TRANSLATE is set true.

Returns :
Error code. Possible errors include spNO_MEMORY. Error is not cleared in this routine.
Parameters:
Matrix  Pointer to the matrix that component is to be entered in.
Row1  First row index for elements. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Zero is the ground row. In no case may Row1 be less than zero.
Row2  Second row index for elements. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Zero is the ground row. In no case may Row2 be less than zero.
Col1  First column index for elements. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Zero is the ground column. In no case may Col1 be less than zero.
Col2  Second column index for elements. Must be in the range of [0..Size] unless the options EXPANDABLE or TRANSLATE are used. Zero is the ground column. In no case may Col2 be less than zero.
Template  Collection of pointers to four elements that are later used to directly address elements. User must supply the template, this routine will fill it.

int spInitialize (  spMatrix    eMatrix,
int(*    pInit)(spElement *pElement, spGenericPtr pInitInfo, int Row, int Col)
) 
 

Initialize the matrix.

With the INITIALIZE compiler option (see spConfig.h) set true, Sparse allows the user to keep initialization information with each structurally nonzero matrix element. Each element has a pointer that is set and used by the user. The user can set this pointer using spInstallInitInfo() and may be read using spGetInitInfo(). Both may be used only after the element exists. The function spInitialize() is a user customizable way to initialize the matrix. Passed to this routine is a function pointer. spInitialize() sweeps through every element in the matrix and checks the pInitInfo pointer (the user supplied pointer). If the pInitInfo is NULL, which is true unless the user changes it (almost always true for fill-ins), then the element is zeroed. Otherwise, the function pointer is called and passed the pInitInfo pointer as well as the element pointer and the external row and column numbers. If the user sets the value of each element, then spInitialize() replaces spClear().

The user function is expected to return a nonzero integer if there is a fatal error and zero otherwise. Upon encountering a nonzero return code, spInitialize() terminates, sets the error state of the matrix to be spMANGLED, and returns the error code.

Returns :
Returns the return value of the pInit() function.
Parameters:
eMatrix  Pointer to matrix.
pInit  Pointer to a function that initializes an element.
See also:
spClear()

void spInstallInitInfo (  spElement *    pElement,
spGenericPtr    pInitInfo
) 
 

This function installs a pointer to a data structure that is used to contain initialization information to a matrix element. It is is then used by spInitialize() to initialize the matrix.

Parameters:
pElement  Pointer to matrix element.
pInitInfo  Pointer to the data structure that will contain initialiation information.
See also:
spInitialize()

Generated on Mon Jun 30 12:01:27 2003 for Sparse by doxygen1.2.17