# 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. 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 cuda-quantum`. If you have an NVIDIA GPU on your host system, you
will be able to use it without any further installation steps.
However, 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
conda create -y -n cuda-quantum python=3.10 pip
conda install -y -n cuda-quantum -c "nvidia/label/cuda-11.8.0" cuda
conda install -y -n cuda-quantum -c conda-forge mpi4py openmpi cxx-compiler
conda env config vars set -n cuda-quantum LD_LIBRARY_PATH="$CONDA_PREFIX/envs/cuda-quantum/lib:$LD_LIBRARY_PATH"
conda env config vars set -n cuda-quantum MPI_PATH=$CONDA_PREFIX/envs/cuda-quantum
conda run -n cuda-quantum pip install cuda-quantum
conda activate cuda-quantum
source $CONDA_PREFIX/lib/python3.10/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": "cuda-quantum",
"maintainer": "NVIDIA Corporation & Affiliates",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cuda-quantum, cuda, quantum, quantum computing, nvidia, high-performance computing",
"author": "NVIDIA Corporation & Affiliates",
"author_email": null,
"download_url": null,
"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\nCUDA-Q. More information about available packages as well as a link to the\ndocumentation and examples for each version can be found in the [release\nnotes][cudaq_docs_releases]. System and compatibility requirements\nare 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\n`pip install cuda-quantum`. If you have an NVIDIA GPU on your host system, you\nwill be able to use it without any further installation steps.\n\nHowever, if you want to perform multi-GPU simulations, or if you are using\n`aarch64`/`arm64` processors, additional components must be installed.\nWe recommend using [Conda](https://docs.conda.io/en/latest/) to do so.\nIf you are not already using Conda,\nyou can install a minimal version following the instructions\n[here](https://docs.anaconda.com/miniconda/). The\nfollowing commands will create and activate a complete environment for CUDA-Q\nwith all its dependencies:\n\n[//]: # (Begin conda install)\n\n```console\nconda create -y -n cuda-quantum python=3.10 pip\nconda install -y -n cuda-quantum -c \"nvidia/label/cuda-11.8.0\" cuda\nconda install -y -n cuda-quantum -c conda-forge mpi4py openmpi cxx-compiler\nconda env config vars set -n cuda-quantum LD_LIBRARY_PATH=\"$CONDA_PREFIX/envs/cuda-quantum/lib:$LD_LIBRARY_PATH\"\nconda env config vars set -n cuda-quantum MPI_PATH=$CONDA_PREFIX/envs/cuda-quantum\nconda run -n cuda-quantum pip install cuda-quantum\nconda activate cuda-quantum\nsource $CONDA_PREFIX/lib/python3.10/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\nprograms in Python!\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\nmakes use of the NVIDIA cuQuantum SDK to enable high-performance simulation,\nwhich is held to 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 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.8.0",
"project_urls": {
"Documentation": "https://nvidia.github.io/cuda-quantum",
"Homepage": "https://developer.nvidia.com/cuda-quantum",
"Releases": "https://nvidia.github.io/cuda-quantum/latest/releases.html",
"Repository": "https://github.com/NVIDIA/cuda-quantum"
},
"split_keywords": [
"cuda-quantum",
" cuda",
" quantum",
" quantum computing",
" nvidia",
" high-performance computing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "46a289b54e1d88fe78a50a9f92e05c36a1cadc894854e9455b1b33cf9ce427d2",
"md5": "ec15ae502260be70aad231ea8b8e2530",
"sha256": "372e2e437d984515ac84e5ccd589cf5401ebb4bac1f2dd090305fb6b8ff046fa"
},
"downloads": -1,
"filename": "cuda_quantum-0.8.0-cp310-cp310-manylinux_2_28_aarch64.whl",
"has_sig": false,
"md5_digest": "ec15ae502260be70aad231ea8b8e2530",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.8",
"size": 112510295,
"upload_time": "2024-08-06T19:23:48",
"upload_time_iso_8601": "2024-08-06T19:23:48.854494Z",
"url": "https://files.pythonhosted.org/packages/46/a2/89b54e1d88fe78a50a9f92e05c36a1cadc894854e9455b1b33cf9ce427d2/cuda_quantum-0.8.0-cp310-cp310-manylinux_2_28_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3d042ef6dd96297be6ef7e5e38d5a212a972f1a8e3f7bbc527c8d62a532884d2",
"md5": "d3b63164c83b357c09dbf4428ca3c958",
"sha256": "3a201ded430d3f7d5eb52017c2514b7ba2a8a6dc768060940539a2c30d5a4d3b"
},
"downloads": -1,
"filename": "cuda_quantum-0.8.0-cp310-cp310-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "d3b63164c83b357c09dbf4428ca3c958",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.8",
"size": 118706134,
"upload_time": "2024-08-06T19:16:17",
"upload_time_iso_8601": "2024-08-06T19:16:17.048477Z",
"url": "https://files.pythonhosted.org/packages/3d/04/2ef6dd96297be6ef7e5e38d5a212a972f1a8e3f7bbc527c8d62a532884d2/cuda_quantum-0.8.0-cp310-cp310-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "38dae4a4d6cf1f358f5becbe4ba7e097c0e2acf8137a69cd5361d70e273483c4",
"md5": "9bcec432a1eb96a2b293cbdeff8acbb3",
"sha256": "b700ab2b9f7bb66ca7bb8d19de7ddd78f9d95165f818aa485b80fc94ada4fee2"
},
"downloads": -1,
"filename": "cuda_quantum-0.8.0-cp311-cp311-manylinux_2_28_aarch64.whl",
"has_sig": false,
"md5_digest": "9bcec432a1eb96a2b293cbdeff8acbb3",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.8",
"size": 112530880,
"upload_time": "2024-08-06T19:24:42",
"upload_time_iso_8601": "2024-08-06T19:24:42.589045Z",
"url": "https://files.pythonhosted.org/packages/38/da/e4a4d6cf1f358f5becbe4ba7e097c0e2acf8137a69cd5361d70e273483c4/cuda_quantum-0.8.0-cp311-cp311-manylinux_2_28_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75911a001a98438e7d479ee479009484ac8edb0b9af3c2852a9184ec8a9b22ce",
"md5": "b43778b31c0e40a9a47f0330c2b5646a",
"sha256": "00313ac125d908f3f99b9b90e7257767d0924501cef779c1af27488038912129"
},
"downloads": -1,
"filename": "cuda_quantum-0.8.0-cp311-cp311-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "b43778b31c0e40a9a47f0330c2b5646a",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.8",
"size": 118721982,
"upload_time": "2024-08-06T19:17:56",
"upload_time_iso_8601": "2024-08-06T19:17:56.123942Z",
"url": "https://files.pythonhosted.org/packages/75/91/1a001a98438e7d479ee479009484ac8edb0b9af3c2852a9184ec8a9b22ce/cuda_quantum-0.8.0-cp311-cp311-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d1b6a2b294f34859da45e00b51cb5374183695bdf96d1e49e854bdbbc6c593ff",
"md5": "bac824b4558b554a0657603cc32058a6",
"sha256": "8b4f3997ae9c536fc4c197c8a438f6f38e411ee64d1ad5aef958a6aeb9604c60"
},
"downloads": -1,
"filename": "cuda_quantum-0.8.0-cp38-cp38-manylinux_2_28_aarch64.whl",
"has_sig": false,
"md5_digest": "bac824b4558b554a0657603cc32058a6",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.8",
"size": 112507689,
"upload_time": "2024-08-06T19:21:45",
"upload_time_iso_8601": "2024-08-06T19:21:45.478657Z",
"url": "https://files.pythonhosted.org/packages/d1/b6/a2b294f34859da45e00b51cb5374183695bdf96d1e49e854bdbbc6c593ff/cuda_quantum-0.8.0-cp38-cp38-manylinux_2_28_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a28c966cd16e5598013115f57bb1b1ce656d87f7c83f7bf774ed4e1abb659d49",
"md5": "5aa3e838fd86024e9e6ee3c152e4791e",
"sha256": "5ae23a25b6a0c44407c551e45b75671ce9505d688efc111e9bdd50fcd5fd7018"
},
"downloads": -1,
"filename": "cuda_quantum-0.8.0-cp38-cp38-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "5aa3e838fd86024e9e6ee3c152e4791e",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.8",
"size": 118702789,
"upload_time": "2024-08-06T19:18:57",
"upload_time_iso_8601": "2024-08-06T19:18:57.853245Z",
"url": "https://files.pythonhosted.org/packages/a2/8c/966cd16e5598013115f57bb1b1ce656d87f7c83f7bf774ed4e1abb659d49/cuda_quantum-0.8.0-cp38-cp38-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eb04cf23566309877bcc0aeeb81bcb413d2eece263f0d77efc7b507a220e5f21",
"md5": "02c0913eecd4f357310d7b105cb0c531",
"sha256": "3c69ce0e79250ba7546a9ea1004b195a312ed48c15e8d562d73dc728b4014440"
},
"downloads": -1,
"filename": "cuda_quantum-0.8.0-cp39-cp39-manylinux_2_28_aarch64.whl",
"has_sig": false,
"md5_digest": "02c0913eecd4f357310d7b105cb0c531",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.8",
"size": 112512754,
"upload_time": "2024-08-06T19:22:48",
"upload_time_iso_8601": "2024-08-06T19:22:48.125682Z",
"url": "https://files.pythonhosted.org/packages/eb/04/cf23566309877bcc0aeeb81bcb413d2eece263f0d77efc7b507a220e5f21/cuda_quantum-0.8.0-cp39-cp39-manylinux_2_28_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1918fe5306db6cb32ea7061d76c9ad005799028d2d04ced5dc2e0fcd490d2e8c",
"md5": "27e24606bcfd4455faec2ddb2990b568",
"sha256": "9563081b2a9f7afce95ae21b18af2686cbc8528bf34a45a4f7f21d64d84d4cb1"
},
"downloads": -1,
"filename": "cuda_quantum-0.8.0-cp39-cp39-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "27e24606bcfd4455faec2ddb2990b568",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.8",
"size": 118708331,
"upload_time": "2024-08-06T19:20:25",
"upload_time_iso_8601": "2024-08-06T19:20:25.044395Z",
"url": "https://files.pythonhosted.org/packages/19/18/fe5306db6cb32ea7061d76c9ad005799028d2d04ced5dc2e0fcd490d2e8c/cuda_quantum-0.8.0-cp39-cp39-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-06 19:23:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NVIDIA",
"github_project": "cuda-quantum",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cuda-quantum"
}
