{"id":1593,"library":"nvidia-cusolver","title":"NVIDIA cuSOLVER Python Bindings","description":"The `nvidia-cusolver` package is a metapackage that provides the native runtime libraries for NVIDIA's cuSOLVER, along with Python bindings for these GPU-accelerated numerical linear algebra routines. It is tightly coupled with the NVIDIA CUDA Toolkit. This allows Python applications to leverage GPU power for tasks such as solving dense and sparse linear systems, eigenvalue problems, and singular value decompositions. The current version is 12.1.0.51, reflecting its alignment with CUDA Toolkit 12.1. Its release cadence follows major CUDA Toolkit updates.","status":"active","version":"12.1.0.51","language":"en","source_language":"en","source_url":"https://github.com/NVIDIA/cuda-python","tags":["cuda","gpu","linear-algebra","numerical-computation","nvidia","cusolver"],"install":[{"cmd":"pip install nvidia-cusolver","lang":"bash","label":"Install nvidia-cusolver"},{"cmd":"pip install cupy-cuda12x","lang":"bash","label":"Install CuPy for CUDA 12.x (Recommended)"}],"dependencies":[{"reason":"Provides CUDA runtime libraries required by cuSOLVER.","package":"nvidia-cuda-runtime-cu12","optional":false},{"reason":"cuSOLVER often relies on cuBLAS for fundamental linear algebra operations.","package":"nvidia-cublas-cu12","optional":false},{"reason":"Underlying Python driver bindings for CUDA, dependency of nvidia-cusolver-bindings.","package":"cuda-python","optional":false},{"reason":"Highly recommended for easily creating and manipulating GPU arrays in Python to use with cuSOLVER. While not a direct dependency, practical usage almost always involves an array library.","package":"cupy","optional":true}],"imports":[{"note":"The `nvidia-cusolver` PyPI package installs the Python bindings under the `cuda` namespace as `cuda.cusolver`.","wrong":"import nvidia_cusolver","symbol":"cusolver","correct":"from cuda import cusolver"}],"quickstart":{"code":"import cupy as cp\nfrom cuda import cusolver, cuda\n\n# Initialize CUDA context (often implicit with CuPy)\n# Create a symmetric positive-definite matrix on GPU using CuPy\n# For simplicity, let's create a diagonally dominant matrix\nn = 4\nA_host = cp.array([\n    [4.0, 1.0, 1.0, 1.0],\n    [1.0, 3.0, 0.0, 0.0],\n    [1.0, 0.0, 2.0, 0.0],\n    [1.0, 0.0, 0.0, 1.0]\n], dtype=cp.float32)\nA_device = cp.asarray(A_host, dtype=cp.float32)\n\n# Allocate memory for factorization output (in-place for potrf)\n# Allocate memory for info (error code)\ninfo_device = cp.zeros(1, dtype=cp.int32)\n\n# Create a cuSOLVER handle\nhandle = None\ntry:\n    handle = cusolver.create_handle()\n\n    # Query workspace size for potrf (Cholesky factorization)\n    lwork = cusolver.spotrf_bufferSize(handle,\n                                       cusolver.cudaSolver_fact_info.CUSOLVER_STATUS_SUCCESS,\n                                       n, A_device.data.ptr, n)\n    workspace = cp.zeros(lwork, dtype=cp.float32)\n\n    # Perform Cholesky factorization: A = L * L^T (or U^T * U)\n    # We'll use CUSOLVER_FILL_MODE_LOWER (lower triangle)\n    cusolver.spotrf(handle,\n                    cusolver.cudaSolver_fact_info.CUSOLVER_FILL_MODE_LOWER,\n                    n, A_device.data.ptr, n, workspace.data.ptr, lwork,\n                    info_device.data.ptr)\n\n    # Check for errors\n    info = info_device.get()\n    if info[0] != 0:\n        print(f\"Cholesky factorization failed with error code: {info[0]}\")\n    else:\n        print(\"Original Matrix (GPU):\\n\", A_host)\n        print(\"Cholesky Factor L (GPU, lower triangle of A_device):\\n\", A_device.get())\n\nfinally:\n    if handle:\n        cusolver.destroy_handle(handle)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `from cuda import cusolver` to access the cuSOLVER functions in your Python code.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}