### Basic Host Timer Implementation

Source: https://docs.nvidia.com/cuda/cudss/performance_code.html

A simple host-side timer function using `gettimeofday` to measure elapsed time in seconds. This is a crude example and may not be suitable for high-precision benchmarking.

```c
static double second(void) {
 struct timeval tv;
 gettimeofday(&tv, NULL);
 return (double)tv.tv_sec + (double)tv.tv_usec / 1000000.0;
}
```

--------------------------------

### cudssMatrixGetFormat

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Gets the format of a matrix.

```APIDOC
## cudssMatrixGetFormat

### Description
Gets the format of a matrix.

### Function Signature
```c
nvStatus_t cudssMatrixGetFormat(
    cudssMatrix_t matrix,
    cudssMatrixFormat_t *format
);
```

### Parameters
#### Path Parameters
- `matrix` (*cudssMatrix_t*)
- `format` (*cudssMatrixFormat_t *)

```

--------------------------------

### cudssMatrixGetDn

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Gets the dense data for a matrix.

```APIDOC
## cudssMatrixGetDn

### Description
Gets the dense data for a matrix.

### Function Signature
```c
nvStatus_t cudssMatrixGetDn(
    cudssMatrix_t matrix,
    int *rows,
    int *cols,
    void **values
);
```

### Parameters
#### Path Parameters
- `matrix` (*cudssMatrix_t*)
- `rows` (*int*)
- `cols` (*int*)
- `values` (*void **)
```

--------------------------------

### Compile cuDSS Sample Code (Shared Library) on Windows

Source: https://docs.nvidia.com/cuda/cudss/getting_started.html

Compile a C++ sample file using nvcc, linking against cuDSS and cuBLAS as shared libraries. Ensure cuDSS and CUDA Toolkit are installed and their paths are correctly set.

```bash
nvcc.exe cudss_simple.cpp -I "%CUDSS_DIR%\include" -lcudss -lcublas -o cudss_simple.exe
```

--------------------------------

### Compile cuDSS Sample with Shared Library

Source: https://docs.nvidia.com/cuda/cudss/getting_started.html

Compile a C++ sample using nvcc, linking against the shared cuDSS and cuBLAS libraries. Ensure cuDSS and CUDA Toolkit are installed and their paths are correctly set.

```bash
nvcc cudss_simple.cpp -I${CUDSS_DIR}/include -L${CUDSS_DIR}/lib -lcudss -lcublas -o cudss_simple
```

--------------------------------

### cudssMatrixGetBatchDn

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Gets the dense data for a batch matrix.

```APIDOC
## cudssMatrixGetBatchDn

### Description
Gets the dense data for a batch matrix.

### Function Signature
```c
nvStatus_t cudssMatrixGetBatchDn(
    cudssMatrix_t matrix,
    int *rows,
    int *cols,
    int *batch_size,
    void **values
);
```

### Parameters
#### Path Parameters
- `matrix` (*cudssMatrix_t*)
- `rows` (*int*)
- `cols` (*int*)
- `batch_size` (*int*)
- `values` (*void **)
```

--------------------------------

### Check Threading Layer in cuDSS MT Mode

Source: https://docs.nvidia.com/cuda/cudss/tips_and_tricks.html

This example demonstrates how to check the threading layer for cuDSS MT mode. It is useful when dealing with multi-threaded issues.

```c++
#include <omp.h>
#include <stdio.h>

int main() {
    int num_threads = omp_get_num_threads();
    printf("Number of threads: %d\n", num_threads);
    return 0;
}
```

--------------------------------

### Basic cuDSS Workflow for Solving Sparse Linear Systems

Source: https://docs.nvidia.com/cuda/cudss/getting_started.html

Demonstrates the fundamental steps to solve a sparse linear system using cuDSS. This includes initialization, configuration, analysis, factorization, and solving phases. Ensure necessary headers and data structures are defined.

