cuStateVec (cu13)

1.13.1 verified Fri May 01 auth: no python

NVIDIA cuQuantum SDK component for state vector simulation on CUDA 13 hardware. Version 1.13.1 provides GPU-accelerated quantum state manipulation. Released alongside cuQuantum releases.

pip install custatevec-cu13

Common errors

error ImportError: libcustatevec.so.1: cannot open shared object file: No such file or directory ↓

cause Missing or incorrect CUDA runtime library path. The custatevec shared library cannot be found.

fix

Ensure CUDA 13 is installed and LD_LIBRARY_PATH includes the cuQuantum lib directory (e.g., /usr/local/cuda-13/lib64).

error RuntimeError: cuStateVec API call failed with error code 3: CUSTATEVEC_STATUS_NOT_INITIALIZED ↓

cause Attempting to use an uninitialized handle or wrong handle after destroy.

fix

Ensure custatevec.create() is called before any other cuStateVec function and that the handle is not used after custatevec.destroy().

Warnings

gotcha The package name suffix -cu13 specifically requires CUDA 13.x runtime. Installing without matching CUDA version leads to ImportError or runtime errors. ↓

fix Verify CUDA version with 'nvcc --version' and install the correct custatevec-cuXX variant (e.g., custatevec-cu12 for CUDA 12).

deprecated custatevec is superseded by cuQuantum Python's integrated API. Standalone custatevec usage may be deprecated in future cuQuantum releases. ↓

fix Consider using cuquantum-python-cu13 instead, which includes custatevec functionality via the cuQuantum SDK.

gotcha The CuPy version must match the CUDA major version. custatevec-cu13 is only compatible with cupy-cuda13x, not cupy-cuda12x. ↓

fix Run 'pip install cupy-cuda13x' alongside custatevec-cu13.

Imports

custatevec
```
import custatevec
```
Direct import of the module; no submodule needed for basic use.
custatevec.createStateVector
wrong
```
import custatevec.custatevec
```
correct
```
from custatevec import createStateVector
```
Common mistaken nested import path.

Quickstart

Initialize a 2-qubit state vector on CUDA 13 using custatevec-cu13.

import custatevec
import cupy as cp
n_qubits = 2
n_amplitudes = 1 << n_qubits
d_amplitudes = cp.zeros(n_amplitudes, dtype=cp.complex128)
d_amplitudes[0] = 1.0 + 0.0j
handle = custatevec.create()
custatevec.initializeStateVector(
    handle, d_amplitudes.data.ptr, custatevec.StateVectorType.COMPUTE_64F, n_qubits, None
)
print('State vector initialized')
custatevec.destroy(handle)