Skip to main content

NVIDIA cuQuantum Python

Project description

cuQuantum Python

Documentation

Please visit the NVIDIA cuQuantum Python documentation.

Installation

Install cuQuantum Python from conda-forge

If 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-python

The 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.0

Install cuQuantum Python from PyPI

Alternatively, 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-cuXX

with XX being 11 (for CUDA 11) or 12 (for CUDA 12). The pip solver will also install all required dependencies for you (including both cuTENSOR and cuQuantum wheels).

Notes:

  • Users can install cuQuantum Python using pip 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 -cuXX suffix is encouraged. --no-cache-dir is required when using pip 23.1+.
  • CuPy also uses a similar auto-detection mechanism to determine the correct wheel to install. If in doubt, or if installing cuquantum-python-cu11, please follow CuPy's installation guide and install it manually.
  • To manually manage all Python dependencies, append --no-deps to pip install to bypass the pip solver, see below.

Building and installing cuQuantum Python from source

Requirements

The build-time dependencies of the cuQuantum Python package include:

  • CUDA Toolkit 11.x or 12.x
  • cuStateVec 1.4.0+
  • cuTensorNet 2.2.0+
  • cuTENSOR 1.6.1+
  • Python 3.9+
  • Cython >=0.29.22,<3
  • pip 21.3.1+
  • packaging
  • setuptools 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:

  1. Clone the NVIDIA/cuQuantum repository: git clone https://github.com/NVIDIA/cuQuantum
  2. Set CUDA_PATH to point to your CUDA installation
  3. [optional] Set CUQUANTUM_ROOT to point to your cuQuantum installation
  4. [optional] Set CUTENSOR_ROOT to point to your cuTENSOR installation
  5. [optional] Make sure cuQuantum and cuTENSOR are visible in your LD_LIBRARY_PATH
  6. Switch to the directory containing the Python implementation: cd cuQuantum/python
  7. Build and install:
    • Run pip install . if you skip Step 3-5 above
    • Run pip 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 -e flag before the last period (so pip ... . becomes pip ... -e .):
    • -e: use the "editable" (in-place) mode
    • -v: enable more verbose output
    • --no-deps: avoid installing the run-time dependencies
    • --no-build-isolation: reuse the current Python environment instead of creating a new one for building the package (this avoids installing any build-time dependencies)
  • As an alternative to setting CUQUANTUM_ROOT, CUSTATEVEC_ROOT and CUTENSORNET_ROOT can 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.

Running

Requirements

Runtime dependencies of the cuQuantum Python package include:

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 your LD_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 your LD_LIBRARY_PATH environment 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 ATTEMPT to use LD_PRELOAD to overwrite it --- it could cause hard to debug behaviors!
  • In certain environments, if PyTorch is installed import cuquantum could fail (with a segmentation fault). It is currently under investigation and a temporary workaround is to import torch before importing cuquantum.
  • Please ensure that you use consistent binaries and packages for either CUDA 11 or 12. Mixing-and-matching will result in undefined behavior.

Samples

Samples for demonstrating the usage of both low-level and high-level Python APIs are available in the samples directory. 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.

Testing

If pytest is installed, typing pytest tests at the command prompt in the Python source root directory will run all tests. Some tests would be skipped if cffi is not installed or if the environment variable CUDA_PATH is not set.

Citing cuQuantum

Pleae click this Zenodo badge to see the citation format: DOI

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

File details

Details for the file cuquantum_python_cu11-23.6.0-cp311-cp311-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for cuquantum_python_cu11-23.6.0-cp311-cp311-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 45465ef2e8743d82d838df69aaa3f6ebaf8055645229122b855c2b5fa23447d9
MD5 08142b3d623db4ab03b1dbd681379218
BLAKE2b-256 1496d5e3c14a3a623c0f5c2dd08dda3946004662a215d1544e62ab65ae65cc44

See more details on using hashes here.

File details

Details for the file cuquantum_python_cu11-23.6.0-cp311-cp311-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for cuquantum_python_cu11-23.6.0-cp311-cp311-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 bb57314f6626e2878060b74bd411c2f1c9c67f1d8b7a03628806af51901ec33b
MD5 db1c781dd2eb4ddffcc426d71d47d78b
BLAKE2b-256 2a1d9354b57228520b4de25b6217d288cc0f94cbdad06aab3905afe9d800fbcc

See more details on using hashes here.

File details

Details for the file cuquantum_python_cu11-23.6.0-cp310-cp310-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for cuquantum_python_cu11-23.6.0-cp310-cp310-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d9462ac85fd2ef58dd2e0aadb540b8f569ebae514484a8601c59e1aa5b0b9115
MD5 7ab9d2e1d43d9b93834caae6aeca9c11
BLAKE2b-256 40d79c26192c1634434baf395a4ff6f3e34831dfc143a2eac239f475dd140922

See more details on using hashes here.

File details

Details for the file cuquantum_python_cu11-23.6.0-cp310-cp310-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for cuquantum_python_cu11-23.6.0-cp310-cp310-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 6dfc45f821de019ce9731efae23f256317aa50540fde87a91f51d7c5362c2f64
MD5 7171621fc79db4ff5ecfa8c788043234
BLAKE2b-256 4a174054d62671218e103e182e81d6f91faa542f345c243290079f40c42322d1

See more details on using hashes here.

File details

Details for the file cuquantum_python_cu11-23.6.0-cp39-cp39-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for cuquantum_python_cu11-23.6.0-cp39-cp39-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 7c1d4713ae441da1ea9e16fce63f076a7c907c423f4f355c72d51bd207e3a14d
MD5 d6844698e42369ea874403be6548fdc0
BLAKE2b-256 7df355ee9e6f56237733e634da7b1d423141a993c68820dbe2cb8867c50b77a6

See more details on using hashes here.

File details

Details for the file cuquantum_python_cu11-23.6.0-cp39-cp39-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for cuquantum_python_cu11-23.6.0-cp39-cp39-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 c650e8e68802620f7203960f983072d59128c41075d5542e00e23f88788d7a3a
MD5 2fd33e216e1b806b20db9c9b3400aec9
BLAKE2b-256 f964368feb226ad0c5107daa11aeaa1d9c43b489b7718f2ed2f8afbce0bb226b

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page