cuDSS Functions

Library Management Functions

cudssCreate

cudssStatus_t
cudssCreate(cudssHandle_t* handle)

The function initializes the cuDSS library handle (cudssHandle_t) which holds the cuDSS library context. It allocates light hardware resources on the host, and must be called prior to making any other cuDSS library calls. Calling any cuDSS function which uses cudssHandle_t without a previous call of cudssCreate() will return an error. The cuDSS library context is tied to the current CUDA device. To use the library on multiple devices, one cuDSS handle should be created for each device.

Parameter	Memory	In/Out	Description
handle	Host	OUT	cuDSS library handle

See cudssStatus_t for the description of the return status.

---

cudssDestroy

cudssStatus_t
cudssDestroy(cudssHandle_t handle)

The function releases hardware resources used by the cuDSS library. This function is the last call with a particular handle to the cuDSS library. Calling any cuDSS function which uses cudssHandle_t after cudssDestroy() will return an error.

Parameter	Memory	In/Out	Description
handle	Host	IN	cuDSS library handle

See cudssStatus_t for the description of the return status.

---

cudssGetProperty

cudssStatus_t
cudssGetProperty(libraryPropertyType propertyType,
                 int*                value)

The function returns the value of the requested property. Refer to libraryPropertyType for supported types.

Parameter	Memory	In/Out	Description
propertyType	Host	IN	Requested property
value	Host	OUT	Value of the requested property

libraryPropertyType (defined in library_types.h):

Value	Meaning
MAJOR_VERSION	Enumerator to query the major version
MINOR_VERSION	Enumerator to query the minor version
PATCH_LEVEL	Number to identify the patch level

See cudssStatus_t for the description of the return status.

---

cudssSetStream

cudssStatus_t
cudssSetStream(cudssHandle_t* handle,
               cudaStream_t   stream)

The function sets the stream to be used by the cuDSS library to execute its routines.

Parameter	Memory	In/Out	Description
handle	Host	IN	cuDSS library handle
stream	Host	IN	The stream used by the library

See cudssStatus_t for the description of the return status.

---

cudssSetDeviceMemHandler

cudssStatus_t
cudssSetDeviceMemHandler(cudssHandle_t* handle,
                         const cudssDeviceMemHandler_t *handler)

Set the current device memory handler inside the library handle.

If handler argument is set to NULL, the library handle will detach its existing memory handler from the library handle. In case device memory handler needs to be changed after it is set for the first time, previously set device memory handler needs to be detached.

If a cuDSS API which needs to allocate device memory (cudssExecute()) is called and there is no device memory handler attached to the library handle at the moment of the call, cuDSS will allocate device memory internally using a default memory handler.

When the device memory handler is set, during calls to the main cuDSS routine cudssExecute() the library will allocate the necessary device memory using the device_alloc() member of the device memory handler struct. The allocated memory will remain a part of the cudssData_t object used in the call until the allocated memory will be deallocated using the device_free() member of the struct when the corresponding cudssDataDestroy() is called. As it follows, erroneous behavior is likely to occur if the device memory handler is changed during the lifespan of the cudssData_t objects which have used the library handle. See cudssDeviceMemHandler_t for further details about device_alloc() and device_free().

The internal stream order is established using the user-provided stream set via cudssSetStream() .

Note: It is undefined behavior if the library handle is bound to a memory handler and subsequently to another handler (without detaching), or the library handle outlives the attached memory pool, or the memory pool is not stream-ordered.

Parameter	Memory	In/Out	Description
handle	Host	IN	cuDSS library handle
handler	Host	IN	The device memory handler that encapsulates the user’s mempool. The struct content is copied internally

See cudssStatus_t for the description of the return status.

---

cudssGetDeviceMemHandler

cudssStatus_t
cudssGetDeviceMemHandler(cudssHandle_t* handle,
                         cudssDeviceMemHandler_t *handler)

Get the current device memory handler.

Parameter	Memory	In/Out	Description
handle	Host	IN	cuDSS library handle
handler	Host	OUT	A (deep) copy of the device memory handler that encapsulates the user’s mempool (if it was set) previously via calling cudssSetDeviceMemHandler()

See cudssStatus_t for the description of the return status.

---

cudssSetCommLayer

cudssStatus_t
cudssSetCommLayer(cudssHandle_t handle, const char* commLibFileName)

The function sets the communication layer to be used in MGMN mode

of cuDSS. The set communication layer will be used for all MGMN mode operations where the

modified library handle is involved.

For more details of when and how this function should be used, see

MGMN mode.

Parameter	Memory	In/Out	Description
handle	Host	IN	cuDSS library handle
commLibFileName	Host	IN	Full filename (including path) to the cuDSS communication layer library If NULL, the communication layer library name is read from the environment variable CUDSS_COMM_LIB