```c++
#include <cudss.h> // cuDSS header

// Device pointers and scalar shape parameters, matrix properties
int* rowOffsets = ...
int* colIndices = ...
double* values = ...
double* bvalues = ...
double* xvalues = ...

//---------------------------------------------------------------------------------
// cuDSS data structures and handle initialization
cudssHandle_t handle;
cudssConfig_t config;
cudssData_t data;
cudssMatrix_t A;
cudssMatrix_t b;
cudssMatrix_t x;

cudssCreate(&handle);

cudssConfigCreate(&config);
cudssDataCreate(handle, &data);
cudssMatrixCreateCsr(&A, ... rowOffsets, colIndices, values, ...);
cudssMatrixCreateDn(&b, ... bvalues, ...);
cudssMatrixCreateDn(&x, ... xvalues, ...);

//---------------------------------------------------------------------------------
// (optional) Modifying solver settings, e.g., reordering algorithm
cudssAlgType_t reorder_alg = CUDSS_ALG_DEFAULT;
cudssConfigSet(config, CUDSS_REORDERING_ALG, &reorder_alg, sizeof(cudssAlgType_t));

//---------------------------------------------------------------------------------
// Reordering & symbolic factorization
cudssExecute(handle, CUDSS_PHASE_ANALYSIS, config, data, A, x, b);

//---------------------------------------------------------------------------------
// Numerical factorization
cudssExecute(handle, CUDSS_PHASE_FACTORIZATION, config, data, A, x, b);

//---------------------------------------------------------------------------------
// Solving the system
cudssExecute(handle, CUDSS_PHASE_SOLVE, config, data, A, x, b);

//---------------------------------------------------------------------------------
// (optional) Extra data can be retrieved from the cudssData_t object
// For example, diagonal of the factorized matrix or the reordering permutation

//---------------------------------------------------------------------------------
// Destroy the opaque objects
cudssConfigDestroy(config);
cudssDataDestroy(handle, data);
cudssMatrixDestroy(A);
cudssMatrixDestroy(x);
cudssMatrixDestroy(b);
cudssDestroy(handle);

//---------------------------------------------------------------------------------
// The solution of the system can now be accessed via the user-allocated device
// pointer xvalues

// ...

```

--------------------------------

### cudssMatrixGetCsr

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Gets the CSR data for a matrix.

```APIDOC
## cudssMatrixGetCsr

### Description
Gets the CSR data for a matrix.

### Function Signature
```c
nvStatus_t cudssMatrixGetCsr(
    cudssMatrix_t matrix,
    int *rows,
    int *cols,
    void **values,
    int **row_ptr,
    int **col_ind
);
```

### Parameters
#### Path Parameters
- `matrix` (*cudssMatrix_t*)
- `rows` (*int*)
- `cols` (*int*)
- `values` (*void **)
- `row_ptr` (*int **)
- `col_ind` (*int **)
```

--------------------------------

### Compile cuDSS Sample with Static Library

Source: https://docs.nvidia.com/cuda/cudss/getting_started.html

Compile a C++ sample linking against static versions of cuDSS and cuBLAS libraries. This requires specifying the full path to the static library files using -Xlinker flags.

```bash
nvcc cudss_simple.cpp -I${CUDSS_DIR}/include \
 -Xlinker=${CUDSS_DIR}/lib/libcudss_static.a \
 -Xlinker=${CTK_DIR}/lib64/libcublas_static.a \
 -Xlinker=${CTK_DIR}/lib64/libcublasLt_static.a \
 -Xlinker=${CTK_DIR}/lib64/libculibos.a \
 -o cudss_simple_static
```

--------------------------------

### cudssConfigCreate

Source: https://docs.nvidia.com/cuda/cudss/functions.html

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.

```APIDOC
## cudssConfigCreate

### Description
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.

### Signature
`cudssStatus_t cudssConfigCreate(cudssConfig_t* config)`

### 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.

### Notes
To release the allocated memory, [`cudssConfigDestroy()`](https://docs.nvidia.com/cuda/cudss/functions.html.md#c.cudssConfigDestroy "cudssConfigDestroy") must be called.
```

--------------------------------

### cudssMatrixGetDistributionRow1d

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Gets the 1D distribution of rows for a matrix.

