KmlMgMatrixCreate
Create a matrix handle.
Shallow copy is used during matrix creation. You need to ensure that the memory specified by the store parameter is not freed before MgMatrixDestroy is called.
Interface Definition
C interface:
KmlMgStatus KmlMgMatrixCreate(KmlMgMatrixH* pMatrix, const KmlMgMatrixStore* store, const KmlMgMatrixOptions* options);
Parameters
|
Parameter |
Type |
Description |
Input/Output |
|---|---|---|---|
|
pMatrix |
KmlMgMatrixH* |
Matrix handle. pMatrix cannot be a null pointer. |
Input/Output |
|
store |
const KmlMgMatrixStore* |
Matrix structure and data information. |
Input |
|
options |
const KmlMgMatrixOptions* |
Matrix information such as the data type. |
Input |
Return Value
|
Return Value |
Type |
Description |
|---|---|---|
|
KML_MG_OK |
int |
Normal execution. |
|
KML_MG_ERR_INVALID_PARAM |
int |
Invalid parameter. |
|
KML_MG_ERR_UNSUPPORTED |
int |
Unsupported feature. |
|
KML_MG_ERR_NO_MEMORY |
int |
Memory allocation failed. |
|
KML_MG_ERR_EXCEEDS_LIMIT |
int |
Value out of the valid range. |
|
KML_MG_ERR_INCOMPATIBLE |
int |
Incompatible version. |
|
KML_MG_ERR_NO_REQUIRED_FIELD |
int |
Required field not set. |
|
KML_MG_ERR_UNKNOWN_TYPE |
int |
Unknown type. |
|
KML_MG_ERR_THIRD_PART |
int |
Errors from the internal third-party call. |
|
KML_MG_ERR_INCONSISTENT |
int |
Inconsistent information transferred. |
|
KML_MG_ERR_UNEXPECTED_CALL_ORDER |
int |
Unexpected call order. |
|
KML_MG_ERR_MATRIX_VALUE_IS_NULL |
int |
Null matrix value. |
|
KML_MG_ERR_NO_RESOURCE |
int |
Resources not ready. |
Structure Description
KmlMgMatrixOptions
|
Field |
Type |
Description |
|---|---|---|
|
fieldMask |
uint64_t |
Mask that determines to which fields the configuration is applied. If a bit is set to 1, its corresponding field uses a specified value. If a bit is set to 0, its corresponding field uses the default value. See the individual field description for configurable mask bits. |
|
indexType |
KmlMgIndexType |
Coordinate type. The options are as follows:
Mask bit: MG_MATRIX_OPTIONS_INDEX_TYPE |
|
valueType |
KmlMgValueType |
Value type. The options are as follows: (Currently, only FP32 and FP64 data types are supported for user input.)
Mask bit: KML_MG_MATRIX_OPTIONS_VALUE_TYPE |
KmlMgMatrixStore
|
Field |
Type |
Description |
|---|---|---|
|
comm |
MPI_Comm |
MPI communicator. |
|
globalx |
int64_t |
Size of the x dimension of the global matrix consisting of all processes. |
|
globaly |
int64_t |
Size of the y dimension of the global matrix consisting of all processes. |
|
globalz |
int64_t |
Size of the z dimension of the global matrix consisting of all processes. |
|
procx |
int64_t |
Number of processes in the x direction. |
|
procy |
int64_t |
Number of processes in the y direction. |
|
procz |
int64_t |
Number of processes in the z direction. |
|
xbeg |
int64_t |
Start coordinate of a process in the x direction (included). |
|
xend |
int64_t |
End coordinate of a process in the x direction (excluded). |
|
ybeg |
int64_t |
Start coordinate of a process in the y direction (included). |
|
yend |
int64_t |
End coordinate of a process in the y direction (excluded). |
|
zbeg |
int64_t |
Start coordinate of a process in the z direction (included). |
|
zend |
int64_t |
End coordinate of a process in the z direction (excluded). |
|
xhalo |
int64_t |
Size of the halo region in the x direction of a process. In the current version, only halo=1 is supported. |
|
yhalo |
int64_t |
Size of the halo region in the y direction of a process. In the current version, only halo=1 is supported. |
|
zhalo |
int64_t |
Size of the halo region in the z direction of a process. In the current version, only halo=1 is supported. |
|
crossPolar |
bool |
Specifies whether the grid support cross-pole communication, that is, whether the grid boundary is continuous. |
|
type |
KmlMgMatrixStoreType |
Matrix format with a structured mesh topology. The options are as follows:
Currently, only KML_MG_MATRIX_STORE_DENSE_COL_MAJOR_HALO vectors and KML_MG_MATRIX_STORE_SPARSE_HALO matrices are supported. |
|
dense |
KmlMgMatrixStoreDense |
Dense format, which is currently used to store RHS vectors and solution vectors. It forms a union with the sparse field. |
|
sparse |
KmlMgMatrixStoreSparse |
Sparse format, which is currently used to store sparse matrices. It forms a union with the dense field. |
KmlMgMatrixStoreDense
|
Field |
Type |
Description |
|---|---|---|
|
values |
void* |
Numeric array, which must be arranged in the Y-X-Z array (from outside to inside). |
|
numDim |
int64_t |
Secondary dimension size, indicating the number of columns (rows) in row- (column-) major order. |
|
is2D |
bool |
Specifies whether it is a 2D grid. |
|
needCorner |
bool |
Specifies whether the grid structure has corner points. If stencil in KmlMgMatrixStoreSparse is KML_MG_STENCIL_2D5 or KML_MG_STENCIL_3D7, the value is false. Otherwise, the value is true. |
KmlMgMatrixStoreSparse
|
Field |
Type |
Description |
|---|---|---|
|
values |
void* |
Numeric array, which must be arranged in the Y-X-Z array (from outside to inside). |
|
type |
KmlMgSparseType |
Order of the sparse matrix. The options are as follows:
As shown in the following figure, for the structured grid matrix of this program, AOS stores data continuously by grid (row), and SOA stores data continuously by diagonal.
|
|
stencil |
KmlMgStencilType |
Grid structure. The sparse matrix is stored by row. The number of non-zero elements in each row of the matrix is determined based on the grid structure. The options are as follows:
|
Using unsupported parameters will cause the program to exit abnormally.