KmlMgMatrixCreate

创建矩阵句柄

创建矩阵时是浅拷贝，用户需要保证MgMatrixDestroy之前不释放参数store指定的内存

接口定义

C Interface：

KmlMgStatus KmlMgMatrixCreate(KmlMgMatrixH* pMatrix, const KmlMgMatrixStore* store, const KmlMgMatrixOptions* options);

参数

参数名	类型	描述	输入/输出
pMatrix	KmlMgMatrixH*	矩阵句柄，pMatrix不可为空指针	输入/输出
store	const KmlMgMatrixStore*	矩阵的结构与数据信息	输入
options	const KmlMgMatrixOptions*	矩阵的数据类型等信息	输入

返回值

返回值	类型	描述
KML_MG_OK	int	正常执行
KML_MG_ERR_INVALID_PARAM	int	参数无效
KML_MG_ERR_UNSUPPORTED	int	暂不支持的功能
KML_MG_ERR_NO_MEMORY	int	分配内存失败
KML_MG_ERR_EXCEEDS_LIMIT	int	超过设置限制
KML_MG_ERR_INCOMPATIBLE	int	版本不兼容
KML_MG_ERR_NO_REQUIRED_FIELD	int	没设置必填字段
KML_MG_ERR_UNKNOWN_TYPE	int	未知的类型
KML_MG_ERR_THIRD_PART	int	内部调用第三方错误
KML_MG_ERR_INCONSISTENT	int	传递信息不一致
KML_MG_ERR_UNEXPECTED_CALL_ORDER	int	预期之外的调用顺序
KML_MG_ERR_MATRIX_VALUE_IS_NULL	int	矩阵值为空
KML_MG_ERR_NO_RESOURCE	int	资源未就绪

结构体说明

KmlMgMatrixOptions

字段名	类型	描述
fieldMask	uint64_t	配置生效的字段掩码。非0的位代表配置对应字段指定的值，0的位代表使用默认值，可配置的掩码位请参见具体字段的说明。
indexType	KmlMgIndexType	坐标类型，有如下值。 KML_MG_INDEX_INT32（目前只支持32位int） KML_MG_INDEX_INT64 掩码位：MG_MATRIX_OPTIONS_INDEX_TYPE
valueType	KmlMgValueType	数值类型，有如下值。（目前只支持FP32和FP64作为用户输入的数值类型） KML_MG_VALUE_FP16 KML_MG_VALUE_FP32 KML_MG_VALUE_FP64 掩码位：KML_MG_MATRIX_OPTIONS_VALUE_TYPE

字段名

类型

描述

fieldMask

uint64_t

配置生效的字段掩码。非0的位代表配置对应字段指定的值，0的位代表使用默认值，可配置的掩码位请参见具体字段的说明。

indexType

KmlMgIndexType

坐标类型，有如下值。

KML_MG_INDEX_INT32（目前只支持32位int）
KML_MG_INDEX_INT64

掩码位：MG_MATRIX_OPTIONS_INDEX_TYPE

valueType

KmlMgValueType

数值类型，有如下值。（目前只支持FP32和FP64作为用户输入的数值类型）

KML_MG_VALUE_FP16
KML_MG_VALUE_FP32
KML_MG_VALUE_FP64

掩码位：KML_MG_MATRIX_OPTIONS_VALUE_TYPE

KmlMgMatrixStore

字段名	类型	描述
comm	MPI_Comm	MPI 通信子
globalx	int64_t	所有进程组成的全局矩阵的 x 方向维度大小
globaly	int64_t	所有进程组成的全局矩阵的 y 方向维度大小
globalz	int64_t	所有进程组成的全局矩阵的 z 方向维度大小
procx	int64_t	x 方向上划分的进程数量
procy	int64_t	y 方向上划分的进程数量
procz	int64_t	z 方向上划分的进程数量
xbeg	int64_t	当前进程的 x 方向起始坐标（包含该坐标）
xend	int64_t	当前进程的 x 方向终止坐标（不含该坐标）
ybeg	int64_t	当前进程的 y 方向起始坐标（包含该坐标）
yend	int64_t	当前进程的 y 方向终止坐标（不含该坐标）
zbeg	int64_t	当前进程的 z 方向起始坐标（包含该坐标）
zend	int64_t	当前进程的 z 方向终止坐标（不含该坐标）
xhalo	int64_t	当前进程的 x 方向的halo区域大小，目前只支持halo=1
yhalo	int64_t	当前进程的 y 方向的halo区域大小，目前只支持halo=1
zhalo	int64_t	当前进程的 z 方向的halo区域大小，目前只支持halo=1
crossPolar	bool	网格是否跨极点通信，即网格边界是否连续
type	KmlMgMatrixStoreType	矩阵格式，均为结构化网格矩阵，有如下值。 KML_MG_MATRIX_STORE_DENSE_ROW_MAJOR（暂不支持） KML_MG_MATRIX_STORE_DENSE_COL_MAJOR（暂不支持） KML_MG_MATRIX_STORE_DENSE_ROW_MAJOR_HALO（暂不支持） KML_MG_MATRIX_STORE_DENSE_COL_MAJOR_HALO KML_MG_MATRIX_STORE_SPARSE（暂不支持） KML_MG_MATRIX_STORE_SPARSE_HALO 目前只支持向量为KML_MG_MATRIX_STORE_DENSE_COL_MAJOR_HALO，矩阵为KML_MG_MATRIX_STORE_SPARSE_HALO
dense	KmlMgMatrixStoreDense	稠密格式，目前用于存储右端向量和解向量，与sparse字段共同构成联合体
sparse	KmlMgMatrixStoreSparse	稀疏格式，目前用于存储稀疏矩阵，与dense字段共同构成联合体

KmlMgMatrixStoreDense

字段名	类型	描述
values	void*	数值数组，目前实现必须按Y-X-Z顺序（从外到里）排列
numDim	int64_t	次维度大小，表示行（列）主序的列（行）数
is2D	bool	是否为2D网格
needCorner	bool	网格结构是否存在角点，对应KmlMgMatrixStoreSparse中的stencil为KML_MG_STENCIL_2D5或KML_MG_STENCIL_3D7则为false，否则为true。

KmlMgMatrixStoreSparse

字段名

类型

描述

values

void*

数值数组，目前实现必须按Y-X-Z顺序（从外到里）排列

type

KmlMgSparseType

稀疏矩阵排列顺序，有如下值。

KML_MG_SPARSE_AOS
KML_MG_SPARSE_SOA（暂不支持）

如下图所示，对于本程序的结构化网格矩阵来说，AOS按网格（行）连续存储，SOA则按每条对角线连续存储

stencil

KmlMgStencilType

表示网格结构，稀疏矩阵按照行存储，根据网格结构决定矩阵每行的非零元个数，有如下值。

KML_MG_STENCIL_2D5（暂不支持）
KML_MG_STENCIL_2D9（暂不支持）
KML_MG_STENCIL_3D7
KML_MG_STENCIL_3D15（暂不支持）
KML_MG_STENCIL_3D19
KML_MG_STENCIL_3D27

使用暂不支持的参数会导致程序异常退出。

依赖

#include "mg.h"

示例代码请参见示例。

父主题： HMG