See cudssStatus_t for the description of the return status.

Config and Data Object Functions

cudssConfigCreate

cudssStatus_t
cudssConfigCreate(cudssConfig_t* config)

The function initializes the cuDSS config object (cudssConfig_t) which holds the settings of the solver related

to solving a specific linear system. It allocates light resources on the host.

To release the allocated memory, cudssConfigDestroy() must be called.

Parameter	Memory	In/Out	Description
config	Host	OUT	cuDSS config object

See cudssStatus_t for the description of the return status.

---

cudssConfigDestroy

cudssStatus_t
cudssConfigDestroy(cudssConfig_t config)

The function releases the host resources used by the cuDSS config object. Using the config object after this function call can lead to undefined behavior.

Parameter	Memory	In/Out	Description
config	Host	IN	cuDSS config object to be destroyed

See cudssStatus_t for the description of the return status.

---

cudssConfigSet

cudssStatus_t
cudssConfigSet(cudssConfig_t      config,
               cudssConfigParam_t param,
               void*              value,
               size_t             sizeInBytes)

The function sets a parameter (cudssConfigParam_t) to the specified value passed by the pointer.

Parameter	Memory	In/Out	Description
config	Host	INOUT	cuDSS config object
param	Host	IN	Parameter to be set
value	Host	IN	A pointer to the value to be set
sizeInBytes	Host	IN	Number of bytes to be read from the pointer

See cudssStatus_t for the description of the return status.

---

cudssConfigGet

cudssStatus_t
cudssConfigGet(cudssConfig_t      config,
               cudssConfigParam_t param,
               void*              value,
               size_t             sizeInBytes,
               size_t*            sizeWritten)

The function retrieves value of a parameter (cudssConfigParam_t) and saves it to the specified memory location.

Parameter	Memory	In/Out	Description
config	Host	IN	cuDSS config object
param	Host	IN	Parameter to be retrieved from the config
value	Host	OUT	A pointer to the output memory
sizeInBytes	Host	IN	Number of bytes to be written (for verification)
sizeWritten	Host	OUT	Valid only when the return value is CUDSS_STATUS_SUCCESS. If sizeInBytes is non-zero, then sizeWritten is the number of bytes actually written; if sizeInBytes is zero: sizeWritten is the number of bytes needed to write full contents

See cudssStatus_t for the description of the return status.

---

cudssDataCreate

cudssStatus_t
cudssDataCreate(cudssHandle_t handle, cudssData_t* data)

The function initializes the cuDSS data object (cudssData_t) which holds the internal data (e.g., LU factors arrays) as well as pointers to user-provided data related to solving a specific linear system. To release the allocated memory, cudssDataDestroy() must be called.

Parameter	Memory	In/Out	Description
handle	Host	IN	cuDSS library handle
data	Host	OUT	cuDSS data object

See cudssStatus_t for the description of the return status.

---

cudssDataDestroy

cudssStatus_t
cudssDataDestroy(cudssHandle_t handle, cudssData_t data)

The function releases the hardware resources used by the cuDSS data object. Using the data object after this function call can lead to undefined behavior.

Parameter	Memory	In/Out	Description
handle	Host	IN	cuDSS library handle
data	Host	IN	cuDSS data object to be destroyed

See cudssStatus_t for the description of the return status.

---

cudssDataSet

cudssStatus_t
cudssDataSet(cudssHandle_t    handle
             cudssData_t      data,
             cudssDataParam_t param,
             void*            value,
             size_t           sizeInBytes)

The function sets a parameter (cudssDataParam_t) to the specified value passed by the pointer.

Parameter	Memory	In/Out	Description
handle	Host	IN	cuDSS library handle
data	Host	INOUT	cuDSS data object
param	Host	IN	Parameter to be set
value	Host	IN	A pointer to the value to be set
sizeInBytes	Host	IN	Number of bytes to be read from the pointer

---

cudssDataGet

cudssStatus_t
cudssDataGet(cudssHandle_t    handle,
             cudssData_t      data,
             cudssDataParam_t param,
             void*            value,
             size_t           sizeInBytes,
             size_t*          sizeWritten)

The function retrieves value of a parameter (cudssDataParam_t) and saves it to the specified memory location.

The output memory buffer can be either on device or on host, a memory copy will be done if necessary.

Parameter	Memory	In/Out	Description
handle	Host	IN	cuDSS library handle
data	Host	IN	cuDSS data object
param	Host	IN	Parameter to be retrieved from the config
value	Host Device	OUT	A pointer to the output memory
sizeInBytes	Host	IN	Number of bytes to be written (for verification)
sizeWritten	Host	OUT	Valid only when the return value is CUDSS_STATUS_SUCCESS. If sizeInBytes is non-zero, then sizeWritten is the number of bytes actually written; if sizeInBytes is zero: sizeWritten is the number of bytes needed to write full contents

