Is this page helpful?

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 which take a cudssHandle_t argument. cuDSS functions without a handle argument (e.g. cudssConfigCreate(), cudssMatrixCreateDn(), cudssGetProperty() and the cudssLogger* functions) do not depend on a prior cudssCreate() call. 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. If the function writes a non-NULL *handle, it must be passed to cudssDestroy(), including when this function returns an error.

cudssCreateMg#

cudssStatus_t cudssCreateMg(
cudssHandle_t *handle,
int device_count,
const 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 and device_count > 1, cuDSS uses devices from 0 to device_count - 1 and the calling device must be 0. If device_indices is NULL and device_count == 1, the handle is bound to the calling device. If device_indices is not NULL, the calling device must equal device_indices[0]. Device indices must be unique and in the range 0 to cudaGetDeviceCount() - 1.
Note: The same device_count and device_indices (including order) should be set on the cudssConfig_t via CUDSS_CONFIG_DEVICE_COUNT and CUDSS_CONFIG_DEVICE_INDICES (set DEVICE_COUNT first). If neither of them is set, cudssExecute() uses the handle topology. For multi-GPU handles (device_count > 1), if either of them is set, the resulting count and ordered indices must match the handle. Single-device handles do not enforce this config-vs-handle match.
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 unique device indices. If NULL with device_count > 1, devices 0 to device_count - 1 are used; if NULL with device_count == 1, the calling device is used.

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise. If the function writes a non-NULL *handle, it must be passed to cudssDestroy(), including when this function returns an error. The calling CUDA device is unchanged.

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. A valid handle is consumed once cleanup begins, including when cleanup reports an error. An invalid-argument return does not consume a valid handle.
Parameters:

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

Returns:

[out] The error status of the invocation.

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.
Note: A cudssData_t object is bound to the stream in effect when CUDSS_PHASE_ANALYSIS (or its sub-phases CUDSS_PHASE_REORDERING and CUDSS_PHASE_SYMBOLIC_FACTORIZATION) is executed; all later phases of that object run on that stream. For a single-GPU handle, a stream set with cudssSetStream() after analysis takes effect only when the analysis phase is executed again. For multi-GPU handles see cudssSetMgStreams().
Note: In the multi-GPU (MG) mode, in case the application needs to set non-default streams for cuDSS on each of the devices, there is another function cudssSetMgStreams() specifically for this purpose.
Parameters:

  • handle – [inout] [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.

cudssSetMgStreams#

cudssStatus_t cudssSetMgStreams(
cudssHandle_t handle,
const cudaStream_t *streams,
int stream_count
)#
The function sets per-device streams to be used by the cuDSS library in multi-GPU mode. This function should be used when the library handle was created with cudssCreateMg().
Each stream in the array corresponds to a device specified in cudssCreateMg(). Specifically, streams[i] will be used for operations on device_indices[i].
The stream_count parameter must match the device_count used in cudssCreateMg().
Note: Call this function before the first cudssExecute() with a given cudssData_t. A data object binds the per-device streams at its first execution and keeps using them; streams set afterwards are not used by that object.
Note: User is responsible for creating and destroying these streams. The streams must remain valid for the lifetime of the cuDSS handle. cuDSS will not destroy user-provided streams.
Note: This function is optional. If not called, cuDSS will create and manage its own internal per-device streams for multi-GPU operations.
Parameters:

  • handle – [inout] [host] cuDSS library handle created with cudssCreateMg()

  • streams – [in] [host] Array of CUDA streams, one per device

  • stream_count – [in] [host] Number of streams in the array (must match device_count from cudssCreateMg())

Returns:

[out] The error status of the invocation. Must return CUDSS_STATUS_SUCCESS on success and some other status code otherwise. Returns an error if stream_count does not match the number of devices, if streams is NULL, or if the handle was not created with cudssCreateMg().

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. Detaching returns CUDSS_STATUS_NOT_SUPPORTED while buffers allocated through the current device memory handler are still live.
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 – [inout] [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(
const cudssHandle_t handle,
cudssDeviceMemHandler_t *handler
)#
Get the current device memory handler. Returns CUDSS_STATUS_INVALID_VALUE if no user-defined handler has been set.
Parameters:

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

  • handler – [out] [host] A copy of the device memory handler struct (ctx, the callbacks and name) set via cudssSetDeviceMemHandler(). The user-owned mempool object behind ctx is not copied; the lifetime rule stated for cudssSetDeviceMemHandler() applies

Returns:

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

cudssSetPinnedMemHandler#

cudssStatus_t cudssSetPinnedMemHandler(
cudssHandle_t handle,
const cudssPinnedMemHandler_t *handler
)#
Set the current pinned (page-locked) host memory handler inside the library handle.
If handler argument is set to NULL, the library handle will detach its existing pinned host memory handler from the library handle. In case the pinned host memory handler needs to be changed after it is set for the first time, the previously set pinned host memory handler needs to be detached. Detaching returns CUDSS_STATUS_NOT_SUPPORTED while buffers allocated through the current pinned host memory handler are still live.
The pinned host memory handler is opt-in. If no pinned host memory handler is attached to the library handle, the internal host allocations that would otherwise use it fall back to the plain (non-pinned) host allocations cuDSS used before this API existed, so not setting a handler leaves the default behavior unchanged.
When the pinned host memory handler is set, cuDSS uses it only for the internal host allocations that it chooses to route through the handler (a subset decided internally by cuDSS, not every host allocation cuDSS makes), allocating them with the pinned_alloc() member of the pinned host memory handler struct and releasing them with the pinned_free() member of the struct. pinned_alloc() must return pinned host memory; cuDSS treats the returned pointer as already pinned and does not call cudaHostRegister()/cudaHostUnregister() for it. cudssExecute() returns CUDSS_STATUS_NOT_SUPPORTED if a pinned host memory handler is attached while CUDSS_CONFIG_USE_CUDA_REGISTER_MEMORY is set to 0. cuDSS passes the CUDA stream the data object is bound to (see cudssSetStream()) to both callbacks. See cudssPinnedMemHandler_t for further details about pinned_alloc() and pinned_free().
Note: It is undefined behavior if the library handle is bound to a pinned host memory handler and subsequently to another handler (without detaching), or the library handle outlives the attached memory pool.
Parameters:

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

  • handler – [in] [host] The pinned host 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.

cudssGetPinnedMemHandler#

cudssStatus_t cudssGetPinnedMemHandler(
const cudssHandle_t handle,
cudssPinnedMemHandler_t *handler
)#
Get the current pinned (page-locked) host memory handler. Returns CUDSS_STATUS_INVALID_VALUE if no user-defined handler has been set.
Parameters:

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

  • handler – [out] [host] A copy of the pinned host memory handler struct (ctx, the callbacks and name) set via cudssSetPinnedMemHandler(). The user-owned mempool object behind ctx is not copied; the lifetime rule stated for cudssSetPinnedMemHandler() applies

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.
The communication layer must provide communication backends for both device and host memory buffers.
After setting the communication layer, users should set the device communicator via cudssDataSet()
with CUDSS_DATA_COMM_DEVICE and the host communicator with CUDSS_DATA_COMM_HOST.
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] Library name or path (resolved by the platform dynamic loader, e.g. dlopen / LoadLibrary). If NULL, the name is read from 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] Library name or path (resolved by the platform dynamic loader, e.g. dlopen / LoadLibrary). If NULL, the name is read from CUDSS_THREADING_LIB

Returns:

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

cudssSetJitCacheDir#

cudssStatus_t cudssSetJitCacheDir(
cudssHandle_t handle,
const char *cacheDir
)#
The function sets the directory of the on-disk cache for runtime-compiled kernels for the given library handle, taking precedence over the CUDSS_JIT_CACHE_DIR environment variable. It applies to the kernels compiled or loaded during the analysis phases executed with this handle after the call. Compiled kernels are shared by all handles of a process: a kernel that another handle already compiled or loaded is reused as is, and the directory set here is read when this handle is the first to need a kernel and receives every kernel this handle uses. Like the environment variable, the directory must be writable only by trusted users.
Parameters:

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

  • cacheDir – [in] [host] Directory for the on-disk cache. If NULL, the directory is read from CUDSS_JIT_CACHE_DIR (the default, and the state before the first call). If empty, no on-disk cache is used regardless of the environment.

Returns:

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

Logger API Functions#

Refer to cuDSS Logging Features for overview and environment variables.

Note

Logging API functions are not thread-safe and must not be called concurrently from multiple threads.

cudssLoggerSetCallback#

cudssStatus_t cudssLoggerSetCallback(cudssLoggerCallback_t callback)#
Sets a custom callback function to receive log messages.
The callback is invoked synchronously from the calling thread and must not call any cuDSS API functions (may cause deadlocks).
Parameters:
Returns:

[out] CUDSS_STATUS_SUCCESS on success, or an error status described in Error status

Note

In MGMN mode, each process has its own independent logger state and callback. The callback must be set in each process if needed.

cudssLoggerSetFile#

cudssStatus_t cudssLoggerSetFile(FILE *file)#
Redirects log output to an already-opened file handle.
Pass NULL to disable log output entirely.
Parameters:

  • file – [in] [host] Pointer to open file with write permission, or NULL to disable logging

Returns:

[out] CUDSS_STATUS_SUCCESS on success, or an error status described in Error status

Note

The file handle must remain open until another file is set or logging is disabled. Passing NULL disables all log output until a valid file is set.

Note

In MGMN mode, each process must use a different file handle to avoid corrupted or interleaved output. Multiple processes writing to the same file concurrently is not safe.

cudssLoggerOpenFile#

cudssStatus_t cudssLoggerOpenFile(const char *logFile)#
Opens a file and redirects log output to it. The file is opened in write mode (“w”), truncating any existing content.
Multiple calls automatically close the previous file. Parent directories must exist beforehand.
Parameters:

  • logFile – [in] [host] Path to the log file

Returns:

[out] CUDSS_STATUS_SUCCESS on success, CUDSS_STATUS_INVALID_VALUE if the file cannot be opened, or another error status described in Error status

Note

In MGMN mode, each process must open a different file to avoid corrupted or interleaved output. Multiple processes writing to the same file concurrently is not safe.

cudssLoggerSetLevel#

cudssStatus_t cudssLoggerSetLevel(int level)#
Sets the logging level to control which messages are output.
Parameters:
Returns:

[out] CUDSS_STATUS_SUCCESS on success, CUDSS_STATUS_INVALID_VALUE if the level is invalid, or another error status described in Error status

cudssLoggerSetMask#

cudssStatus_t cudssLoggerSetMask(int mask)#
Sets the logging mask for fine-grained control over which log types are output.
Parameters:
Returns:

[out] CUDSS_STATUS_SUCCESS on success, or an error status described in Error status

cudssLoggerForceDisable#

cudssStatus_t cudssLoggerForceDisable(void)#
Permanently and irreversibly disables all logging for the entire process.
Once called, logging cannot be re-enabled for the lifetime of the process.
Returns:

[out] CUDSS_STATUS_SUCCESS on success, or an error status described in Error status

Note

Once this API is called, disables all existing file sinks and registered callbacks immediately. This API takes precedence over all logging configurations (environment variables, cudssLoggerSetLevel(), cudssLoggerSetMask(), etc.).

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. If the function writes a non-NULL *config, it must be passed to cudssConfigDestroy(), including when this function returns an error.

cudssConfigDestroy#

cudssStatus_t cudssConfigDestroy(cudssConfig_t config)#
The function releases the host resources used by the cuDSS config object. A valid config object is consumed once cleanup begins, including when cleanup reports an error. An invalid-argument return does not consume a valid config object.
Parameters:

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

Returns:

[out] The error status of the invocation.

cudssConfigSet#

cudssStatus_t cudssConfigSet(
cudssConfig_t config,
cudssConfigParam_t param,
const 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(
const 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(
const 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. If the function writes a non-NULL *data, it must be passed to cudssDataDestroy(), including when this function returns an error.

cudssDataDestroy#

cudssStatus_t cudssDataDestroy(cudssHandle_t handle, cudssData_t data)#
The function releases the hardware resources used by the cuDSS data object. A valid data object is consumed once cleanup begins, including when cleanup reports an error. An invalid-argument return does not consume a valid data object.
Parameters:

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

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

Returns:

[out] The error status of the invocation. For multi-GPU data, the calling CUDA device is unchanged.

cudssDataSet#

cudssStatus_t cudssDataSet(
const cudssHandle_t handle,
cudssData_t data,
cudssDataParam_t param,
const 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(
const cudssHandle_t handle,
const 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 data object

  • 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,
const cudssConfig_t config,
cudssData_t data,
const cudssMatrix_t inputMatrix,
cudssMatrix_t solution,
const 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. For multi-GPU execution, the calling CUDA device is unchanged.
After this function returns CUDSS_STATUS_ALLOC_FAILED or CUDSS_STATUS_INTERNAL_ERROR, do not call it again with the same data object. Memory estimates may still be queried; destroy and recreate the data object before retrying.
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. This is not available when CUDSS_MEMORY_OPTIMIZATION_SOLVE_ONLY was set in CUDSS_CONFIG_MEMORY_OPTIMIZATION_SETTING for the preceding factorization: that releases state which a further factorization needs, and cudssExecute() then returns CUDSS_STATUS_NOT_SUPPORTED until CUDSS_PHASE_ANALYSIS is run again.
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 matrix creation and setter routines only store the data pointers and do not check where the data resides. cudssExecute() determines the location of the arrays for which host memory is allowed; pageable, pinned and managed memory are all treated as host memory. The allowed memory locations are:

Matrix data

Non-batch matrix

Batch of matrices

Input sparse matrix (CSR): rowStart, rowEnd, colIndices, values

Device or host memory, independently for each array, in all execution modes. Device memory only with CUDSS_REORDERING_ALG_BTF_COLAMD or CUDSS_REORDERING_ALG_COLAMD reordering, or with uniform batch options enabled.

Device memory only, both for the pointer arrays and for the arrays they point to.

Right-hand side and solution (dense): values

Device memory. Host memory only in the hybrid execute mode, for single-process runs (not MGMN) with nrhs = 1.

Device memory only, both for the pointer arrays and for the arrays they point to.
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 system matrix must be sparse (currently, only 3-array CSR format is supported).

  • Right-hand side and solution matrices must be dense, with column-major layout.

  • 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).

  • During reordering and symbolic factorization, supplied right-hand side and solution descriptors are used for memory estimates and must already have valid shapes. For a non-uniform batch, its count must match the system-matrix batch; the right-hand side column-count and both leading-dimension arrays must be present and contain nonnegative values. Supplied non-batch leading dimensions must be valid for their matrix shapes. The descriptors remain optional during analysis; omitted descriptors use the default estimate for one right-hand side.

  • For the non-uniform input batches, batches with varying shapes are supported. E.g., nrows, ncols, nnz can be different for each batch instance. However, the aggregate number of rows and non-zeroes must be less than INT_MAX.

  • 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. MGMN and MG modes do not support matrix batches.

  • 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

  • inputMatrix – [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,
const 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, unless the hybrid host/device execution mode is enabled (single-process runs with nrhs = 1 only). The function does not check where the data resides; see the allowed memory locations in cudssExecute().
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 (host memory only in the hybrid execute mode)

  • 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. If the function writes a non-NULL *matrix, it must be passed to cudssMatrixDestroy(), including when this function returns an error.

cudssMatrixCreateBatchDn#

cudssStatus_t cudssMatrixCreateBatchDn(
cudssMatrix_t *matrix,
int64_t batchCount,
const void *nrows,
const void *ncols,
const void *ld,
const void *const *values,
cudaDataType_t integerType,
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.
The shape arrays are stored in the matrix descriptor. cudssExecute() validates the arrays when it uses the descriptor during reordering or symbolic factorization.
Note: MGMN and MG modes do 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

  • integerType – [in] [host] Integer 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. If the function writes a non-NULL *matrix, it must be passed to cudssMatrixDestroy(), including when this function returns an error.

cudssMatrixCreateCsr#

cudssStatus_t cudssMatrixCreateCsr(
cudssMatrix_t *matrix,
int64_t nrows,
int64_t ncols,
int64_t nnz,
const void *rowStart,
const void *rowEnd,
const void *colIndices,
const void *values,
cudaDataType_t offsetType,
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 can hold either device or host memory pointers. Passing host memory pointers avoids redundant device-to-host data movements when the data resides on the host.
Note: host memory input for the input matrix is not supported for a batch of matrices (cudssMatrixCreateBatchCsr()), when uniform batch options are enabled, or when CUDSS_REORDERING_ALG_BTF_COLAMD or CUDSS_REORDERING_ALG_COLAMD is used for reordering. The function does not check where the data resides; see the allowed memory locations in cudssExecute().
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 (must be less than \(2^{31}\), regardless of offsetType and indexType)

  • ncols – [in] [host] Number of columns (must be less than \(2^{31}\))

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

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

  • rowEnd – [in] [device/host] Row end offsets

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

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

  • offsetType – [in] [host] Offset type (rowStart and rowEnd) of the 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. If the function writes a non-NULL *matrix, it must be passed to cudssMatrixDestroy(), including when this function returns an error.

cudssMatrixCreateBatchCsr#

cudssStatus_t cudssMatrixCreateBatchCsr(
cudssMatrix_t *matrix,
int64_t batchCount,
const void *nrows,
const void *ncols,
const void *nnz,
const void *const *rowStart,
const void *const *rowEnd,
const void *const *colIndices,
const void *const *values,
cudaDataType_t offsetType,
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.
Note: MGMN and MG modes do 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 (the sum over the batch must be less than INT_MAX)

  • 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 (the sum over the batch must be less than INT_MAX)

  • 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

  • offsetType – [in] [host] Offset type (rowStart and rowEnd) of the matrices in the batch

  • indexType – [in] [host] Index type of the matrices in the batch

  • valueType – [in] [host] Data type of the matrices in the batch

  • 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. If the function writes a non-NULL *matrix, it must be passed to cudssMatrixDestroy(), including when this function returns an error.

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. A valid matrix object is consumed once cleanup begins, including when cleanup reports an error. An invalid-argument return does not consume a valid matrix object.
Parameters:

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

Returns:

[out] The error status of the invocation.

cudssMatrixSetValues#

cudssStatus_t cudssMatrixSetValues(
cudssMatrix_t matrix,
const void *values
)#
The function resets the pointer to values inside the cuDSS matrix object to the provided buffer. For a sparse (CSR) matrix object, the provided data buffer can hold either device or host memory pointers. For a dense matrix object (right-hand side or solution), the provided data buffer must hold device-visible data, unless the hybrid host/device execution mode is enabled (single-process runs with nrhs = 1 only). The function does not check where the data resides; see the allowed memory locations in cudssExecute().
Parameters:

  • matrix – [inout] [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,
const void *const *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 – [inout] [host] cuDSS matrix object

  • values – [in] [device] Pointer to the new values for each 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,
const void *rowStart,
const void *rowEnd,
const void *colIndices,
const void *values
)#
The function resets the CSR pointers inside the cuDSS matrix object to the provided buffers. The provided data buffers for rowStart, rowEnd, colIndices and values can hold either device or host memory pointers, independently for each buffer. See cudssMatrixCreateCsr() for the cases where host memory input is not supported.
Parameters:

  • matrix – [inout] [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,
const void *const *rowStart,
const void *const *rowEnd,
const void *const *colIndices,
const void *const *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 – [inout] [host] cuDSS matrix object

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

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

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

  • values – [in] [device] 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. In this case, the data buffers of the matrix object (rowStart, rowEnd, colIndices and values for CSR, values for dense) may be NULL.

Note: input sparse matrix, right-hand side and solution can have a different (from each other) distribution. For example, only the sparse matrix can be distributed, while right-hand side 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 – [inout] [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(
const 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 the data pointer from a cuDSS matrix object which holds a dense matrix. The values output returns the pointer stored in the matrix object; no matrix data is copied. 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] Pointer to 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(
const cudssMatrix_t matrix,
int64_t *batchCount,
void **nrows,
void **ncols,
void **ld,
void ***values,
cudaDataType_t *integerType,
cudaDataType_t *valueType,
cudssLayout_t *layout
)#
The function retrieves dense matrix properties and data pointers from a cuDSS matrix object which holds a batch of dense matrices. The nrows, ncols, ld and values outputs return the pointers stored in the matrix object; no matrix data is copied. 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

  • integerType – [out] [host] Buffer for the integer type of the scalar arrays (nrows, ncols, ld)

  • 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(
const cudssMatrix_t matrix,
int64_t *nrows,
int64_t *ncols,
int64_t *nnz,
void **rowStart,
void **rowEnd,
void **colIndices,
void **values,
cudaDataType_t *offsetType,
cudaDataType_t *indexType,
cudaDataType_t *valueType,
cudssMatrixType_t *mtype,
cudssMatrixViewType_t *mview,
cudssIndexBase_t *indexBase
)#
The function retrieves sparse matrix properties and data pointers from a cuDSS matrix object which holds a CSR sparse matrix. The rowStart, rowEnd, colIndices and values outputs return the pointers stored in the matrix object; no matrix data is copied. 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] Pointer to the row start offsets

  • rowEnd – [out] [device/host] Pointer to the row end offsets

  • colIndices – [out] [device/host] Pointer to the column indices of the matrix

  • values – [out] [device/host] Pointer to the values of the CSR matrix

  • offsetType – [out] [host] Buffer for the offset type (rowStart and rowEnd) of the 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(
const cudssMatrix_t matrix,
int64_t *batchCount,
void **nrows,
void **ncols,
void **nnz,
void ***rowStart,
void ***rowEnd,
void ***colIndices,
void ***values,
cudaDataType_t *offsetType,
cudaDataType_t *indexType,
cudaDataType_t *valueType,
cudssMatrixType_t *mtype,
cudssMatrixViewType_t *mview,
cudssIndexBase_t *indexBase
)#
The function retrieves sparse matrix properties and data pointers from a cuDSS matrix object which holds a batch of CSR sparse matrices. The nrows, ncols, nnz, rowStart, rowEnd, colIndices and values outputs return the pointers stored in the matrix object; no matrix data is copied. 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

  • offsetType – [out] [host] Buffer for the offset type (rowStart and rowEnd) of the matrices in the batch

  • indexType – [out] [host] Buffer for the index type of the matrices in the batch

  • valueType – [out] [host] Buffer for the data type of the matrices in the batch

  • 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(
const 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 – [out] [host] first row index of the local matrix on the calling process

  • last_row – [out] [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(
const 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.