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.
Parameters:

  • handle – [out] [host] cuDSS library handle

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssCreateMg#

cudssStatus_t cudssCreateMg(
cudssHandle_t *handle,
int device_count,
int *device_indices
)#
The function initializes the cuDSS library handle (cudssHandle_t) which holds the cuDSS library context for multiple devices. Calling any cuDSS function which uses cudssHandle_t without a previous call of cudssCreateMg() will return an error. The cuDSS library context is tied to the CUDA devices defined by device_count number and device_indices array. If device_indices is NULL, cuDSS will take devices from 0 to device_count - 1. The calling device index must be equal to the first device number from device_indices or 0 (if device_indices is NULL)
Note: Same device_count and device_indices must be passed to cudssConfig_t object by calling cudssConfigSet() with CUDSS_CONFIG_DEVICE_COUNT and CUDSS_CONFIG_DEVICE_INDICES.
Limitations: Some of the features are not supported, see MG mode for details.
Parameters:

  • handle – [out] [host] cuDSS library handle

  • device_count – [in] [host] Number of devices

  • device_indices – [in] [host] Integer array of size device_count which stores device indices. If set to NULL, device indices from 0 to device_count - 1 are used.

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • handle – [in] [host] cuDSS library handle

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssGetProperty#

cudssStatus_t cudssGetProperty(
libraryPropertyType propertyType,
int *value
)#
The function returns the value of the requested property. Refer to libraryPropertyType for supported types.
Parameters:

  • propertyType – [in] [host] Requested property

  • value – [out] [host] Value of the requested property

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

The enum libraryPropertyType is defined in library_types.h (standard CUDA header file). The supported subset of values for cuDSS is:
enumerator MAJOR_VERSION#

Enumerator to query the major version

enumerator MINOR_VERSION#

Enumerator to query the minor version

enumerator PATCH_LEVEL#

Number to identify the patch level

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.
Parameters:

  • handle – [in] [host] cuDSS library handle

  • stream – [in] [host] The stream used by the library

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • handle – [in] [host] cuDSS library handle

  • handler – [in] [host] The device memory handler that encapsulates the user’s mempool. The struct content is copied internally

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssGetDeviceMemHandler#

cudssStatus_t cudssGetDeviceMemHandler(
cudssHandle_t handle,
cudssDeviceMemHandler_t *handler
)#
Get the current device memory handler.
Parameters:

  • handle – [in] [host] cuDSS library handle

  • handler – [out] [host] A (deep) copy of the device memory handler that encapsulates the user’s mempool (if it was set) previously via calling cudssSetDeviceMemHandler()

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • handle – [in] [host] cuDSS library handle

  • commLibFileName – [in] [host] 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

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssSetThreadingLayer#

cudssStatus_t cudssSetThreadingLayer(
cudssHandle_t handle,
const char *thrLibFileName
)#
The function sets the threading layer to be used in MT mode of cuDSS. The set threading layer will be used for all MT mode operations where the modified library handle is involved. For more details of when and how this function should be used, see MT mode.
Parameters:

  • handle – [in] [host] cuDSS library handle

  • thrLibFileName – [in] [host] Full filename (including path) to the cuDSS threading layer library If NULL, the threading layer library name is read from the environment variable CUDSS_THREADING_LIB

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • config – [out] [host] cuDSS config object

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • config – [in] [host] cuDSS config object to be destroyed

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • config – [inout] [host] cuDSS config object

  • param – [in] [host] Parameter to be set

  • value – [in] [host] A pointer to the value to be set

  • sizeInBytes – [in] [host] Number of bytes to be read from the pointer

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • config – [in] [host] cuDSS config object

  • param – [in] [host] Parameter to be retrieved from the config

  • value – [out] [host] A pointer to the output memory

  • sizeInBytes – [in] [host] Number of bytes to be written (for verification)

  • sizeWritten – [out] [host] 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

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • handle – [in] [host] cuDSS library handle

  • data – [out] [host] cuDSS data object

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • handle – [in] [host] cuDSS library handle

  • data – [in] [host] cuDSS data object to be destroyed

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • handle – [in] [host] cuDSS library handle

  • data – [inout] [host] cuDSS data object

  • param – [in] [host] Parameter to be set

  • value – [in] [host] A pointer to the value to be set

  • sizeInBytes – [in] [host] Number of bytes to be read from the pointer

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • handle – [in] [host] cuDSS library handle

  • data – [in] [host] cuDSS data object

  • param – [in] [host] Parameter to be retrieved from the config

  • value – [out] [host/device] A pointer to the output memory

  • sizeInBytes – [in] [host] Number of bytes to be written (for verification)

  • sizeWritten – [out] [host] 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

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