```APIDOC
## cudssMatrixGetDistributionRow1d

### Description
Gets the 1D distribution of rows for a matrix.

### Function Signature
```c
nvStatus_t cudssMatrixGetDistributionRow1d(
    cudssMatrix_t matrix,
    int *row_dist
);
```

### Parameters
#### Path Parameters
- `matrix` (*cudssMatrix_t*)
- `row_dist` (*int *)

```

--------------------------------

### Compile cuDSS Sample Code (Static Library) on Windows

Source: https://docs.nvidia.com/cuda/cudss/getting_started.html

Compile a C++ sample file using nvcc, linking against cuDSS and cuBLAS as static libraries. This requires specific linker flags to ensure all necessary code is included.

```bash
nvcc.exe cudss_simple.cpp -I %CUDSS_DIR%\include \
 -Xlinker=/WHOLEARCHIVE:"%CUDSS_DIR%\lib\cudss.lib" \
 -Xlinker=/WHOLEARCHIVE:"%CTK_DIR%\lib\x64\cublas.lib" \
 -Xlinker=/FORCE -o cudss_simple_static.exe
```

--------------------------------

### cudssMatrixGetBatchCsr

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Gets the CSR data for a batch matrix.

```APIDOC
## cudssMatrixGetBatchCsr

### Description
Gets the CSR data for a batch matrix.

### Function Signature
```c
nvStatus_t cudssMatrixGetBatchCsr(
    cudssMatrix_t matrix,
    int *rows,
    int *cols,
    int *batch_size,
    void **values,
    int **row_ptr,
    int **col_ind
);
```

### Parameters
#### Path Parameters
- `matrix` (*cudssMatrix_t*)
- `rows` (*int*)
- `cols` (*int*)
- `batch_size` (*int*)
- `values` (*void **)
- `row_ptr` (*int **)
- `col_ind` (*int **)
```

--------------------------------

### cudssDistributedInterface_t.cudssCommSize

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Gets the size (number of processes) of a communicator.

```APIDOC
## cudssDistributedInterface_t.cudssCommSize

### Description
Gets the size of a communicator.

### Function Signature
`cudssError_t cudssDistributedInterface_t::cudssCommSize(cudssComm_t comm, int *size)`

### Parameters
*   **comm** (cudssComm_t) - The communicator.
*   **size** (int *) - Pointer to store the size.
```

--------------------------------

### cudssMatrixCreateBatchDn

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Creates a batch of dense matrices.

```APIDOC
## cudssMatrixCreateBatchDn

### Description
Creates a batch of dense matrices.

### Function Signature
`cudssError_t cudssMatrixCreateBatchDn(cudssHandle_t handle, int n, int m, int batch_size, cudssLayout_t layout, cudssMatrix_t *matrix)`

### Parameters
*   **handle** (cudssHandle_t) - The handle of the CUDSS library.
*   **n** (int) - The number of rows in each matrix.
*   **m** (int) - The number of columns in each matrix.
*   **batch_size** (int) - The number of matrices in the batch.
*   **layout** (cudssLayout_t) - The memory layout (CUDSS_LAYOUT_ROW_MAJOR or CUDSS_LAYOUT_COL_MAJOR).
*   **matrix** (cudssMatrix_t *) - Pointer to store the created dense matrix.
```

--------------------------------

### cudssDistributedInterface_t.cudssCommRank

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Gets the rank of the calling process within a communicator.

```APIDOC
## cudssDistributedInterface_t.cudssCommRank

### Description
Gets the rank of the calling process within a communicator.

### Function Signature
`cudssError_t cudssDistributedInterface_t::cudssCommRank(cudssComm_t comm, int *rank)`

### Parameters
*   **comm** (cudssComm_t) - The communicator.
*   **rank** (int *) - Pointer to store the rank.
```

--------------------------------

### Get Number of Perturbed Pivots with cudssDataGet

Source: https://docs.nvidia.com/cuda/cudss/tips_and_tricks.html

Use cudssDataGet with CUDSS_DATA_NPIVOTS to retrieve the count of perturbed pivots during factorization. This can indicate if a matrix is not well-conditioned.

```c
cudssDataGet(handle, CUDSS_DATA_NPIVOTS, &npivots);
```

--------------------------------

