---
title: KmlMgMatrixCreate
description: "创建矩阵句柄。"
url: https://www.hikunpeng.com/document/detail/zh/kunpenghpcs/hpckit/devg/kunpengaccel_kml_0966.html
sourcePath: /source/zh/kunpenghpcs/hpckit/devg/kunpengaccel_kml_0966.html
indexId: b3f2cf882d2d77846348d6cb4658d5936e305a9596d434b634f89921f62adb4c61
---
# 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 |


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"

示例代码请参见示例。