See cudssStatus_t for the description of the return status.

---

Main cuDSS Function

cudssExecute

cudssStatus_t
cudssExecute(cudssHandle_t  handle,
             cudssPhase_t   phase,
             cudssConfig_t  config,
             cudssConfig_t  data,
             cudssMatrix_t* matrix,
             cudssMatrix_t* solution,
             cudssMatrix_t* rhs)

The function executes a phase of the solution process. The data buffers in the matrix objects for the input matrix, solution and right-hand side matrices must hold device-visible data.

Parameter	Memory	In/Out	Description	Possible Values
handle	Host	IN	cuDSS library handle
phase	Host	IN	Execution phase
config	Host	IN	Solver config object
data	Host	INOUT	Solver data object
matrix	Host	IN	Input sparse matrix	Must be sparse
solution	Host	INOUT	Solution matrix	Must be dense
rhs	Host	IN	Right-hand side matrix	Must be dense

See cudssStatus_t for the description of the return status.

---

Matrix Object Functions

cudssMatrixCreateDn

cudssStatus_t
cudssMatrixCreateDn(cudssMatrix_t* matrix,
                    int64_t        nrows,
                    int64_t        ncols,
                    int64_t        ld,
                    void*          values,
                    cudaDataType_t valueType,
                    cudssLayout_t  layout)

The function creates a matrix object wrapped around dense matrix data. The provided data buffer for the matrix values must hold device-visible data.

Parameter	Memory	In/Out	Description	Possible Values
matrix	Host	OUT	Created matrix object
nrows	Host	IN	Number of rows	Must be non-negative
ncols	Host	IN	Number of columns	Must be non-negative
ld	Host	IN	Leading dimension	≥ nrows if column-major, ≥ ncols if row-major. The only supported values right now is exactly nrows (ncols)
values	Device	IN	Values of the dense matrix
valueType	Host	IN	Data type of the matrix	CUDA_R_32F, CUDA_R_64F, CUDA_C_32F, CUDA_C_64F
layout	Host	IN	Memory layout	CUDSS_LAYOUT_COL_MAJOR, CUDSS_LAYOUT_ROW_MAJOR The only supported value right now is CUDSS_LAYOUT_COL_MAJOR

See cudssStatus_t for the description of the return status.

---

cudssMatrixCreateCsr

cudssStatus_t
cudssMatrixCreateCsr(cudssMatrix_t*       matrix,
                     int64_t              nrows,
                     int64_t              ncols,
                     int64_t              nnz,
                     void*                rowStart,
                     void*                rowEnd,
                     void*                colIndices,
                     void*                values,
                     cudaDataType_t       indexType,
                     cudaDataType_t       valueType,
                     cudaMatrixType_t     mtype,
                     cudaMatrixViewType_t mview,
                     cudssIndexBase_t     indexBase)

The function creates a matrix object wrapped around dense matrix data. The provided data buffers for rowStart, rowEnd, colIndices and values must hold device-visible data.

Parameter	Memory	In/Out	Description	Possible Values
matrix	Host	OUT	Created matrix object
nrows	Host	IN	Number of rows	Must be non-negative
ncols	Host	IN	Number of columns	Must be non-negative
nnz	Host	IN	Number of non-zeroes	Must be non-negative
rowStart	Device	IN	Row start offsets
rowEnd	Device	IN	Values of the dense matrix	NULL is the only supported value as 4-array CSR is not supported currently
coIndices	Device	IN	Column indices of the matrix
values	Device	IN	Values of the dense matrix
indexType	Host	IN	Index type of the matrix	CUDA_R_32I
valueType	Host	IN	Data type of the matrix	CUDA_R_32F, CUDA_R_64F, CUDA_C_32F, CUDA_C_64F
mtype	Host	IN	Matrix type of the matrix	See cudssMatrixType_t
mview	Host	IN	Matrix view of the matrix	See cudssMatrixViewType_t
indexBase	Host	IN	Indexing base	See cudssIndexBase_t

See cudssStatus_t for the description of the return status.

---

cudssMatrixDestroy

cudssStatus_t
cudssMatrixDestroy(cudssMatrix_t* matrix)

The function releases memory associated with the matrix wrapper. As cuDSS matrix objects are only lightweight wrappers around the user data, the user data remains untouched.

Parameter	Memory	In/Out	Description
matrix	Host	IN	cuDSS matrix object

See cudssStatus_t for the description of the return status.

---

cudssMatrixSetValues

cudssStatus_t
cudssMatrixSetValues(cudssMatrix_t matrix, void *values)

The function resets the pointer to values inside the cuDSS matrix object to the provided buffer. The provided data buffer must hold device-visible data.