### cudssCreate

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Creates an instance of the cuDSS library. This is typically the first step before using other cuDSS functionalities.

```APIDOC
## cudssCreate

### Description
Creates an instance of the cuDSS library.

### Function Signature
```c

```

### Parameters
(No specific parameters are detailed in the source for this function.)

### Return Value
(The return value is not explicitly detailed in the source, but likely returns a handle to the cuDSS instance.)

### Usage Example
(No usage example is provided in the source.)
```

--------------------------------

### Enable Pivoting Epsilon Scaling with cudssConfigSet

Source: https://docs.nvidia.com/cuda/cudss/tips_and_tricks.html

Enable automatic scaling of the pivoting epsilon for better accuracy with matrices of varying magnitudes by using cudssConfigSet with CUDSS_CONFIG_PIVOT_EPSILON_ALG.

```c
cudssConfigSet(handle, CUDSS_CONFIG_PIVOT_EPSILON_ALG, &pivot_epsilon_alg);
```

--------------------------------

### cudssCreate

Source: https://docs.nvidia.com/cuda/cudss/functions.html

Initializes the cuDSS library handle, which holds the library context. This function must be called before any other cuDSS library calls.

```APIDOC
## cudssCreate

### Description
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. 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
#### Path Parameters
- **handle** (cudssHandle_t*) - Output - cuDSS library handle

### Returns
- **cudssStatus_t** - The error status of the invocation. Must return `CUDSS_STATUS_SUCCESS` on success and some other status code otherwise.
```

--------------------------------

### Matrix Creation and Manipulation Functions

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Functions for creating, destroying, and modifying sparse and dense matrices in various formats.

```APIDOC
## cudssMatrixCreateBatchCsr

### Description
Creates a batch of CSR matrices.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixCreateBatchDn

### Description
Creates a batch of dense matrices.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixCreateCsr

### Description
Creates a CSR matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixCreateDn

### Description
Creates a dense matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixDestroy

### Description
Destroys a cuDSS matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixGetBatchCsr

### Description
Retrieves the CSR data from a batch matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixGetBatchDn

### Description
Retrieves the dense data from a batch matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixGetCsr

### Description
Retrieves the CSR data from a matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixGetDistributionRow1d

### Description
Gets the 1D row distribution of a matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixGetDn

### Description
Retrieves the dense data from a matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixGetFormat

### Description
Gets the format of a cuDSS matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixSetBatchCsrPointers

### Description
Sets the CSR data pointers for a batch matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

```APIDOC
## cudssMatrixSetBatchValues

### Description
Sets the values for a batch matrix.

### Method
C function

### Endpoint
n/a

### Parameters
None explicitly documented.

### Request Example
None provided.

### Response
None explicitly documented.
```

--------------------------------

### Enable Matching and Scaling with cudssConfigSet

Source: https://docs.nvidia.com/cuda/cudss/tips_and_tricks.html

Improve accuracy by enabling matrix matching and scaling. Use cudssConfigSet with CUDSS_CONFIG_USE_MATCHING and CUDSS_CONFIG_MATCHING_ALG.

```c
cudssConfigSet(handle, CUDSS_CONFIG_USE_MATCHING, &use_matching);
```

```c
cudssConfigSet(handle, CUDSS_CONFIG_MATCHING_ALG, &matching_alg);
```

--------------------------------

### Compile cuDSS Sample with Shared Library (pip wheels)

Source: https://docs.nvidia.com/cuda/cudss/getting_started.html

When using pip wheels, replace -lcudss with -l:libcudss.so.0 due to limitations with symlinks in wheels. This command links the shared cuDSS library.

```bash
nvcc cudss_simple.cpp -I${CUDSS_DIR}/include -L${CUDSS_DIR}/lib -l:libcudss.so.0 -lcublas -o cudss_simple
```

--------------------------------

### Set cuDSS and CUDA Library Paths

Source: https://docs.nvidia.com/cuda/cudss/getting_started.html

Update LD_LIBRARY_PATH to include cuDSS and CUDA Toolkit library directories for runtime access. Ensure CUDSS_DIR and CTK_DIR environment variables are set.

```bash
export LD_LIBRARY_PATH=${CUDSS_DIR}/lib:${CTK_DIR}/lib64:${LD_LIBRARY_PATH}
```

--------------------------------

### cudssConfigCreate

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Creates a configuration object for cuDSS operations. This object holds various settings that control the behavior of cuDSS algorithms.

```APIDOC
## cudssConfigCreate

### Description
Creates a configuration object for cuDSS operations.

### Method
C Function

### Endpoint
n/a

### Parameters
None explicitly documented in the provided text.

### Request Example
```c
// Example usage not provided in source.
```

### Response
None explicitly documented in the provided text.
```

--------------------------------

### cudssMatrixCreateDn

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Creates a dense matrix descriptor.

```APIDOC
## cudssMatrixCreateDn

### Description
Creates a dense matrix descriptor.

### Function Signature
```c
nvStatus_t cudssMatrixCreateDn(
    cudssMatrix_t *matrix,
    int rows,
    int cols,
    cudssMatrixFormat_t format
);
```

### Parameters
#### Path Parameters
- `matrix` (*cudssMatrix_t*)
- `rows` (*int*)
- `cols` (*int*)
- `format` (*cudssMatrixFormat_t*)
```

--------------------------------

### cudssMatrixCreateBatchDn

Source: https://docs.nvidia.com/cuda/cudss/functions.html

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.

```APIDOC
## cudssMatrixCreateBatchDn

### Description
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()`](https://docs.nvidia.com/cuda/cudss/functions.html.md#c.cudssExecute "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.
```

--------------------------------

### cudssCreateMg

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Creates a handle to the cuDSS multi-grid solver. This function is used for initializing the multi-grid solver functionality.

```APIDOC
## cudssCreateMg

### Description
Creates a handle to the cuDSS multi-grid solver.

### Function Signature
```c
void cudssCreateMg(cudssHandle_t *handle)
```

### Parameters
*   **handle** (cudssHandle_t *) - Pointer to a location where the cuDSS multi-grid solver handle will be stored.

### Remarks
This function initializes the multi-grid solver component of the cuDSS library. The returned handle is specific to the multi-grid solver and should be destroyed using `cudssDestroy`.
```

--------------------------------

### cudssDeviceMemHandler_t.device_alloc

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Allocates memory on the device using the provided handler.

```APIDOC
## cudssDeviceMemHandler_t.device_alloc

### Description
Allocates memory on the device using the provided handler.

### Method
C Function

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### cudssCreate

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Creates a handle to the cuDSS library. This is typically the first function called when using the cuDSS library.

```APIDOC
## cudssCreate

### Description
Creates a handle to the cuDSS library.

### Function Signature
```c
void cudssCreate(cudssHandle_t *handle)
```

### Parameters
*   **handle** (cudssHandle_t *) - Pointer to a location where the cuDSS library handle will be stored.

### Remarks
This function initializes the cuDSS library and returns a handle that must be used in subsequent cuDSS function calls. The handle should be destroyed using `cudssDestroy` when no longer needed.
```

--------------------------------

### Set cuDSS and CUDA Library Paths on Windows

Source: https://docs.nvidia.com/cuda/cudss/getting_started.html

Update the system's PATH environment variable to include the cuDSS and CUDA Toolkit library directories. This is necessary for the compiler and linker to find the required libraries.

```batch
setx PATH "%CUDSS_DIR%\lib:%CTK_DIR%\lib64:%PATH%"
```

--------------------------------

### cudssCreateMg

Source: https://docs.nvidia.com/cuda/cudss/functions.html

Initializes the cuDSS library handle for multiple devices. This function is used when cuDSS needs to operate across several CUDA devices.

```APIDOC
## cudssCreateMg

### Description
Initializes the cuDSS library handle (`cudssHandle_t`) which holds the cuDSS library context for multiple devices. 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`).

### Parameters
#### Path Parameters
- **handle** (cudssHandle_t*) - Output - cuDSS library handle
- **device_count** (int) - Input - Number of devices
- **device_indices** (int*) - Input - 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
- **cudssStatus_t** - The error status of the invocation. Must return `CUDSS_STATUS_SUCCESS` on success and some other status code otherwise.
```

