KmlSolverMatrixCreate

Create a matrix operation handle.

Shallow copy is used during matrix creation. You need to ensure that the memory specified by the store parameter is not freed before KmlSolverMatrixDestroy is called.

Interface Definition

C interface:

int KmlSolverMatrixCreate(KmlSolverMatrix **pMatrix, const KmlSolverMatrixStore *store, const KmlSolverMatrixOption *matOption);

Parameters

Parameter	Type	Description	Input/Output
pMatrix	KmlSolverMatrix **	Matrix handle. pMatrix cannot be a null pointer.	Input/Output
store	KmlSolverMatrixStore *	Matrix format structure, which cannot be a null pointer. For details, see Table 1.	Input
matOption	KmlSolverMatrixOption *	Matrix configuration option, which cannot be a null pointer. For details, see Table 2.	Input

**Table 1** KmlSolverMatrixStore structure
Field	Type	Description
valueType	KmlSolverValueType	Value type. The options are as follows: KMLSS_VALUE_FP32: float KMLSS_VALUE_FP64: double KMLSS_VALUE_FP32C: complex float KMLSS_VALUE_FP64C: complex double
indexType	KmlSolverIndexType	Matrix coordinate index type. KMLSS_INDEX_INT32: int32_t KMLSS_INDEX_INT64: int64_t
nRow	int64_t	Number of rows in a matrix
nCol	int64_t	Number of columns in a matrix
format	KmlSolverMatrixStoreFormat	Matrix storage format. The options are as follows: KMLSS_MATRIX_STORE_CSR: CSR format KMLSS_MATRIX_STORE_CSR_L: CSR format, with only the lower triangular part KMLSS_MATRIX_STORE_CSR_U: CSR format, with only the upper triangular part KMLSS_MATRIX_STORE_CSC: CSC format KMLSS_MATRIX_STORE_CSC_L: CSC format, with only the lower triangular part KMLSS_MATRIX_STORE_CSC_U: CSC format, with only the upper triangular part KMLSS_MATRIX_STORE_COO: COO format KMLSS_MATRIX_STORE_COO_L: COO format, with only the lower triangular part KMLSS_MATRIX_STORE_COO_U: COO format, with only the upper triangular part KMLSS_MATRIX_STORE_DENSE_ROW_MAJOR: row-major dense storage KMLSS_MATRIX_STORE_DENSE_COL_MAJOR: column-major dense storage
csr	KmlSolverMatrixStoreCSR Table 3 describes the fields of this type.	This field is valid only when format is set to KMLSS_MATRIX_STORE_CSR, KMLSS_MATRIX_STORE_CSR_L, or KMLSS_MATRIX_STORE_CSR_U.
csc	KmlSolverMatrixStoreCSC Table 4 describes the fields of this type.	This field is valid only when format is set to KMLSS_MATRIX_STORE_CSC, KMLSS_MATRIX_STORE_CSC_L, or KMLSS_MATRIX_STORE_CSC_U.
coo	KmlSolverMatrixStoreCOO Table 5 describes the fields of this type.	This field is valid only when format is set to KMLSS_MATRIX_STORE_COO, KMLSS_MATRIX_STORE_COO_L, or KMLSS_MATRIX_STORE_COO_U.
dense	KmlSolverMatrixStoreDense Table 6 describes the fields of this type.	This field is valid only when format is set to KMLSS_MATRIX_STORE_DENSE_ROW_MAJOR or KMLSS_MATRIX_STORE_DENSE_COL_MAJOR.

**Table 2** KmlSolverMatrixOption structure
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.
type	KmlSolverMatrixType	Matrix type. The options are as follows: KMLSS_MATRIX_GEN indicates a general matrix. This is the default value. KMLSS_MATRIX_STRUCT_SYM indicates a structurally symmetric matrix. KMLSS_MATRIX_SYM indicates a symmetric matrix. KMLSS_MATRIX_HER indicates a Hermitian matrix. KMLSS_MATRIX_SPD indicates a symmetric positive definite matrix. KMLSS_MATRIX_HPD indicates a Hermitian positive definite matrix. Mask bit: KMLSS_MATRIX_OPTION_TYPE

**Table 3** KmlSolverMatrixStoreCSR structure
Field	Type	Description
value	void *	Non-zero element value array. The size is the number of non-zero elements.
rowOffset	void *	Row offset array. The size is the number of rows plus 1.
colIndex	void *	Column coordinate array. The size is the number of non-zero elements. The values must be sorted in ascending order.

**Table 4** KmlSolverMatrixStoreCSC structure
Field	Type	Description
value	void *	Non-zero element value array. The size is the number of non-zero elements.
rowIndex	void *	Row coordinate array. The size is the number of non-zero elements. The values must be sorted in ascending order.
colOffset	void *	Column offset array. The size is the number of rows plus 1.

**Table 5** KmlSolverMatrixStoreCOO structure
Field	Type	Description
value	void *	Non-zero element value array. The size is the number of non-zero elements.
rowId	void *	Row coordinate array. The size is the number of non-zero elements. The values must be sorted in ascending order.
colId	void *	Column coordinate array. The size is the number of non-zero elements. The column IDs in the same row must be sorted in ascending order.
nnz	int64_t	Number of non-zero elements.

**Table 6** KmlSolverMatrixStoreDense structure
Field	Type	Description
value	void *	Matrix value array. The size is the number of rows multiplied by the number of columns.
ld	int64_t	Leading dimension. For a row-major order, ld represents the array length required to store each row; for a column-major order, ld represents the array length required to store each column.

Return Value

Return Value	Type	Description
KMLSS_NO_ERROR	int	Normal execution.
KMLSS_INTERNAL_ERROR	int	Internal error.
KMLSS_NULL_ARGUMENT	int	A null argument exists in {pMatrix, store, matOption}.

Dependencies

#include "kml_solver.h"

Parent topic: Matrix Functions