NVIDIA cuSOLVER Python Bindings

Warnings

• breaking The `nvidia-cusolver` package versions are tightly coupled with specific NVIDIA CUDA Toolkit versions (e.g., `cu12` implies CUDA 12.x). Using a version of `nvidia-cusolver` incompatible with your system's CUDA Toolkit or GPU driver can lead to runtime errors or incorrect results.
  Fix: Ensure that your `nvidia-cusolver` package version, NVIDIA driver, and CUDA Toolkit (if manually installed) are compatible. For example, `nvidia-cusolver` version `12.1.x` is designed for CUDA Toolkit 12.1.
• gotcha This library requires a compatible NVIDIA GPU and appropriate drivers to function. Running Python code that imports `cuda.cusolver` on a system without these prerequisites will result in `cuda.cuda.CU_ERROR_NO_DEVICE` or similar errors.
  Fix: Verify that your system has an NVIDIA GPU and that the correct drivers are installed and up-to-date. Check `nvidia-smi` output to confirm GPU and driver status.
• gotcha The `nvidia-cusolver` package is a metapackage that bundles native libraries and `nvidia-cusolver-bindings`. The actual Python module for cuSOLVER functionality is imported as `from cuda import cusolver`, not directly `import nvidia_cusolver`.
  Fix: Always use `from cuda import cusolver` to access the cuSOLVER functions in your Python code.
• gotcha cuSOLVER operates on GPU memory. You will need a compatible Python array library like CuPy (highly recommended) or Numba's CUDA device arrays to easily create, transfer, and manage data on the GPU for use with `cuda.cusolver` functions.
  Fix: Install `cupy` (e.g., `pip install cupy-cuda12x` for CUDA 12.x) and use `cupy.asarray()` to create arrays on the GPU before passing their data pointers to cuSOLVER functions.
• gotcha The `cuda.cusolver` API is a low-level wrapper around the C cuSOLVER library. This means users are often responsible for manual memory management (e.g., allocating scratchpad memory for workspace), handle management (creating and destroying handles), and explicit error checking via info arrays.
  Fix: Always check the `info` output parameter of cuSOLVER functions to detect errors. Follow documentation for required workspace sizes and allocate temporary GPU memory accordingly.

Install

• pip install nvidia-cusolver Install nvidia-cusolver
• pip install cupy-cuda12x Install CuPy for CUDA 12.x (Recommended)

Imports

• cusolver

  from cuda import cusolver

  The `nvidia-cusolver` PyPI package installs the Python bindings under the `cuda` namespace as `cuda.cusolver`.

Quickstart

This example demonstrates how to perform a Cholesky factorization using `cuda.cusolver.potrf`. It requires `cupy` for convenient GPU array creation and manipulation. A cuSOLVER handle is created, workspace size is queried, and then the factorization is executed on a symmetric positive-definite matrix on the GPU.

import cupy as cp
from cuda import cusolver, cuda

# Initialize CUDA context (often implicit with CuPy)
# Create a symmetric positive-definite matrix on GPU using CuPy
# For simplicity, let's create a diagonally dominant matrix
n = 4
A_host = cp.array([
    [4.0, 1.0, 1.0, 1.0],
    [1.0, 3.0, 0.0, 0.0],
    [1.0, 0.0, 2.0, 0.0],
    [1.0, 0.0, 0.0, 1.0]
], dtype=cp.float32)
A_device = cp.asarray(A_host, dtype=cp.float32)

# Allocate memory for factorization output (in-place for potrf)
# Allocate memory for info (error code)
info_device = cp.zeros(1, dtype=cp.int32)

# Create a cuSOLVER handle
handle = None
try:
    handle = cusolver.create_handle()

    # Query workspace size for potrf (Cholesky factorization)
    lwork = cusolver.spotrf_bufferSize(handle,
                                       cusolver.cudaSolver_fact_info.CUSOLVER_STATUS_SUCCESS,
                                       n, A_device.data.ptr, n)
    workspace = cp.zeros(lwork, dtype=cp.float32)

    # Perform Cholesky factorization: A = L * L^T (or U^T * U)
    # We'll use CUSOLVER_FILL_MODE_LOWER (lower triangle)
    cusolver.spotrf(handle,
                    cusolver.cudaSolver_fact_info.CUSOLVER_FILL_MODE_LOWER,
                    n, A_device.data.ptr, n, workspace.data.ptr, lwork,
                    info_device.data.ptr)

    # Check for errors
    info = info_device.get()
    if info[0] != 0:
        print(f"Cholesky factorization failed with error code: {info[0]}")
    else:
        print("Original Matrix (GPU):\n", A_host)
        print("Cholesky Factor L (GPU, lower triangle of A_device):\n", A_device.get())

finally:
    if handle:
        cusolver.destroy_handle(handle)