laspack.tgz: laspack/html/node25.html

"Fossies" - the Fresh Open Source Software Archive

Member "laspack/html/node25.html" (13 Aug 1995, 11362 Bytes) of package /linux/privat/old/laspack.tgz:

Caution: In this restricted "Fossies" environment the current HTML page may not be correctly presentated and may have some non-functional links. You can here alternatively try to browse the pure source code or just view or download the uninterpreted raw source code. If the rendering is insufficient you may try to find and view the page on the project site itself.

Next: RTC(3LAS) Up: Manual Pages Previous: PRECOND(3LAS)

QMATRIX(3LAS)

NAME

Q_Constr, Q_Destr, Q_SetName, Q_GetName, Q_GetDim, Q_GetSymmetry, Q_GetElOrder, Q_SetLen, Q_GetLen, Q_SetEntry, Q_GetPos, Q_GetVal, Q_AddVal, Q__SetEntry, Q__GetPos, Q__GetVal, Q__AddVal, Q_GetEl, Q_SortEl, Q_AllocInvDiagEl, Q_SetKer, Q_KerDefined, Q_EigenvalInfo, Q_Lock, Q_Unlock -- type QMatrix for quadratic sparse matrices

SYNOPSIS

#include <laspack/qmatrix.h>

typedef double Real; 

typedef enum { 
    Rowws, 
    Clmws 
} ElOrderType; 

typedef enum { 
    Normal, 
    Tempor 
} InstanceType; 

void Q_Constr(QMatrix *Q, char *Name, size_t Dim, Boolean Symmetry, 
         ElOrderType ElOrder, InstanceType Instance, Boolean OwnData); 
void Q_Destr(QMatrix *Q); 
void Q_SetName(QMatrix *Q, char *Name); 
char *Q_GetName(QMatrix *Q); 
size_t Q_GetDim(QMatrix *Q); 
Boolean Q_GetSymmetry(QMatrix *Q); 
ElOrderType Q_GetElOrder(QMatrix *Q); 
void Q_SetLen(QMatrix *Q, size_t RoC, size_t Len); 
size_t Q_GetLen(QMatrix *Q, size_t RoC); 
void Q_SetEntry(QMatrix *Q, size_t RoC, size_t Entry, size_t Pos, Real Val); 
size_t Q_GetPos(QMatrix *Q, size_t RoC, size_t Entry); 
Real Q_GetVal(QMatrix *Q, size_t RoC, size_t Entry); 
void Q_AddVal(QMatrix *Q, size_t RoC, size_t Entry, Real Val); 
void Q__SetEntry(QMatrix *Q, size_t RoC, size_t Entry, size_t Pos, Real Val); 
size_t Q__GetPos(QMatrix *Q, size_t RoC, size_t Entry); 
Real Q__GetVal(QMatrix *Q, size_t RoC, size_t Entry); 
void Q__AddVal(QMatrix *Q, size_t RoC, size_t Entry, Real Val); 
Real Q_GetEl(QMatrix *Q, size_t Row, size_t Clm); 
void Q_SortEl(QMatrix *Q); 
void Q_AllocInvDiagEl(QMatrix *Q); 
void Q_SetKer(QMatrix *Q, Vector *RightKer, Vector *LeftKer); 
Boolean Q_KerDefined(QMatrix *Q); 
void **Q_EigenvalInfo(QMatrix *Q); 
void Q_Lock(QMatrix *Q); 
void Q_Unlock(QMatrix *Q);

DESCRIPTION

The procedure Q_Constr is the constructor of the type QMatrix. It creates and initializes a new variable of this type directed by the parameter Q. As symbolic name, the string Name is used. The dimensions of the matrix are defined by Dim. The parameter Symmetry should be set to True for symmetric, False for non-symmetric matrices. The parameter ElOrder determines the order in which the matrix elements are stored. It can be set to Rowws and Clmws for row-wise and column-wise ordering, respectively. For matrices used in application codes, one should always use the parameters Instance = Normal and OwnData = True. In this case, Q_Constr allocates memory for internal auxiliary variables needed for storage of matrix elements and initializes them. Other parameter combinations for Instance and OwnData are intended for internal usage by LASPack .

