Package: cuquantum-python-cu12
cuQuantum PythonDocumentationPlease visit theNVIDIA cuQuantum Python documentation.InstallationInstall cuQuantum Python from conda-forgeIf you already have a Conda environment set up, it is the easiest to install cuQuantum Python from the conda-forge channel:conda install -c conda-forge cuquantum-pythonThe Conda solver will install all required dependencies for you. If you need to select a particular CUDA version, say CUDA 12.0, please issue the following command:conda install -c conda-forge cuquantum-python cuda-version=12.0Install cuQuantum Python from PyPIAlternatively, assuming you already have a Python environment set up (it doesn't matter if it's a Conda env or not),
you can also install cuQuantum Python this way:pip install cuquantum-python-cuXXwithXXbeing11(for CUDA 11) or12(for CUDA 12).
Thepipsolver will also install all required dependencies for you (including both cuTENSOR and cuQuantum wheels).Notes:Users can install cuQuantum Python usingpip install --no-cache-dir cuquantum-python, which will attempt to detect the current CUDA environment and choose the appropriate wheel to install. In the event of detection failure, CUDA 11 is assumed. This is subject to change in the future. Installing wheels with the-cuXXsuffix is encouraged.--no-cache-diris required when usingpip23.1+.CuPy also uses a similar auto-detection mechanism to determine the correct wheel to install. If in doubt, or if installingcuquantum-python-cu11, please followCuPy's installation guideand install it manually.To manually manage all Python dependencies, append--no-depstopip installto bypass thepipsolver, see below.Building and installing cuQuantum Python from sourceRequirementsThe build-time dependencies of the cuQuantum Python package include:CUDA Toolkit 11.x or 12.xcuStateVec 1.4.0+cuTensorNet 2.2.0+cuTENSOR 1.6.1+Python 3.9+Cython >=0.29.22,<3pip 21.3.1+packagingsetuptools 61.0.0+wheel 0.34.0+Except for CUDA and Python, the rest of the build-time dependencies are handled by the new PEP-517-based build system (see Step 7 below).To compile and install cuQuantum Python from source, please follow the steps below:Clone theNVIDIA/cuQuantumrepository:git clone https://github.com/NVIDIA/cuQuantumSetCUDA_PATHto point to your CUDA installation[optional] SetCUQUANTUM_ROOTto point to your cuQuantum installation[optional] SetCUTENSOR_ROOTto point to your cuTENSOR installation[optional] Make sure cuQuantum and cuTENSOR are visible in yourLD_LIBRARY_PATHSwitch to the directory containing the Python implementation:cd cuQuantum/pythonBuild and install:Runpip install .if you skip Step 3-5 aboveRunpip install -v --no-deps --no-build-isolation .otherwise (advanced)Notes:For Step 7, if you are building from source for testing/developing purposes you'd likely want to insert a-eflag before the last period (sopip ... .becomespip ... -e .):-e: use the "editable" (in-place) mode-v: enable more verbose output--no-deps: avoid installing therun-timedependencies--no-build-isolation: reuse the current Python environment instead of creating a new one for building the package (this avoids installing anybuild-timedependencies)As an alternative to settingCUQUANTUM_ROOT,CUSTATEVEC_ROOTandCUTENSORNET_ROOTcan be set to point to the cuStateVec and the cuTensorNet libraries, respectively. The latter two environment variables take precedence if defined.Please ensure that you use consistent binaries and packages for either CUDA 11 or 12. Mixing-and-matching will result in undefined behavior.RunningRequirementsRuntime dependencies of the cuQuantum Python package include:An NVIDIA GPU with compute capability 7.0+Driver: Linux (450.80.02+ for CUDA 11, 525.60.13+ for CUDA 12)CUDA Toolkit 11.x or 12.xcuStateVec 1.4.0+cuTensorNet 2.2.0+cuTENSOR 1.6.1+Python 3.9+NumPy v1.21+CuPy v10.0.0+ (seeinstallation guide)PyTorch v1.10+ (optional, seeinstallation guide)Qiskit v0.24.0+ (optional, seeinstallation guide)Cirq v0.6.0+ (optional, seeinstallation guide)mpi4py v3.1.0+ (optional, seeinstallation guide)If you install everything from conda-forge, all the required dependencies are taken care for you (except for the driver).If you install the pip wheels, CuPy, cuTENSOR and cuQuantum (but not CUDA Toolkit or the driver,
please make sure the CUDA libraries are visible through yourLD_LIBRARY_PATH) are installed for you.If you build cuQuantum Python from source, please make sure that the paths to the CUDA, cuQuantum, and cuTENSOR libraries are added
to yourLD_LIBRARY_PATHenvironment variable, and that a compatible CuPy is installed.Known issues:If a system has multiple copies of cuTENSOR, one of which is installed in a default system path, the Python runtime could pick it up despite cuQuantum Python is linked to another copy installed elsewhere, potentially causing a version-mismatch error. The proper fix is to remove cuTENSOR from the system paths to ensure the visibility of the proper copy.DO NOT ATTEMPTto useLD_PRELOADto overwrite it --- it could cause hard to debug behaviors!In certain environments, if PyTorch is installedimport cuquantumcould fail (with a segmentation fault). It is currently under investigation and a temporary workaround is to importtorchbefore importingcuquantum.Please ensure that you use consistent binaries and packages for either CUDA 11 or 12. Mixing-and-matching will result in undefined behavior.SamplesSamples for demonstrating the usage of both low-level and high-level Python APIs are
available in thesamplesdirectory. The low-level API samples are 1:1 translations of the corresponding
samples written in C. The high-level API samples demonstrate pythonic usages of the cuTensorNet
library in Python.TestingIf pytest is installed, typingpytest testsat the command prompt in the Python source root directory will
run all tests. Some tests would be skipped ifcffiis not installed or if the environment
variableCUDA_PATHis not set.Citing cuQuantumPleae click this Zenodo badge to see the citation format: