Merge branch '22.11' into 'main'

Prepare for 22.11 public release

See merge request cuda-hpc-libraries/cuquantum-sdk/cuquantum-public!14

CONTRIBUTING.md

@@ -1,12 +1,14 @@
 # Contributing
 
-Thank you for your interest in contributing to cuQuantum Python! Based on the type of contribution, it will fall into two categories:
+Thank you for your interest in contributing to cuQuantum Python! Based on the type of contribution, it will fall into three categories:
 
 1. You want to report a bug, feature request, or documentation issue
-    - File an [issue](https://github.com/NVIDIA/cuQuantum/issues/new)
+    - File an [issue](https://github.com/NVIDIA/cuQuantum/issues)
     describing what you encountered or what you want to see changed.
     - The NVIDIA team will evaluate the issues and triage them, scheduling
     them for a release. If you believe the issue needs priority attention
     comment on the issue to notify the team.
 2. You want to implement a feature or bug-fix
     - At this time we do not accept code contributions.
+3. You want to share your nice work built upon cuQuantum:
+    - We would love to hear more about your work! Please share with us on [NVIDIA/cuQuantum GitHub Discussions](https://github.com/NVIDIA/cuQuantum/discussions>)! We also take any cuQuantum-related questions on this forum.

python/CONTRIBUTING.md

@@ -1,12 +1,14 @@
 # Contributing
 
-Thank you for your interest in contributing to cuQuantum Python! Based on the type of contribution, it will fall into two categories:
+Thank you for your interest in contributing to cuQuantum Python! Based on the type of contribution, it will fall into three categories:
 
 1. You want to report a bug, feature request, or documentation issue
-    - File an [issue](https://github.com/NVIDIA/cuQuantum/issues/new)
+    - File an [issue](https://github.com/NVIDIA/cuQuantum/issues)
     describing what you encountered or what you want to see changed.
     - The NVIDIA team will evaluate the issues and triage them, scheduling
     them for a release. If you believe the issue needs priority attention
     comment on the issue to notify the team.
 2. You want to implement a feature or bug-fix
     - At this time we do not accept code contributions.
+3. You want to share your nice work built upon cuQuantum:
+    - We would love to hear more about your work! Please share with us on [NVIDIA/cuQuantum GitHub Discussions](https://github.com/NVIDIA/cuQuantum/discussions>)! We also take any cuQuantum-related questions on this forum.

python/README.md

@@ -5,19 +5,7 @@
 Please visit the [NVIDIA cuQuantum Python documentation](https://docs.nvidia.com/cuda/cuquantum/python).
 
 
-## Building
-
-### Requirements
-
-Build-time dependencies of the cuQuantum Python package and some versions that
-are known to work are as follows:
-
-* CUDA Toolkit 11.x
-* cuQuantum 22.07+
-* cuTENSOR 1.5.0+
-* Python 3.8+
-* Cython - e.g. 0.29.21
-* [packaging](https://packaging.pypa.io/en/latest/)
+## Installation
 
 ### Install cuQuantum Python from conda-forge
 
@@ -33,26 +21,53 @@ Alternatively, assuming you already have a Python environment set up (it doesn't
 you can also install cuQuantum Python this way:
 
 ```
-pip install cuquantum-python
+pip install cuquantum-python-cu11
 ```
-The `pip` solver will also install both cuTENSOR and cuQuantum for you.
+The `pip` solver will also install all dependencies for you (including both cuTENSOR and cuQuantum wheels).
+
+Notes:
 
-Note: To properly install the wheels the environment variable `CUQUANTUM_ROOT` must not be set.
+- User can still install cuQuantum Python using `pip install cuquantum-python`, which currently points to the `cuquantum-python-cu11` wheel that is subject to change in the future. Installing wheels with the `-cuXX` suffix is encouraged.
+- To manually manage all Python dependencies, append `--no-deps` to `pip install` to bypass the `pip` solver, see below.
 
-### Install cuQuantum Python from source
+### Building and installing cuQuantum Python from source
+
+#### Requirements
+
+The build-time dependencies of the cuQuantum Python package include:
+
+* CUDA Toolkit 11.x
+* cuStateVec 1.1.0+
+* cuTensorNet 2.0.0+
+* cuTENSOR 1.5.0+
+* Python 3.8+
+* Cython >=0.29.22,<3
+* pip 21.3.1+
+* [packaging](https://packaging.pypa.io/en/latest/)
+* 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. Set `CUDA_PATH` to point to your CUDA installation
-2. Set `CUQUANTUM_ROOT` to point to your cuQuantum installation
-3. Set `CUTENSOR_ROOT` to point to your cuTENSOR installation
-4. Make sure CUDA, cuQuantum and cuTENSOR are visible in your `LD_LIBRARY_PATH`
-5. Run `pip install -v .`
+1. Clone the [NVIDIA/cuQuantum](https://github.com/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 the `pip install` step, adding the `-e` flag after `-v` would allow installing the package in-place (i.e., in "editable mode" for testing/developing).
-- If `CUSTATEVEC_ROOT` and `CUTENSORNET_ROOT` are set (for the cuStateVec and the cuTensorNet libraries, respectively), they overwrite `CUQUANTUM_ROOT`.
-- For local development, set `CUQUANTUM_IGNORE_SOLVER=1` to ignore the dependency on the `cuquantum` wheel.
+- 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.
 
 
 ## Running
@@ -64,14 +79,16 @@ Runtime dependencies of the cuQuantum Python package include:
 * An NVIDIA GPU with compute capability 7.0+
 * Driver: Linux (450.80.02+)
 * CUDA Toolkit 11.x
-* cuQuantum 22.07+
-* cuTENSOR 1.5.0+
+* cuStateVec 1.1.0+
+* cuTensorNet 2.0.0+
+* cuTENSOR 1.6.1+
 * Python 3.8+
 * NumPy v1.19+
 * CuPy v9.5.0+ (see [installation guide](https://docs.cupy.dev/en/stable/install.html))
 * PyTorch v1.10+ (optional, see [installation guide](https://pytorch.org/get-started/locally/))
 * Qiskit v0.24.0+ (optional, see [installation guide](https://qiskit.org/documentation/getting_started.html))
 * Cirq v0.6.0+ (optional, see [installation guide](https://quantumai.google/cirq/install))
+* mpi4py v3.1.0+ (optional, see [installation guide](https://mpi4py.readthedocs.io/en/stable/install.html))
 
 If you install everything from conda-forge, the dependencies are taken care for you (except for the driver).
 
@@ -102,4 +119,4 @@ variable `CUDA_PATH` is not set.
 
 ## Citing cuQuantum
 
-Pleae click this Zenodo badge to see the citation format: [![DOI](https://zenodo.org/badge/435003852.svg)](https://zenodo.org/badge/latestdoi/435003852)
+Pleae click this Zenodo badge to see the citation format: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6385574.svg)](https://doi.org/10.5281/zenodo.6385574)

python/builder/__init__.py

@@ -0,0 +1,39 @@
+# Copyright (c) 2021-2022, NVIDIA CORPORATION & AFFILIATES
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+
+# How does the build system for cuquantum-python work?
+#
+# - When building a wheel ("pip wheel", "pip install .", or "python setup.py
+#   bdist_wheel" (discouraged!)), we want to build against the cutensor &
+#   cuquantum wheels that would be installed to site-packages, so we need
+#   two things:
+#     1. make them the *build-time* dependencies
+#     2. set up linker flags to modify rpaths
+#
+# - For 1. we opt in to use PEP-517, as setup_requires is known to not work
+#   automatically for users. This is the "price" we pay (by design of
+#   PEP-517), as it creates a new, "isolated" environment (referred to as
+#   build isolation) to which all build-time dependencies that live on PyPI
+#   are installed. Another "price" (also by design) is in the non-editable
+#   mode (without the "-e" flag) it always builds a wheel for installation.
+#
+# - For 2. the solution is to create our own bdist_wheel (called first) and
+#   build_ext (called later) commands. The former would inform the latter
+#   whether we are building a wheel.
+#
+# - There is an escape hatch for 1. which is to set "--no-build-isolation".
+#   Then, users are expected to set CUQUANTUM_ROOT (or CUSTATEVEC_ROOT &
+#   CUTENSORNET_ROOT) and manage all build-time dependencies themselves.
+#   This, together with "-e", would not produce any wheel, which is the old
+#   behavior offered by the environment variable CUQUANTUM_IGNORE_SOLVER=1
+#   that we removed and no longer works.
+#
+# - In any case, the custom build_ext command is in use, which would compute
+#   the needed compiler flags (depending on it's building a wheel or not)
+#   and overwrite the incoming Extension instances.
+#
+# - In any case, the dependencies (on PyPI wheels) are set up by default,
+#   and "--no-deps" can be passed as usual to tell pip to ignore the
+#   *run-time* dependencies.

python/builder/pep517.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2021-2022, NVIDIA CORPORATION & AFFILIATES
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+# This module implements basic PEP 517 backend support, see e.g.
+# - https://peps.python.org/pep-0517/
+# - https://setuptools.pypa.io/en/latest/build_meta.html#dynamic-build-dependencies-and-other-build-meta-tweaks
+# Specifically, there are 5 APIs required to create a proper build backend, see below.
+# For now it's mostly a pass-through to setuptools, except that we need to determine
+# some dependencies at build time.
+#
+# Note that we purposely do not implement the PEP-660 API hooks so that "pip install ...
+# --no-build-isolation -e ." behaves as expected (in-place build/installation without
+# creating a wheel). This may require pip>21.3.0.
+
+from packaging.version import Version
+from setuptools import build_meta as _build_meta
+
+import utils  # this is builder.utils (the build system has sys.path set up)
+
+
+prepare_metadata_for_build_wheel = _build_meta.prepare_metadata_for_build_wheel
+build_wheel = _build_meta.build_wheel
+build_sdist = _build_meta.build_sdist
+
+
+# Note: this function returns a list of *build-time* dependencies, so it's not affected
+# by "--no-deps" based on the PEP-517 design.
+def get_requires_for_build_wheel(config_settings=None):
+    # set up version constraints: note that CalVer like 22.03 is normalized to
+    # 22.3 by setuptools, so we must follow the same practice in the constraints;
+    # also, we don't need the patch number here
+    cuqnt_require = [f'custatevec-cu{utils.cuda_major_ver}~=1.1',   # ">=1.1.0,<2"
+                     f'cutensornet-cu{utils.cuda_major_ver}~=2.0',  # ">=2.0.0,<3"
+                    ]
+
+    return _build_meta.get_requires_for_build_wheel(config_settings) + cuqnt_require
+
+
+# Note: We have never promised to support sdist (CUQNT-514). We really cannot
+# care less about the correctness here. If we are lucky, setuptools would do
+# the right thing for us, but even if it's wrong let's not worry about it.
+def get_requires_for_build_sdist(config_settings=None):
+    return _build_meta.get_requires_for_build_sdist(config_settings)