{"id":23479,"library":"custatevec-cu13","title":"cuStateVec (cu13)","description":"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.","status":"active","version":"1.13.1","language":"python","source_language":"en","source_url":"https://github.com/NVIDIA/cuQuantum","tags":["quantum-computing","cuda","gpu","nvidia","state-vector"],"install":[{"cmd":"pip install custatevec-cu13","lang":"bash","label":"Install custatevec for CUDA 13"}],"dependencies":[{"reason":"Required for GPU array operations (CuPy for CUDA 13)","package":"cupy-cuda13x","optional":false},{"reason":"Python bindings for cuQuantum, often needed together","package":"cuquantum-python-cu13","optional":true}],"imports":[{"note":"Direct import of the module; no submodule needed for basic use.","wrong":"","symbol":"custatevec","correct":"import custatevec"},{"note":"Common mistaken nested import path.","wrong":"import custatevec.custatevec","symbol":"custatevec.createStateVector","correct":"from custatevec import createStateVector"}],"quickstart":{"code":"import custatevec\nimport cupy as cp\nn_qubits = 2\nn_amplitudes = 1 << n_qubits\nd_amplitudes = cp.zeros(n_amplitudes, dtype=cp.complex128)\nd_amplitudes[0] = 1.0 + 0.0j\nhandle = custatevec.create()\ncustatevec.initializeStateVector(\n    handle, d_amplitudes.data.ptr, custatevec.StateVectorType.COMPUTE_64F, n_qubits, None\n)\nprint('State vector initialized')\ncustatevec.destroy(handle)","lang":"python","description":"Initialize a 2-qubit state vector on CUDA 13 using custatevec-cu13."},"warnings":[{"fix":"Verify CUDA version with 'nvcc --version' and install the correct custatevec-cuXX variant (e.g., custatevec-cu12 for CUDA 12).","message":"The package name suffix -cu13 specifically requires CUDA 13.x runtime. Installing without matching CUDA version leads to ImportError or runtime errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Consider using cuquantum-python-cu13 instead, which includes custatevec functionality via the cuQuantum SDK.","message":"custatevec is superseded by cuQuantum Python's integrated API. Standalone custatevec usage may be deprecated in future cuQuantum releases.","severity":"deprecated","affected_versions":">=1.13"},{"fix":"Run 'pip install cupy-cuda13x' alongside custatevec-cu13.","message":"The CuPy version must match the CUDA major version. custatevec-cu13 is only compatible with cupy-cuda13x, not cupy-cuda12x.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Ensure CUDA 13 is installed and LD_LIBRARY_PATH includes the cuQuantum lib directory (e.g., /usr/local/cuda-13/lib64).","cause":"Missing or incorrect CUDA runtime library path. The custatevec shared library cannot be found.","error":"ImportError: libcustatevec.so.1: cannot open shared object file: No such file or directory"},{"fix":"Ensure custatevec.create() is called before any other cuStateVec function and that the handle is not used after custatevec.destroy().","cause":"Attempting to use an uninitialized handle or wrong handle after destroy.","error":"RuntimeError: cuStateVec API call failed with error code 3: CUSTATEVEC_STATUS_NOT_INITIALIZED"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}