Parameter	Memory	In/Out	Description
matrix	Host	IN	cuDSS matrix object
values	Device	IN	Buffer with the new matrix values

See cudssStatus_t for the description of the return status.

---

cudssMatrixSetCsrPointers

cudssStatus_t
cudssMatrixSetCsrPointers(cudssMatrix_t matrix,
                          void*         rowStart,
                          void*         rowEnd,
                          void*         colIndices,
                          void*         values)

The function resets the CSR pointers inside the cuDSS matrix object to the provided buffers. The provided data buffers must hold device-visible data.

Parameter	Memory	In/Out	Description
matrix	Host	IN	cuDSS matrix object
rowStart	Device	IN	Buffer with the new row start offsets
rowEnd	Device	IN	Buffer with the new row end offsets
colIndices	Device	IN	Buffer with the new column indices
values	Device	IN	Buffer with the new matrix values

See cudssStatus_t for the description of the return status.

---

cudssMatrixGetDn

cudssStatus_t
cudssMatrixGetDn(cudssMatrix_t   matrix,
                 int64_t*        nrows,
                 int64_t*        ncols,
                 int64_t*        ld,
                 void**          values,
                 cudaDataType_t* valueType,
                 cudssLayout_t*  layout)

The function retrieves dense matrix properties and data from a cuDSS matrix object which holds a dense matrix. If on input any of the pointers is NULL, it is ignored and the corresponding value is not returned.

Parameter	Memory	In/Out	Description	Possible Values
matrix	Host	IN	cuDSS matrix object
nrows	Host	OUT	Buffer for the number of rows	Ignored if NULL
ncols	Host	OUT	Buffer for the number of columns	Ignored if NULL
ld	Host	OUT	Buffer for the leading dimension	Ignored if NULL
values	Device	OUT	Buffer for the values of the matrix	Ignored if NULL
valueType	Host	OUT	Buffer for the data type of the matrix	CUDA_R_32F, CUDA_R_64F, CUDA_C_32F, CUDA_C_64F Ignored if NULL
layout	Host	OUT	Buffer for the memory layout	Ignored if NULL

See cudssStatus_t for the description of the return status.

---

cudssMatrixGetCsr

cudssStatus_t
cudssMatrixGetCsr(cudssMatrix_t*        matrix,
                  int64_t*              nrows,
                  int64_t*              ncols,
                  int64_t*              nnz,
                  void**                rowStart,
                  void**                rowEnd,
                  void**                colIndices,
                  void**                values,
                  cudaDataType_t*       indexType,
                  cudaDataType_t*       valueType,
                  cudaMatrixType_t*     mtype,
                  cudaMatrixViewType_t* mview,
                  cudssIndexBase_t*     indexBase)

The function retrieves sparse matrix properties and data from a cuDSS matrix object which holds a CSR sparse matrix. If on input any of the pointers is NULL, it is ignored and the corresponding value is not returned.

Parameter	Memory	In/Out	Description	Possible Values
matrix	Host	IN	Matrix object
nrows	Host	OUT	Buffer for the number of rows	Ignored if NULL
ncols	Host	OUT	Buffer for the number of columns	Ignored if NULL
nnz	Host	OUT	Buffer for the number of non-zeroes	Ignored if NULL
rowStart	Device	OUT	Buffer for the row start offsets	Ignored if NULL
rowEnd	Device	OUT	Buffer for the values of the dense matrix	Must be NULL as 4-array CSR is not supported
colIndices	Device	OUT	Buffer for the column indices of the matrix	Ignored if NULL
values	Device	OUT	Buffer for the values of the dense matrix	Ignored if NULL
indexType	Host	OUT	Buffer for the index type of the matrix	CUDA_R_32I Ignored if NULL
valueType	Host	OUT	Buffer for the data type of the matrix	CUDA_R_32F, CUDA_R_64F, CUDA_C_32F, CUDA_C_64F Ignored if NULL
mtype	Host	OUT	Matrix type of the matrix	See cudssMatrixType_t
mview	Host	OUT	Matrix view of the matrix	See cudssMatrixViewType_t
indexBase	Host	OUT	Buffer for the indexing base	See cudssIndexBase_t Ignored if NULL

See cudssStatus_t for the description of the return status.

---

cudssMatrixGetFormat

cudssStatus_t
cudssMatrixGetFormat(cudssMatrix_t matrix, cudssMatrixFormat_t *format)

The function returns into the provided buffer the matrix format (cudssMatrixFormat_t) of the cuDSS matrix object.

Parameter	Memory	In/Out	Description
matrix	Host	IN	cuDSS matrix object
format	Host	OUT	Buffer for the returned matrix format

See cudssStatus_t for the description of the return status.