--------------------------------

### Compute Relative Residual Norm for Accuracy

Source: https://docs.nvidia.com/cuda/cudss/tips_and_tricks.html

This code sample shows how to compute the relative norm of the residual to measure the accuracy of solving a linear system. It mixes device and host code.

```c++
// Example of how to compute the relative norm of the residual
// with a mixture of device and host code.
// See the residual code sample: https://github.com/NVIDIA/CUDALibrarySamples/tree/master/cuDSS/simple_residual/simple_residual.cu
```

--------------------------------

### cudssMatrixCreateBatchCsr

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Creates a batch of CSR (Compressed Sparse Row) matrices.

```APIDOC
## cudssMatrixCreateBatchCsr

### Description
Creates a batch of CSR matrices.

### Function Signature
`cudssError_t cudssMatrixCreateBatchCsr(cudssHandle_t handle, int n, int m, int nnz, int batch_size, cudssIndexBase_t index_base, cudssMatrix_t *matrix)`

### Parameters
*   **handle** (cudssHandle_t) - The handle of the CUDSS library.
*   **n** (int) - The number of rows in each matrix.
*   **m** (int) - The number of columns in each matrix.
*   **nnz** (int) - The total number of non-zero elements across all matrices in the batch.
*   **batch_size** (int) - The number of matrices in the batch.
*   **index_base** (cudssIndexBase_t) - The index base (CUDSS_BASE_ZERO or CUDSS_BASE_ONE).
*   **matrix** (cudssMatrix_t *) - Pointer to store the created CSR matrix.
```

--------------------------------

### cudssCommSplit

Source: https://docs.nvidia.com/cuda/cudss/types.html

Creates new communicators based on colors and keys.

```APIDOC
## cudssCommSplit

### Description
A function pointer to a routine which creates new communicators based on colors and keys.

### Method
C Function

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **comm** (*const void*") - A pointer to the communicator to be split.
- **color** (*int*) - Control of the subset assignment. Processes with the same color are grouped together.
- **key** (*int*) - Control of the rank assignment. Processes in the new communicator are ordered based on the keys.
- **new_comm** (*void*") - A pointer to the new communicator defined w.r.t to colors.

### Returns
- **int** - The error status of the invocation. Must return 0 on success and any nonzero integer otherwise.
```

--------------------------------

### Load cuDSS Communication Library

Source: https://docs.nvidia.com/cuda/cudss/commlayer_simulation_code.html

Dynamically load the communication layer library using dlopen and resolve the 'cudssDistributedInterface' symbol using dlsym. Ensure error handling for library loading and symbol resolution.

```c++
#include <dlfcn.h> // required for dlopen and dlsym

cudssDistributedInterface_t *commIface;

void *commIfaceLib = NULL;

char *libname = <path to the communication layer library>;

commIfaceLib = static_cast<void*>(dlopen(libname, RTLD_NOW));

if (commIfaceLib == NULL) { /* bad */ }

commIface = (cudssDistributedInterface_t*)dlsym(commIfaceLib,
 "cudssDistributedInterface");

if (commIface == NULL) { /* bad */ }

commIface->cudssBcast(...);
```

--------------------------------

### CUDSS Call and Check with Timing Macro

Source: https://docs.nvidia.com/cuda/cudss/performance_code.html

A macro for executing cuDSS calls with optional warm-up iterations and performance run measurements. It includes timing logic and prints the execution time. Use for profiling specific cuDSS phases.

```c
#define CUDSS_CALL_AND_CHECK_TIME(call, status, msg, func_name, WARM_UP, 
PERF_RUN) \
 do { \
 if (WARM_UP) { \
 status = call; \
 if (status != CUDSS_STATUS_SUCCESS) { \
 printf("CUDSS call ended unsuccessfully with status = %d, " \
 "details: " #msg "\n", \
 status); \
 } \
 } \
 cudaDeviceSynchronize(); \
 start_time = second(); \
 for (int i = 0; i < (PERF_RUN ? nrun : 1); i++) { \
 status = call; \
 if (status != CUDSS_STATUS_SUCCESS) { \
 printf("CUDSS call ended unsuccessfully with status = %d, " \
 "details: " #msg "\n", \
 status); \
 } \
 } \
 cudaDeviceSynchronize(); \
 double tmp_t_ = (second() - start_time) / (PERF_RUN ? nrun : 1); \
 if (rank == 0) { \
 printf("%s: time = %1.8f\n", func_name, tmp_t_); \
 fflush(0); \
 } \
 } while (0);
```

