Metadata-Version: 2.4
Name: cuda-quantum-cu12
Version: 0.14.0
Summary: Python bindings for the CUDA-Q toolkit for heterogeneous quantum-classical workflows.
Keywords: cudaq,cuda-quantum,cuda,quantum,quantum computing,nvidia,high-performance computing
Author: NVIDIA Corporation & Affiliates
Maintainer: NVIDIA Corporation & Affiliates
License-Expression: Apache-2.0
License-File: CITATION.cff
License-File: LICENSE
License-File: NOTICE
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Environment :: GPU :: NVIDIA CUDA :: 12
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Project-URL: Homepage, https://developer.nvidia.com/cuda-q
Project-URL: Documentation, https://nvidia.github.io/cuda-quantum
Project-URL: Repository, https://github.com/NVIDIA/cuda-quantum
Project-URL: Releases, https://nvidia.github.io/cuda-quantum/latest/releases.html
Requires-Python: >=3.11
Requires-Dist: astpretty~=3.0
Requires-Dist: custatevec-cu12~=1.12
Requires-Dist: cutensornet-cu12~=2.11
Requires-Dist: cudensitymat-cu12~=0.4
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10.1
Requires-Dist: requests>=2.32.4
Requires-Dist: nvidia-cublas-cu12~=12.0
Requires-Dist: nvidia-curand-cu12~=10.3
Requires-Dist: nvidia-cusparse-cu12~=12.5
Requires-Dist: nvidia-cuda-runtime-cu12~=12.0
Requires-Dist: nvidia-cusolver-cu12~=11.4
Requires-Dist: nvidia-cuda-nvrtc-cu12~=12.0
Requires-Dist: cupy-cuda12x~=13.6.0
Provides-Extra: chemistry
Requires-Dist: openfermionpyscf==0.5; extra == "chemistry"
Requires-Dist: h5py<3.11; extra == "chemistry"
Provides-Extra: visualization
Requires-Dist: qutip>5; extra == "visualization"
Requires-Dist: matplotlib>=3.5; extra == "visualization"
Provides-Extra: integrators
Requires-Dist: torchdiffeq; extra == "integrators"
Description-Content-Type: text/markdown

# Welcome to the CUDA-Q Python API

CUDA-Q is a comprehensive framework for quantum programming. It features:

- A programming model which extends C++ and Python with quantum kernels,
  enabling high-level programming in familiar languages
- A high-performance quantum compiler, `nvq++`, based on the industry standard
  LLVM toolchain
- Interoperability with all of the leading models and tools for accelerated
  computing, including CUDA, ISO standard parallelism, OpenMP, and OpenACC
- The ability to utilize and seamlessly switch between different quantum
  technologies, including state-of-the-art simulator backends with NVIDIA
  cuQuantum and a number of different physical quantum processors (QPUs)

The CUDA-Q Python wheels contain the Python API and core components of CUDA-Q.
This package installs CUDA-Q binaries that are compatible with a CUDA version
${{ cuda_version_requirement }}. More information about available packages as
well as a link to the documentation and examples for each version can be found
in the [release notes][cudaq_docs_releases]. System and compatibility
requirements are listed in the Installation Guide of the linked documentation.

**Note**: CUDA-Q is supported on Linux (`x86_64` and `aarch64`/`arm64`) and
macOS (ARM64/Apple silicon, CPU-only simulation). GPU-accelerated simulation
requires Linux with a supported NVIDIA GPU.

[cudaq_docs_releases]:
    https://nvidia.github.io/cuda-quantum/latest/releases.html

## Installation Including GPU-Acceleration