The procedure Q_Destr is the destructor of type QMatrix. It releases memory of matrix elements as well as internal auxiliary variables.

The procedure Q_SetName resets the symbolic name of the matrix. This can be queried by the procedure Q_GetName.

The procedure Q_GetDim returns the dimension of the matrix.

The procedure Q_GetSymmetry returns True if Q is stored as a symmetric matrix, False otherwise.

The procedure Q_GetElOrder returns the element order of matrix elements.

The procedure Q_SetLen sets or resets the length, i.e. the number of non-zero elements, of the row or column RoC (1 <= RoC <= Dim) to Len, and allocates memory for element storage. The length of each row or column is initialized by zero. The current value can be queried by the procedure Q_GetLen.

The procedure Q_SetEntry assigns position Pos and the value Val of a non-zero element in the row or column RoC to the entry Entry (0 <= Entry <= Len - 1). For symmetric matrices, only elements of the upper triangular part should be stored.

The procedures Q_GetPos and Q_GetVal return the position and the value of the non-zero element stored as entry Entry in the row or column RoC, respectively.

The procedure Q_AddEntry adds the value Val to the non-zero element stored as entry Entry in the row or column RoC.

The procedures Q__GetLen, Q__SetEntry, Q__GetPos, Q__GetVal and Q__AddVal have the same functionality as the routines Q_GetLen, Q_SetEntry, Q_GetPos, Q_GetVal and Q_AddVal. They are designed as preprocessing macros and are thus essentially faster. Because no range check is made they should not be used in the test phase of the application code.

The procedure Q_GetEl returns the value of the matrix element in the row Row and column Clm. In contrast to other procedures, all matrix elements are considered here. If any element is not stored, zero is returned.

The procedure Q_SortEl sorts elements of each row or column in ascending order.

The procedure Q_AllocInvDiagEl allocates pointers the diagonal elements and computes and stores their reciprocal values as auxiliary variables.

For singular matrices, an one-dimensional ``right'' and ``left'' null space can be defined by the procedure Q_SetKer with vectors RightKer and LeftKer as parameter. For symmetric matrices, the ``left'' null space equals to the ``right'' one and need therefore not to be set. The procedure Q_KerDefined returns True if a null space was specified, otherwise False.

The procedure Q_EigenvalInfo is used in LASPack internally. It allows to read and store information above eigenvalues of the matrix Q, which are produced by routines in module EIGENVAL, in connection with the matrix itself. The query of these data by the procedure Q_EigenvalInfo avoid an access to the internal representation of the type QMatrix.

In subroutines, the procedure Q_Lock should be applied to all passed parameters of the type QMatrix. This ensures that, if they are of temporary kind, they are not released within any LASPack routine before the procedure is leaved. This should be carried out by a call of Q_Unlock which have to be called at the end of the procedure.

FILES

qmatrix.h ... header file
qmatrix.c ... source file

EXAMPLES

A simple tridiagonal 7 x 7 matrix

       |  2   -1           |
   1   | -1    2   -1      |
  ---  |           ...     |
   h   |       1    2   -1 |
       |           -1    2 |

with h = 1/8 could be generated as follows:

QMatrix A;
size_t Row;
double h;

...

Q_Constr(&A, "A", 7, False, Rowws, Normal, True);

h = 1.0 / 8.0;

Q_SetLen(&A, 1, 2);
Q_SetEntry(&A, 1, 0, 1,  2.0 / h);       
Q_SetEntry(&A, 1, 1, 2, -1.0 / h);      
for (Row = 2; Row < 7; Row++) {
    Q_SetLen(&A, Row, 3);
    Q_SetEntry(&A, Row, 0, Row - 1, -1.0 / h);      
    Q_SetEntry(&A, Row, 1, Row,      2.0 / h);      
    Q_SetEntry(&A, Row, 2, Row + 1, -1.0 / h);
}
Q_SetLen(&A, 7, 2);
Q_SetEntry(&A, 7, 0, 6, -1.0 / h);      
Q_SetEntry(&A, 7, 1, 7,  2.0 / h);      

...

Q_Destr(&A);