Main cuDSS Function#

cudssExecute#

cudssStatus_t cudssExecute(
cudssHandle_t handle,
int 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. Prior to calling cudssExecute(), all objects passed as parameters must already be created and properly initialized.
The simplest possible solution process consists of three main phases, analysis, factorization, and solve, following one another. During the analysis phase, reordering and symbolic factorization (preparing the internal data structures) are done. During the factorization phase, numerical factorization is performed and during the solve phase, the factorization is used to find the solution to the linear system.
The phases must always happen in the following order: CUDSS_PHASE_REORDERING -> CUDSS_PHASE_SYMBOLIC_FACTORIZATION -> CUDSS_PHASE_FACTORIZATION -> (optional) CUDSS_PHASE_REFACTORIZATION -> CUDSS_PHASE_SOLVE. The optional refactorization is usually skipped before the first solve. Re-using the analysis results is supported. Users can change matrix values and only need to run the (re-)factorization and solve phases.
Note: Combining phases is supported as long as the order is followed. As an example, combining CUDSS_PHASE_REORDERING | CUDSS_PHASE_SOLVE will result in an error, while CUDSS_PHASE_ANALYSIS | CUDSS_PHASE_FACTORIZATION is allowed. Please review cudssPhase_t for the full list of phase parameters.

During the execution, the solver configuration properties are read from the config of type cudssConfig_t. The internal data structures necessary to keep all data required for solving the system (incl. the factors) are kept as a part of data object of type cudssData_t. Users can change the configuration settings or provide additional data parameters (e.g. a user permutation) or query extra information (like memory estimates or number of pivots) before/after the phases of the solution process via cudssConfigSet(), or cudssDataGet(), respectively.

The data buffers in the matrix objects for the input matrix, solution and right-hand side matrices must hold device-visible data, unless the hybrid host/device execution mode is enabled.
Note: The function has the following limitations on the cudssMatrix_t objects which can be used as call arguments, in addition to the limitations of the corresponding matrix creation routines (e.g., cudssMatrixCreateCsr()):

  • The input sparse matrix (in the batch case, each matrix in the batch) must have data consistent with its description (incl. offsets and indices, indexing base, matrix type)

  • The input sparse matrix (in the batch case, each matrix in the batch) may have unsorted column indices but must not have repeating entries.

  • The input sparse matrix in CSR format must have its row offsets array start with the indexing base (0 or 1).

  • The input sparse matrix may change for the SOLVE phase (except when hybrid execution mode is used) but for distributed matrices, the range of rows (row distribution) must remain the same.

  • The input sparse matrix, right hand side and solution must have the same datatypes for values and indices (if applicable).

  • For the batched inputs, non-uniform batches with varying shapes are supported. E.g., nrows, ncols, nnz can be different for each batch instance.

  • In MGMN mode all processes must have valid global nrows, ncols, nnz data for sparse matrices and valid global nrows, ncols and local ld for the dense matrices. In the batch case, all processes must additionally have a valid batchCount.

  • If cudssMatrixSetDistributionRow1d() is not used then in MGMN mode full matrix data (for the system’s matrix, solution and right-hand side) must be present on the root process, i.e. process with rank = 0 in the provided communicator. The other processes may have the data pointers set to NULL.

    Otherwise the system’s matrix, solution and right-hand side must be distributed according to the corresponding call to cudssMatrixSetDistributionRow1d().

Note: using the cudssMatrixViewType_t parameter when creating the sparse input matrix (or a batch of those), one can pass only a triangular portion of the matrix without the need to explicitly change the underlying matrix data. E.g., if the mview is set to CUDSS_MVIEW_UPPER, then during the analysis phase, cudssExecute() will ignore all the indices in the lower part of the matrix, even if the underlying matrix storage represents a full matrix.
Parameters:

  • handle – [in] [host] cuDSS library handle

  • phase – [in] [host] Execution phase(s)

  • config – [in] [host] Solver config object

  • data – [inout] [host] Solver data object

  • matrix – [in] [host] Input sparse matrix

  • solution – [inout] [host] Solution matrix

  • rhs – [in] [host] Right-hand side matrix

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Note: In MGMN mode all processes must have valid nrows, ncols and ld.
See more limitations for using cudssMatrix_t objects in the documentation for the main routine, cudssExecute().
Parameters:

  • matrix – [out] [host] Created matrix object

  • nrows – [in] [host] Number of rows

  • ncols – [in] [host] Number of columns

  • ld – [in] [host] Leading dimension

  • values – [in] [device/host] Values of the dense matrix

  • valueType – [in] [host] Data type of the matrix

  • layout – [in] [host] Memory layout

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssMatrixCreateBatchDn#

cudssStatus_t cudssMatrixCreateBatchDn(
cudssMatrix_t *matrix,
int64_t batchCount,
void *nrows,
void *ncols,
void *ld,
void **values,
cudaDataType_t indexType,
cudaDataType_t valueType,
cudssLayout_t layout
)#
The function creates a matrix object wrapped around a batch of dense matrices. The provided data buffer for the matrix values must contain device-visible pointers to device-visible data.
Note: cuDSS supports non-uniform batches with varying shapes, e.g nrows, ncols, ld can be different for each batch instance.
Note: MGMN mode does not support matrix batches.
See more limitations for using cudssMatrix_t objects in the documentation for the main routine, cudssExecute().
Parameters:

  • matrix – [out] [host] Created matrix object

  • batchCount – [in] [host] Size of the batch

  • nrows – [in] [host] Number of rows for each matrix in the batch

  • ncols – [in] [host] Number of columns for each matrix in the batch

  • ld – [in] [host] Leading dimension for each matrix in the batch

  • values – [in] [device] Pointer to values of each dense matrix in the batch

  • indexType – [in] [host] Index type for scalar arrays (nrows, ncols, ld)

  • valueType – [in] [host] Data type of the matrix

  • layout – [in] [host] Memory layout

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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,
cudssMatrixType_t mtype,
cudssMatrixViewType_t mview,
cudssIndexBase_t indexBase
)#
The function creates a matrix object wrapped around sparse matrix data. The provided data buffers for rowStart, rowEnd, colIndices and values must hold device-visible data.
Note: creating a cudssMatrix_t with CSR format does not perform any data consistency checks and thus currently it is the caller’s responsibility to have data description parameters matching the data.
Note: In MGMN mode all processes must have valid nrows, ncols, nnz data (in case of distributed matrices, these should correspond to the global matrix)
See more limitations for using cudssMatrix_t objects in the documentation for the main routine, cudssExecute().
Parameters:

  • matrix – [out] [host] Created matrix object

  • nrows – [in] [host] Number of rows

  • ncols – [in] [host] Number of columns

  • nnz – [in] [host] Number of non-zeroes

  • rowStart – [in] [device/host] Row start offsets

  • rowEnd – [in] [device/host] Values of the dense matrix

  • colIndices – [in] [device/host] Column indices of the matrix

  • values – [in] [device/host] Values of the dense matrix

  • indexType – [in] [host] Index type of the matrix

  • valueType – [in] [host] Data type of the matrix

  • mtype – [in] [host] Matrix type of the matrix

  • mview – [in] [host] Matrix view of the matrix

  • indexBase – [in] [host] Indexing base

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssMatrixCreateBatchCsr#

cudssStatus_t cudssMatrixCreateBatchCsr(
cudssMatrix_t *matrix,
int64_t batchCount,
void *nrows,
void *ncols,
void *nnz,
void **rowStart,
void **rowEnd,
void **colIndices,
void **values,
cudaDataType_t indexType,
cudaDataType_t valueType,
cudssMatrixType_t mtype,
cudssMatrixViewType_t mview,
cudssIndexBase_t indexBase
)#
The function creates a matrix object wrapped around a batch of sparse matrices (CSR format). The provided data buffer for rowStart, rowEnd, colIndices and values must contain device-visible pointers to device-visible data.
Note: cuDSS supports non-uniform batches with varying shapes, e.g nrows, ncols, nnz can be different for each batch instance.
Note: creating a cudssMatrix_t with a batch of matrices in CSR format does not perform any data consistency checks and thus currently it is the caller’s responsibility to have data description parameters matching the data.
See more limitations for using cudssMatrix_t objects in the documentation for the main routine, cudssExecute().
Parameters:

  • matrix – [out] [host] Created matrix object

  • batchCount – [in] [host] Size of the batch

  • nrows – [in] [host] Number of rows for each matrix in the batch

  • ncols – [in] [host] Number of columns for each matrix in the batch

  • nnz – [in] [host] Numbers of non-zeroes for each matrix in the batch

  • rowStart – [in] [device] Pointer to row start offsets for each matrix in the batch

  • rowEnd – [in] [device] Pointer to row end offsets for each matrix in the batch

  • colIndices – [in] [device] Pointer to column indices for each matrix in the batch

  • values – [in] [device] Pointer to values of each CSR matrix in the batch

  • indexType – [in] [host] Index type of the matrix

  • valueType – [in] [host] Data type of the matrix

  • mtype – [in] [host] Matrix type of the matrix

  • mview – [in] [host] Matrix view of the matrix

  • indexBase – [in] [host] Indexing base

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • matrix – [in] [host] cuDSS matrix object

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • matrix – [in] [host] cuDSS matrix object

  • values – [in] [device/host] Buffer with the new matrix values

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssMatrixSetBatchValues#

