Next: RTC(3LAS)
Up: Manual Pages
Previous: PRECOND(3LAS)
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
#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);
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 matrices,
to 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 the 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 the 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
to the diagonal elements and computes and stores their reciprocal values
as auxiliary variables.
For singular matrices, a 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 the ``right'' one
and therefore need not 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 us to read and store information above eigenvalues
of the matrix Q,
which are produced by routines in the 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 a temporary kind,
they are not released within any LASPack
routine
before the procedure is left.
This should be carried out by a call of Q_Unlock
which has to be called at the end of the procedure.
qmatrix.h ... header file
qmatrix.c ... source file
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);
matrix(3LAS), operats(3LAS),
errhandl(3LAS)
Next: RTC(3LAS)
Up: Manual Pages
Previous: PRECOND(3LAS)
Tomas Skalicky (skalicky@msmfs1.mw.tu-dresden.de)