--------------------------------

### cudssMatrixCreateDn

Source: https://docs.nvidia.com/cuda/cudss/functions.html

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

```APIDOC
## cudssMatrixCreateDn

### Description
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()`](https://docs.nvidia.com/cuda/cudss/functions.html.md#c.cudssExecute "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.
```

--------------------------------

### cudssExecute

Source: https://docs.nvidia.com/cuda/cudss/functions.html

Executes a phase of the sparse matrix solution process. This function is used to perform analysis, factorization, or solve steps within the CUdS library. Ensure all input objects are properly initialized before calling.

```APIDOC
## cudssExecute

### Description
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.

### Method
`cudssStatus_t cudssExecute(cudssHandle_t handle, int phase, cudssConfig_t config, cudssConfig_t data, cudssMatrix_t matrix, cudssMatrix_t solution, cudssMatrix_t rhs)`

### Parameters

#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* **handle** (`cudssHandle_t`) - Handle to the CUdS library context.
* **phase** (`int`) - The phase of the solution process to execute (e.g., analysis, factorization, solve).
* **config** (`cudssConfig_t`) - Configuration object for the solver.
* **data** (`cudssConfig_t`) - Data object to store intermediate results and solver state.
* **matrix** (`cudssMatrix_t`) - The input sparse matrix.
* **solution** (`cudssMatrix_t`) - Matrix to store the solution vector(s).
* **rhs** (`cudssMatrix_t`) - The right-hand side vector(s) of the linear system.

### Request Example
```json
{
  "handle": "cudssHandle_t_object",
  "phase": 1, 
  "config": "cudssConfig_t_object",
  "data": "cudssData_t_object",
  "matrix": "cudssMatrix_t_object",
  "solution": "cudssMatrix_t_object",
  "rhs": "cudssMatrix_t_object"
}
```

### Response
#### Success Response (200)
* **cudssStatus_t** - Indicates the success or failure of the operation. A return value of `CUDSS_STATUS_SUCCESS` indicates success.

#### Response Example
```json
{
  "status": "CUDSS_STATUS_SUCCESS"
}
```

### Notes
* 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.
* Input sparse matrices may have unsorted column indices but must not have repeating entries.
* For the batched inputs, non-uniform batches with varying shapes are supported.
```

--------------------------------

### cudssExecute

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Executes a CUDSS operation.

```APIDOC
## cudssExecute

### Description
Executes a CUDSS operation.

### Function Signature
`cudssError_t cudssExecute(cudssHandle_t handle, cudssOperation_t operation)`

### Parameters
*   **handle** (cudssHandle_t) - The handle of the CUDSS library.
*   **operation** (cudssOperation_t) - The CUDSS operation to execute.
```

--------------------------------

### cudssMatrixCreateCsr

Source: https://docs.nvidia.com/cuda/cudss/genindex.html

Creates a CSR (Compressed Sparse Row) matrix.

```APIDOC
## cudssMatrixCreateCsr

### Description
Creates a CSR matrix.

### Function Signature
`cudssError_t cudssMatrixCreateCsr(cudssHandle_t handle, int n, int m, int nnz, cudssIndexBase_t index_base, cudssMatrix_t *matrix)`

### Parameters
*   **handle** (cudssHandle_t) - The handle of the CUDSS library.
*   **n** (int) - The number of rows.
*   **m** (int) - The number of columns.
*   **nnz** (int) - The number of non-zero elements.
*   **index_base** (cudssIndexBase_t) - The index base (CUDSS_BASE_ZERO or CUDSS_BASE_ONE).
*   **matrix** (cudssMatrix_t *) - Pointer to store the created CSR matrix.
```