cudssStatus_t cudssMatrixSetBatchValues(
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 for the matrix values must contain device-visible pointers to device-visible data.
Parameters:

  • matrix – [in] [host] cuDSS matrix object

  • values – [in] [device/host] Pointer to the new values for each dense matrix in the batch

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • matrix – [in] [host] cuDSS matrix object

  • rowStart – [in] [device/host] Buffer with the new row start offsets

  • rowEnd – [in] [device/host] Buffer with the new row end offsets

  • colIndices – [in] [device/host] Buffer with the new column indices

  • values – [in] [device/host] Buffer with the new matrix values

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssMatrixSetBatchCsrPointers#

cudssStatus_t cudssMatrixSetBatchCsrPointers(
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 buffer for rowStart, rowEnd, colIndices and values must contain device-visible pointers to device-visible data.
Parameters:

  • matrix – [in] [host] cuDSS matrix object

  • rowStart – [in] [device/host] Pointer to the new row start offsets for each CSR matrix in the batch

  • rowEnd – [in] [device/host] Pointer to the new row end offsets for each CSR matrix in the batch

  • colIndices – [in] [device/host] Pointer to the new column indices for each CSR matrix in the batch

  • values – [in] [device/host] Pointer to the new values for each CSR matrix in the batch

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssMatrixSetDistributionRow1d#

cudssStatus_t cudssMatrixSetDistributionRow1d(
cudssMatrix_t matrix,
int64_t *first_row,
int64_t *last_row
)#
The function sets the 1D distribution for the matrix (CSR or Dense) for the MGMN mode. The provided first_row and last_row must be always 0-based and specify the first and the last (included) row indices of the local matrix on the calling process. Setting first_row > last_row means that the local matrix is empty for the calling process.

Note: input sparse matrix, right-hand-size and solution can have a different (from each other) distribution. For example, only the sparse matrix can be distributed, while right-hand-size or solution are not.

Note: if the sparse matrix or right-hand side are distributed with an overlap (between processes) then the overlapped part will be summed up, that is the overlapped part will have a contribution from all related processes. if the solution is distributed with overlapping (between processes) then the overlapped part will have the same values on corresponding processes.

Parameters:

  • matrix – [in] [host] cuDSS matrix object

  • first_row – [in] [host] first row index of the local matrix on the calling process

  • last_row – [in] [host] last row index of the local matrix on the calling process

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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.
Parameters:

  • matrix – [in] [host] cuDSS matrix object

  • nrows – [out] [host] Buffer for the number of rows

  • ncols – [out] [host] Buffer for the number of columns

  • ld – [out] [host] Buffer for the leading dimension

  • values – [out] [device/host] Buffer for the values of the matrix

  • valueType – [out] [host] Buffer for the data type of the matrix

  • layout – [out] [host] Buffer for the memory layout

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssMatrixGetBatchDn#

cudssStatus_t cudssMatrixGetBatchDn(
cudssMatrix_t matrix,
int64_t *batchCount,
void **nrows,
void **ncols,
void **ld,
void ***values,
cudaDataType_t *indexType,
cudaDataType_t *valueType,
cudssLayout_t *layout
)#
The function retrieves dense matrix properties and data from a cuDSS matrix object which holds a batch of dense matrices. If on input any of the pointers is NULL, it is ignored and the corresponding value is not returned.
Parameters:

  • matrix – [in] [host] cuDSS matrix object

  • batchCount – [out] [host] Buffer for the size of the batch

  • nrows – [out] [host] Pointer to the number of rows for each dense matrix in the batch

  • ncols – [out] [host] Pointer to the number of columns for dense matrix in the batch

  • ld – [out] [host] Pointer to the leading dimension for each dense matrix in the batch

  • values – [out] [device] Pointer to the values of each dense matrix in the batch

  • indexType – [out] [host] Buffer for the index type of the matrix

  • valueType – [out] [host] Buffer for the data type of the matrix

  • layout – [out] [host] Buffer for the memory layout

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

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,
cudssMatrixType_t *mtype,
cudssMatrixViewType_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.
Parameters:

  • matrix – [in] [host] Matrix object

  • nrows – [out] [host] Buffer for the number of rows

  • ncols – [out] [host] Buffer for the number of columns

  • nnz – [out] [host] Buffer for the number of non-zeroes

  • rowStart – [out] [device/host] Buffer for the row start offsets

  • rowEnd – [out] [device/host] Buffer for the row end offsets

  • colIndices – [out] [device/host] Buffer for the column indices of the matrix

  • values – [out] [device/host] Buffer for the values of the CSR matrix

  • indexType – [out] [host] Buffer for the index type of the matrix

  • valueType – [out] [host] Buffer for the data type of the matrix

  • mtype – [out] [host] Matrix type of the matrix

  • mview – [out] [host] Matrix view of the matrix

  • indexBase – [out] [host] Buffer for the indexing base

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssMatrixGetBatchCsr#

cudssStatus_t cudssMatrixGetBatchCsr(
cudssMatrix_t *matrix,
int64_t *batchCount,
void **nrows,
void **ncols,
void **nnz,
void ***rowStart,
void ***rowEnd,
void ***colIndices,
void ***values,
cudaDataType_t *indexType,
cudaDataType_t *valueType,
cudssMatrixType_t *mtype,
cudssMatrixViewType_t *mview,
cudssIndexBase_t *indexBase
)#
The function retrieves sparse matrix properties and data from a cuDSS matrix object which holds a batch of CSR sparse matrices. If on input any of the pointers is NULL, it is ignored and the corresponding value is not returned.
Parameters:

  • matrix – [in] [host] Matrix object

  • batchCount – [out] [host] Buffer for the size of the batch

  • nrows – [out] [host] Pointer to the number of rows for each CSR matrix in the batch

  • ncols – [out] [host] Pointer to the number of columns for each CSR matrix in the batch

  • nnz – [out] [host] Pointer to the number of non-zeroes for each CSR matrix in the batch

  • rowStart – [out] [device] Pointer to the row start offsets for each CSR matrix in the batch

  • rowEnd – [out] [device] Pointer to the row end offsets for each CSR matrix in the batch

  • colIndices – [out] [device] Pointer to the column indices for each CSR matrix in the batch

  • values – [out] [device] Pointer to the values for each CSR matrix in the batch

  • indexType – [out] [host] Buffer for the index type of the matrix

  • valueType – [out] [host] Buffer for the data type of the matrix

  • mtype – [out] [host] Matrix type of the matrix

  • mview – [out] [host] Matrix view of the matrix

  • indexBase – [out] [host] Buffer for the indexing base

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssMatrixGetDistributionRow1d#

cudssStatus_t cudssMatrixGetDistributionRow1d(
cudssMatrix_t matrix,
int64_t *first_row,
int64_t *last_row
)#
The function retrieves 1D distribution boundaries (first and last row indices) from a cuDSS matrix object. For the non-MGMN mode the function returns first_row equals to 0 and last_row equal to nrows - 1.
Parameters:

  • matrix – [in] [host] cuDSS matrix object

  • first_row – [in] [host] first row index of the local matrix on the calling process

  • last_row – [in] [host] last row index of the local matrix on the calling process

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.

cudssMatrixGetFormat#

cudssStatus_t cudssMatrixGetFormat(cudssMatrix_t matrix, int *format)#
The function returns into the provided buffer the matrix format (as an int which can be a combination of bit flags defined in cudssMatrixFormat_t) of the cuDSS matrix object.
Parameters:

  • matrix – [in] [host] cuDSS matrix object

  • format – [out] [host] Buffer for the returned matrix format

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise.