** Next:** MLSOLV(3LAS)
**Up:** Manual Pages
** Previous:** ITERSOLV(3LAS)

` M_Constr`, ` M_Destr`,
` M_SetName`, ` M_GetName`,
` M_GetRowDim`, ` M_GetClmDim`, ` M_GetElOrder`,
` M_SetLen`, ` M_GetLen`,
` M_SetEntry`, ` M_GetPos`, ` M_GetVal`, ` M_AddVal`,
` M__SetEntry`, ` M__GetPos`, ` M__GetVal`, ` M__AddVal`,
` M_GetEl`,
` M_SortEl`,
` M_Lock`, ` M_Unlock`
-- type ` Matrix` for general rectangular sparse matrices

#include <laspack/matrix.h>
typedef double Real;
typedef enum {
Rowws,
Clmws
} ElOrderType;
typedef enum {
Normal,
Tempor
} InstanceType;
void M_Constr(Matrix *M, char *Name, size_t RowDim, size_t ClmDim,
ElOrderType ElOrder, InstanceType Instance, Boolean OwnData);
void M_Destr(Matrix *M);
void M_SetName(Matrix *M, char *Name);
char *M_GetName(Matrix *M);
size_t M_GetRowDim(Matrix *M);
size_t M_GetClmDim(Matrix *M);
ElOrderType M_GetElOrder(Matrix *M);
void M_SetLen(Matrix *M, size_t RoC, size_t Len);
size_t M_GetLen(Matrix *M, size_t RoC);
void M_SetEntry(Matrix *M, size_t RoC, size_t Entry, size_t Pos, Real Val);
Real M_GetPos(Matrix *M, size_t RoC, size_t Entry);
size_t M_GetEVal(Matrix *M, size_t RoC, size_t Entry);
void M_AddVal(Matrix *M, size_t RoC, size_t Entry, Real Val);
void M__SetEntry(Matrix *M, size_t RoC, size_t Entry, size_t Pos, Real Val);
Real M__GetPos(Matrix *M, size_t RoC, size_t Entry);
size_t M__GetVal(Matrix *M, size_t RoC, size_t Entry);
void M__AddVal(Matrix *M, size_t RoC, size_t Entry, Real Val);
Real M_GetEl(Matrix *M, size_t Row, size_t Clm);
void M_SortEl(Matrix *M);
void M_Lock(Matrix *M);
void M_Unlock(Matrix *M);

######

The procedure ` M_Constr` is the constructor of the type ` Matrix`.
It creates and initializes a new variable of this type directed
by the parameter ` M`.
As symbolic name, the string ` Name` is used.
The row and column dimensions of the matrix are defined by ` RowDim` and
` ClmDim`.
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,
own should always use the parameters
` Instance = Normal` and ` OwnData = True`.
In this case, ` M_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 ` M_Destr` is the destructor of type ` Matrix`.
It releases memory of matrix elements as well as internal auxiliary variables.

######

The procedure ` M_SetName` resets the symbolic name of the matrix.
This can be queried by the procedure ` M_GetName`.

######

The procedures ` M_GetRowDim` and ` M_GetClmDim` return the row and column dimension
of the matrix, respectively.

######

The procedure ` M_GetElOrder` returns the element order
of matrix elements.

######

The procedure ` M_SetLen` sets or resets the length,
i.e. the number of non-zero elements,
of the row or column ` RoC`
` (1 <= RoC <= RowDim / ClmDim)`
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 ` M_GetLen`.

######

The procedure ` M_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).`

######

The procedures ` M_GetPos` and ` M_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 ` M_AddEntry` adds the value ` Val`
to the non-zero element stored as entry ` Entry`
in the row or column ` RoC`.

######

The procedures ` M__GetLen`, ` M__SetEntry`, ` M__GetPos`,
` M__GetVal` and ` M__AddEntry` have the same functionality as
the routines ` M_GetLen`, ` M_SetEntry`, ` M_GetPos`,
` M_GetVal` and ` M_AddEntry`.
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 ` M_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 ` M_SortEl` sorts elements of each row or column
in ascending order.

######

In subroutines, the procedure ` M_Lock` should be applied
to all passed parameters of the type ` Matrix`.
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 ` M_Unlock`
which have to be called at the end of the procedure.

` matrix.h ... ` header file

` matrix.c ... ` source file

######

The matrix

| 1 2 1 0 0 0 0 |
| 0 0 1 2 1 0 0 |
| 0 0 0 0 1 2 1 |

which may be used e.g. for weighted restriction
of grid functions from a seven point to a three point grid,
could be generated by the following code fragment:

Matrix R;
size_t Row;
...
M_Constr(&R, "R", 3, 7, Rowws, Normal, True);
for (Row = 1; Row <= 3; Row++) {
M_SetLen(&R, Row, 3);
M_SetEntry(&R, Row, 0, 2 * Row - 1, 0.5);
M_SetEntry(&R, Row, 1, 2 * Row, 1.0);
M_SetEntry(&R, Row, 2, 2 * Row + 1, 0.5);
}
...
M_Destr(&R);

operats(3LAS), errhandl(3LAS)

** Next:** MLSOLV(3LAS)
**Up:** Manual Pages
** Previous:** ITERSOLV(3LAS)

Tomas Skalicky (skalicky@msmfs1.mw.tu-dresden.de)