---
title: KmlAmgMatrixCreate
description: "创建矩阵句柄。"
url: https://www.hikunpeng.com/document/detail/zh/kunpenghpcs/hpckit/devg/kunpengaccel_kml_0980.html
sourcePath: /source/zh/kunpenghpcs/hpckit/devg/kunpengaccel_kml_0980.html
indexId: d1695cfde2a66c16447b2f40170c865ef76bdb9835265da9e9807d989f491df061
---
# KmlAmgMatrixCreate

创建矩阵句柄。

创建矩阵时是浅拷贝，用户需要保证KmlAmgMatrixCreate创建的矩阵在求解结束之前不释放参数store指定的内存。


#### 接口定义

C Interface：

KmlAmgStatus KmlAmgMatrixCreate(KmlAmgMatrixH* matrix, KmlAmgMatrixStore* store, const KmlAmgMatrixOptions* options);


#### 参数

| 参数名 | 类型 | 描述 | 输入/输出 |
| --- | --- | --- | --- |
| matrix | KmlAmgMatrixH\* | 矩阵句柄，matrix不可为空指针 | 输入/输出 |
| store | KmlAmgMatrixStore\* | 矩阵的格式与数据信息结构体 | 输入 |
| options | KmlAmgMatrixOptions\* | 矩阵配置选项 | 输入 |


#### 返回值

| 返回值 | 类型 | 描述 |
| --- | --- | --- |
| KMLAMG\_SUCCESS | int | 运行成功 |
| KMLAMG\_ERR\_INVALID\_PARAM | int | 参数无效 |
| KMLAMG\_ERR\_UNSUPPORTED | int | 功能暂不支持 |
| KMLAMG\_ERR\_NULL\_POINTER | int | 空指针 |
| KMLAMG\_ERR\_NO\_REQUIRED\_FIELD | int | 没有设置必需字段 |
| KMLAMG\_ERR\_NO\_MEMORY | int | 内存分配失败 |
| KMLAMG\_ERR\_UNKNOWN\_TYPE | int | 未知的类型 |
| KMLAMG\_ERR\_UNEXPECTED\_CALL\_ORDER | int | 预期之外的调用顺序 |
| KMLAMG\_ERR\_NO\_RESOURCE | int | 资源未就绪 |
| KMLAMG\_ERR\_INCONSISTENT | int | 不同阶段传递的信息不一致 |
| KMLAMG\_ERR\_UNKNOWN\_ERROR | int | 未知错误 |


#### 结构体说明

KmlAmgMatrixStore结构体描述：


**表1 KmlAmgMatrixStore结构体**

| 字段名 | 类型 | 描述 |
| --- | --- | --- |
| globalNRows | int64\_t | 全局矩阵行数 |
| globalNCols | int64\_t | 全局矩阵列数 |
| localNRows | int64\_t | 本进程矩阵行数 |
| localNCols | int64\_t | 本进程矩阵列数 |
| type | KmlAmgMatrixStoreType | 矩阵的类型，有如下值： KMLAMG\_MATRIX\_STORE\_CSR表示CSR格式的矩阵 KMLAMG\_MATRIX\_STORE\_CSC表示CSC格式的矩阵（暂不支持） KMLAMG\_MATRIX\_STORE\_COO表示COO格式的矩阵（暂不支持） KMLAMG\_MATRIX\_STORE\_DENSE\_ROW\_MAJOR表示行主序矩阵（目前只支持列数为1，即向量） KMLAMG\_MATRIX\_STORE\_DENSE\_COL\_MAJOR表示列主序矩阵（暂不支持） |
| partitionType | KmlAmgMatrixPartitionType | 矩阵切分的类型，有如下值： KMLAMG\_MATRIX\_PARTITION\_ROW表示按行切分 KMLAMG\_MATRIX\_PARTITION\_COL表示按列切分（暂不支持） KMLAMG\_MATRIX\_PARTITION\_NZ表示按非零元切分（暂不支持） |
| isAvgPart | int8\_t | 矩阵是否是平均切分，0表示不平均，非0值表示平均切分 |
| localBegin | int64\_t | 当前进程矩阵的起始行/列索引 |
| dense | KmlAmgMatrixStoreDense | type为KMLAMG\_MATRIX\_STORE\_DENSE\_ROW\_MAJOR或KMLAMG\_MATRIX\_STORE\_DENSE\_COL\_MAJOR时，该字段有效，存储矩阵的值 |
| csr | KmlAmgMatrixStoreCSR | type为KMLAMG\_MATRIX\_STORE\_CSR时该字段生效，存储CSR矩阵的三元组信息 |
| csc | KmlAmgMatrixStoreCSC | type为KMLAMG\_MATRIX\_STORE\_CSC时该字段生效，存储CSC矩阵的三元组信息 |
| coo | KmlAmgMatrixStoreCOO | type为KMLAMG\_MATRIX\_STORE\_COO时该字段生效，存储COO矩阵的三元组信息 |


KmlAmgMatrixOptions结构体描述：

| 字段名 | 类型 | 描述 |
| --- | --- | --- |
| fieldMask | uint64\_t | 配置生效的字段掩码。非0的位代表配置对应字段指定的值，0的位代表使用默认值，可配置的掩码位见具体字段的说明。 |
| valueType | KmlAmgValueType | 矩阵数值类型，有如下值： KMLAMG\_VALUE\_FP32表示float KMLAMG\_VALUE\_FP64表示double 掩码位：KMLAMG\_MATRIX\_OPTIONS\_VALUE\_TYPE |
| indexType | KmlAmgIndexType | 矩阵索引类型： KMLAMG\_INDEX\_INT32表示int32\_t KMLAMG\_INDEX\_INT64表示int64\_t（暂不支持） 掩码位：KMLAMG\_MATRIX\_OPTIONS\_INDEX\_TYPE |
| comm | MPI\_Comm | 通信子 掩码位：KMLAMG\_MATRIX\_OPTIONS\_COMM |
| numThreads | int32\_t | 线程数 掩码位：KMLAMG\_MATRIX\_OPTIONS\_NUM\_THREADS |


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


#### 依赖

#include "amg4c.h"