# 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
11.x (where x >= 8) or 12.x. 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 currently only supported on Linux operating systems using
`x86_64` or `aarch64`/`arm64` processors.
[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 on `x86_64` platforms simply requires `pip install
cudaq`. Please make sure your `pip` version is \>= 24.0.
If you have an NVIDIA GPU on your host system, you will be
able to use it without any further installation steps.
> **Important:**
> Please check if you have an existing installation of the `cuda-quantum`, `cudaq-quantum-cu11`, or `cuda-quantum-cu12` package, and uninstall it prior to installation. Different CUDA-Q binary distributions may conflict with each other causing issues.
If you want to perform multi-GPU simulations, or if you are using
`aarch64`/`arm64` processors, 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 the
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=11.8.0 # set this variable to version 11.x (where x >= 8) or 12.x
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 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 cudaq
source $CONDA_PREFIX/lib/python3.11/site-packages/distributed_interfaces/activate_custom_mpi.sh
```
[//]: # (End conda install)
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.
[//]: # (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
Raw data
{
"_id": null,
"home_page": null,
"name": "cudaq",
"maintainer": "NVIDIA Corporation & Affiliates",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cudaq, cuda-quantum, cuda, quantum, quantum computing, nvidia, high-performance computing",
"author": "NVIDIA Corporation & Affiliates",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/67/2d/2204c654b9f92271ad2c9ec340891b4370d17d99d35d8395a55fb555b5e7/cudaq-0.9.0.tar.gz",
"platform": null,
"description": "# Welcome to the CUDA-Q Python API\n\nCUDA-Q is a comprehensive framework for quantum programming. It features:\n\n- A programming model which extends C++ and Python with quantum kernels,\n enabling high-level programming in familiar languages\n- A high-performance quantum compiler, `nvq++`, based on the industry standard\n LLVM toolchain\n- Interoperability with all of the leading models and tools for accelerated\n computing, including CUDA, ISO standard parallelism, OpenMP, and OpenACC\n- The ability to utilize and seamlessly switch between different quantum\n technologies, including state-of-the-art simulator backends with NVIDIA\n cuQuantum and a number of different physical quantum processors (QPUs)\n\nThe CUDA-Q Python wheels contain the Python API and core components of CUDA-Q.\nThis package installs CUDA-Q binaries that are compatible with a CUDA version\n11.x (where x >= 8) or 12.x. More information about available packages as\nwell as a link to the documentation and examples for each version can be found\nin the [release notes][cudaq_docs_releases]. System and compatibility\nrequirements are listed in the Installation Guide of the linked documentation.\n\n**Note**: CUDA-Q is currently only supported on Linux operating systems using\n`x86_64` or `aarch64`/`arm64` processors.\n\n[cudaq_docs_releases]:\n https://nvidia.github.io/cuda-quantum/latest/releases.html\n\n## Installation Including GPU-Acceleration\n\n[//]: # (Begin complete install)\n\nCUDA-Q does not require a GPU to use, but some components are GPU-accelerated.\n\nGetting started with CUDA-Q on `x86_64` platforms simply requires `pip install\ncudaq`. Please make sure your `pip` version is \\>= 24.0.\nIf you have an NVIDIA GPU on your host system, you will be\nable to use it without any further installation steps.\n\n> **Important:** \n> Please check if you have an existing installation of the `cuda-quantum`, `cudaq-quantum-cu11`, or `cuda-quantum-cu12` package, and uninstall it prior to installation. Different CUDA-Q binary distributions may conflict with each other causing issues.\n\n\nIf you want to perform multi-GPU simulations, or if you are using\n`aarch64`/`arm64` processors, additional components must be installed. We\nrecommend using [Conda](https://docs.conda.io/en/latest/) to do so. If you are\nnot already using Conda, you can install a minimal version following the\ninstructions [here](https://docs.anaconda.com/miniconda/). The following\ncommands will create and activate a complete environment for CUDA-Q with all its\ndependencies:\n\n[//]: # (Begin conda install)\n\n```console\ncuda_version=11.8.0 # set this variable to version 11.x (where x >= 8) or 12.x\nconda create -y -n cudaq-env python=3.11 pip\nconda install -y -n cudaq-env -c \"nvidia/label/cuda-${cuda_version}\" cuda\nconda install -y -n cudaq-env -c conda-forge mpi4py openmpi cxx-compiler\nconda env config vars set -n cudaq-env LD_LIBRARY_PATH=\"$CONDA_PREFIX/envs/cudaq-env/lib:$LD_LIBRARY_PATH\"\nconda env config vars set -n cudaq-env MPI_PATH=$CONDA_PREFIX/envs/cudaq-env\nconda activate cudaq-env\npip install cudaq\nsource $CONDA_PREFIX/lib/python3.11/site-packages/distributed_interfaces/activate_custom_mpi.sh\n```\n\n[//]: # (End conda install)\n\nYou must configure MPI by setting the following environment variables:\n\n[//]: # (Begin ompi setup)\n\n```console\nexport OMPI_MCA_opal_cuda_support=true OMPI_MCA_btl='^openib'\n```\n\n[//]: # (End ompi setup)\n\n*If you do not set these variables you may encounter a segmentation fault.*\n\n**Important**: It is *not* sufficient to set these variable within the Conda\nenvironment, like the commands above do for `LD_LIBRARY_PATH`. To avoid having\nto set them every time you launch a new shell, we recommend adding them to\n`~/.profile` (create the file if it does not exist), and to `~/.bash_profile` or\n`~/.bash_login` if such a file exists.\n\n[//]: # (End complete install)\n\nMPI uses [SSH](https://en.wikipedia.org/wiki/Secure_Shell) or\n[RSH](https://en.wikipedia.org/wiki/Remote_Shell) to communicate with each node\nunless another resource manager, such as\n[SLURM](https://slurm.schedmd.com/overview.html), is used. If you are\nencountering an error \"The value of the MCA parameter `plm_rsh_agent` was set to\na path that could not be found\", please make sure you have an SSH Client\ninstalled.\n\n## Running CUDA-Q\n\nYou should now be able to import CUDA-Q and start building quantum programs in\nPython!\n\n```console\nimport cudaq\n\nkernel = cudaq.make_kernel()\nqubit = kernel.qalloc()\nkernel.x(qubit)\nkernel.mz(qubit)\n\nresult = cudaq.sample(kernel)\n```\n\nAdditional examples and documentation are linked in the [release\nnotes][cudaq_docs_releases].\n\n## Contributing\n\nThere are many ways in which you can get involved with CUDA-Q. If you are\ninterested in developing quantum applications with CUDA-Q, our [GitHub\nrepository][github_link] is a great place to get started! For more information\nabout contributing to the CUDA-Q platform, please take a look at\n[Contributing.md](https://github.com/NVIDIA/cuda-quantum/blob/main/Contributing.md).\n\n## License\n\nCUDA-Q is an open source project. The source code is available on\n[GitHub][github_link] and licensed under [Apache License\n2.0](https://github.com/NVIDIA/cuda-quantum/blob/main/LICENSE). CUDA-Q makes use\nof the NVIDIA cuQuantum SDK to enable high-performance simulation, which is held\nto its own respective license.\n\n[github_link]: https://github.com/NVIDIA/cuda-quantum/\n\n## Feedback\n\nPlease let us know your feedback and ideas for the CUDA-Q platform in the\n[Discussions][discussions] tab of our [GitHub repository][github_repo], or [file\nan issue][cuda_quantum_issues]. To report security concerns please reach out to\n[cuda-quantum@nvidia.com](mailto:cuda-quantum@nvidia.com).\n\n[discussions]: https://github.com/NVIDIA/cuda-quantum/discussions\n[cuda_quantum_issues]: https://github.com/NVIDIA/cuda-quantum/issues\n[github_repo]: https://github.com/NVIDIA/cuda-quantum\n",
"bugtrack_url": null,
"license": "Apache License Version 2.0 Copyright (c) 2023 - 2024 NVIDIA Corporation & Affiliates All rights reserved. Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ",
"summary": "Python bindings for the CUDA-Q toolkit for heterogeneous quantum-classical workflows.",
"version": "0.9.0",
"project_urls": {
"Documentation": "https://nvidia.github.io/cuda-quantum",
"Homepage": "https://developer.nvidia.com/cuda-q",
"Releases": "https://nvidia.github.io/cuda-quantum/latest/releases.html",
"Repository": "https://github.com/NVIDIA/cuda-quantum"
},
"split_keywords": [
"cudaq",
" cuda-quantum",
" cuda",
" quantum",
" quantum computing",
" nvidia",
" high-performance computing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "672d2204c654b9f92271ad2c9ec340891b4370d17d99d35d8395a55fb555b5e7",
"md5": "26ce20250dbc9d908d5153d96c636f40",
"sha256": "9545fc50367d35c4acef9ec5afebbf8a78782c876f42810286762dbe2f2d7770"
},
"downloads": -1,
"filename": "cudaq-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "26ce20250dbc9d908d5153d96c636f40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 8396,
"upload_time": "2024-11-18T19:17:21",
"upload_time_iso_8601": "2024-11-18T19:17:21.810837Z",
"url": "https://files.pythonhosted.org/packages/67/2d/2204c654b9f92271ad2c9ec340891b4370d17d99d35d8395a55fb555b5e7/cudaq-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-18 19:17:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NVIDIA",
"github_project": "cuda-quantum",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cudaq"
}