[//]: # (Begin complete install)

CUDA-Q does not require a GPU to use, but some components are GPU-accelerated.
Getting started with CUDA-Q requires `pip install
${{ package_name }}`. Please make sure your `pip` version is \>= 24.0.

${{ deprecation_notice }}

> **Important:**
> Please check if you have an existing installation of the `cuda-quantum`,
`cudaq-quantum-cu11`, `cuda-quantum-cu12`, or `cuda-quantum-cu13` package, and uninstall it prior to
 installation. Different CUDA-Q binary distributions may conflict with each
 other causing issues.

Platform-specific instructions: Linux | macOS

**Linux: GPU-Acceleration and Multi-GPU**

If you have an NVIDIA GPU on your host system, you will be
able to use it without any further installation steps.

If you want to perform multi-GPU simulations, additional components must be
installed. We recommend using [Conda](https://docs.conda.io/en/latest/) to do
so. If you are not already using Conda, you can install a minimal version
following [miniconda instructions here](https://docs.anaconda.com/miniconda/).
The following commands will create and activate a complete environment for
CUDA-Q with all its dependencies:

[//]: # (Begin conda install)

```console
cuda_version=${{ cuda_version_conda }} # set this variable to version ${{ cuda_version_requirement }}
conda create -y -n cudaq-env python=3.11 pip
conda install -y -n cudaq-env -c "nvidia/label/cuda-${cuda_version}" cuda
conda install -y -n cudaq-env -c conda-forge mpi4py openmpi">=5.0.3" cxx-compiler
conda env config vars set -n cudaq-env LD_LIBRARY_PATH="$CONDA_PREFIX/envs/cudaq-env/lib:$LD_LIBRARY_PATH"
conda env config vars set -n cudaq-env MPI_PATH=$CONDA_PREFIX/envs/cudaq-env
conda activate cudaq-env
pip install ${{ package_name }}
source $CONDA_PREFIX/lib/python3.11/site-packages/distributed_interfaces/activate_custom_mpi.sh
```

[//]: # (End conda install)

**Warning (conda-forge)**: Installing `cudaq` from the `conda-forge` channel on recent versions of Python can lead to segmentation faults.
If you see such errors, please switch to one of the Python versions 3.10.15, 3.11.10, or 3.12.7 as per the issue
[#2999](https://github.com/NVIDIA/cuda-quantum/issues/2999) or [#3104](https://github.com/NVIDIA/cuda-quantum/issues/3104).

You must configure MPI by setting the following environment variables:

[//]: # (Begin ompi setup)

```console
export OMPI_MCA_opal_cuda_support=true OMPI_MCA_btl='^openib'
```

[//]: # (End ompi setup)

*If you do not set these variables you may encounter a segmentation fault.*

**Important**: It is *not* sufficient to set these variable within the Conda
environment, like the commands above do for `LD_LIBRARY_PATH`. To avoid having
to set them every time you launch a new shell, we recommend adding them to
`~/.profile` (create the file if it does not exist), and to `~/.bash_profile` or
`~/.bash_login` if such a file exists.

**macOS**

GPU-acceleration is not available on macOS, so a virtual environment
is all you need:

[//]: # (Begin macos install)

```console
python3 -m venv .venv
source .venv/bin/activate
pip install cudaq
```

[//]: # (End macos install)

[//]: # (End complete install)

MPI uses [SSH](https://en.wikipedia.org/wiki/Secure_Shell) or
[RSH](https://en.wikipedia.org/wiki/Remote_Shell) to communicate with each node
unless another resource manager, such as
[SLURM](https://slurm.schedmd.com/overview.html), is used. If you are
encountering an error "The value of the MCA parameter `plm_rsh_agent` was set to
a path that could not be found", please make sure you have an SSH Client
installed.

## Running CUDA-Q

You should now be able to import CUDA-Q and start building quantum programs in
Python!

```console
import cudaq

kernel = cudaq.make_kernel()
qubit = kernel.qalloc()
kernel.x(qubit)
kernel.mz(qubit)

result = cudaq.sample(kernel)
```

Additional examples and documentation are linked in the [release
notes][cudaq_docs_releases].

## Contributing

There are many ways in which you can get involved with CUDA-Q. If you are
interested in developing quantum applications with CUDA-Q, our [GitHub
repository][github_link] is a great place to get started! For more information
about contributing to the CUDA-Q platform, please take a look at
[Contributing.md](https://github.com/NVIDIA/cuda-quantum/blob/main/Contributing.md).

## License

CUDA-Q is an open source project. The source code is available on
[GitHub][github_link] and licensed under [Apache License
2.0](https://github.com/NVIDIA/cuda-quantum/blob/main/LICENSE). CUDA-Q makes use
of the NVIDIA cuQuantum SDK to enable high-performance simulation, which is held
to its own respective license.

[github_link]: https://github.com/NVIDIA/cuda-quantum/

## Feedback

Please let us know your feedback and ideas for the CUDA-Q platform in the
[Discussions][discussions] tab of our [GitHub repository][github_repo], or [file
an issue][cuda_quantum_issues]. To report security concerns please reach out to
[cuda-quantum@nvidia.com](mailto:cuda-quantum@nvidia.com).

[discussions]: https://github.com/NVIDIA/cuda-quantum/discussions
[cuda_quantum_issues]: https://github.com/NVIDIA/cuda-quantum/issues
[github_repo]: https://github.com/NVIDIA/cuda-quantum
