# pyquil-for-azure-quantum
This library allows you to use [pyQuil] to run programs on [Azure Quantum](https://azure.microsoft.com/en-us/services/quantum/) against Rigetti targets. Internally, it leverages the [azure-quantum] package.
## Usage
Generally, you use [pyQuil] normally, with a few differences:
1. Instead of `pyquil.get_qc()`, you will use either `pyquil_azure_quantum.get_qvm()` or `pyquil_azure_quantum.get_qpu()`.
2. You do not need to have `qvm` or `quilc` running in order to run programs through `pyquil_azure_quantum`. You may still run them if you wish to run QVM locally instead of passing through Azure or if you wish to precompile your programs (e.g., to inspect the exact Quil that will run).
3. You do not need a QCS account or credentials unless you wish to manually inspect the details of the QPU (e.g., list all qubits).
4. You **must** have these environment variables set:
1. `AZURE_QUANTUM_SUBSCRIPTION_ID`: The Azure subscription ID where the Quantum Workspace is located.
2. `AZURE_QUANTUM_WORKSPACE_RG`: The Azure resource group where the Quantum Workspace is located.
3. `AZURE_QUANTUM_WORKSPACE_NAME`: The name of the Quantum Workspace.
4. `AZURE_QUANTUM_WORKSPACE_LOCATION`: The region where the Quantum Workspace is located.
5. You **may** [set environment variables][azure auth] to authenticate with Azure. If you do not, a browser will open to the Azure portal to authenticate.
6. Whenever possible, you should prefer using `AzureQuantumComputer.run_batch()` over `Program.write_memory(); AzureQuantumComputer.run()` to run programs which have multiple parameters. Calling `write_memory()` followed by `run()` will still work but will be much slower than running a batch of parameters all at once.
## Examples
### 1. Leveraging Hosted QVM and quilc
With this program, you do not need to run `qvm` nor `quilc` locally in order to leverage them, as they can run through Azure Quantum.
```python
from pyquil_for_azure_quantum import get_qpu, get_qvm
from pyquil.gates import CNOT, MEASURE, H
from pyquil.quil import Program
from pyquil.quilbase import Declare
program = Program(
Declare("ro", "BIT", 2),
H(0),
CNOT(0, 1),
MEASURE(0, ("ro", 0)),
MEASURE(1, ("ro", 1)),
).wrap_in_numshots_loop(1000)
qpu = get_qpu("Aspen-11")
qvm = get_qvm()
exe = qpu.compile(program) # This does not run quilc yet.
results = qpu.run(exe) # Quilc will run in the cloud before executing the program.
qvm_results = qvm.run(exe) # This runs the program on QVM in the cloud, not locally.
```
### 2. Running quilc Locally
You can optionally run quilc yourself and disable the use of quilc in the cloud.
```python
from pyquil_for_azure_quantum import get_qpu
from pyquil.gates import CNOT, MEASURE, H
from pyquil.quil import Program
from pyquil.quilbase import Declare
program = Program(
Declare("ro", "BIT", 2),
H(0),
CNOT(0, 1),
MEASURE(0, ("ro", 0)),
MEASURE(1, ("ro", 1)),
).wrap_in_numshots_loop(1000)
qpu = get_qpu("Aspen-11")
native_quil = qpu.compiler.quil_to_native_quil(program) # quilc must be running locally to compile
exe = qpu.compile(native_quil, to_native_gates=False) # Skip quilc in the cloud
results = qpu.run(exe)
```
### 3. Running Parametrized Circuits in a Batch
When you have a program which should be run across multiple parameters, you can submit all the parameters at once to significantly improve performance.
```python
import numpy as np
from pyquil_for_azure_quantum import get_qpu
from pyquil.gates import MEASURE, RX
from pyquil.quil import Program
from pyquil.quilbase import Declare
from pyquil.quilatom import MemoryReference
program = Program(
Declare("ro", "BIT", 1),
Declare("theta", "REAL", 1),
RX(MemoryReference("theta"), 0),
MEASURE(0, ("ro", 0)),
).wrap_in_numshots_loop(1000)
qpu = get_qpu("Aspen-11")
compiled = qpu.compile(program)
memory_map = {"theta": [[0.0], [np.pi], [2 * np.pi]]}
results = qpu.run_batch(compiled, memory_map) # This is a list of results, one for each parameter set.
results_0 = results[0].get_register_map().get("ro")
results_pi = results[1].get_register_map().get("ro")
results_2pi = results[2].get_register_map().get("ro")
```
> Microsoft, Microsoft Azure, and Azure Quantum are trademarks of the Microsoft group of companies.
[azure-quantum]: https://github.com/microsoft/qdk-python
[pyQuil]: https://pyquil-docs.rigetti.com/en/stable/
[azure auth]: https://docs.microsoft.com/en-us/azure/quantum/optimization-authenticate-service-principal#authenticate-as-the-service-principal
Raw data
{
"_id": null,
"home_page": "https://github.com/rigetti/pyquil-for-azure-quantum",
"name": "pyquil-for-azure-quantum",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.12",
"maintainer_email": "",
"keywords": "",
"author": "Dylan Anthony",
"author_email": "danthony@rigetti.com",
"download_url": "https://files.pythonhosted.org/packages/c3/cf/24ec73529c69b08e19b4a9c4c95dc4146930906d3cd5a4de0a0394c9a0e4/pyquil_for_azure_quantum-0.0.3.tar.gz",
"platform": null,
"description": "# pyquil-for-azure-quantum\n\nThis library allows you to use [pyQuil] to run programs on [Azure Quantum](https://azure.microsoft.com/en-us/services/quantum/) against Rigetti targets. Internally, it leverages the [azure-quantum] package.\n\n## Usage\n\nGenerally, you use [pyQuil] normally, with a few differences:\n\n1. Instead of `pyquil.get_qc()`, you will use either `pyquil_azure_quantum.get_qvm()` or `pyquil_azure_quantum.get_qpu()`.\n2. You do not need to have `qvm` or `quilc` running in order to run programs through `pyquil_azure_quantum`. You may still run them if you wish to run QVM locally instead of passing through Azure or if you wish to precompile your programs (e.g., to inspect the exact Quil that will run).\n3. You do not need a QCS account or credentials unless you wish to manually inspect the details of the QPU (e.g., list all qubits).\n4. You **must** have these environment variables set:\n 1. `AZURE_QUANTUM_SUBSCRIPTION_ID`: The Azure subscription ID where the Quantum Workspace is located.\n 2. `AZURE_QUANTUM_WORKSPACE_RG`: The Azure resource group where the Quantum Workspace is located. \n 3. `AZURE_QUANTUM_WORKSPACE_NAME`: The name of the Quantum Workspace.\n 4. `AZURE_QUANTUM_WORKSPACE_LOCATION`: The region where the Quantum Workspace is located.\n5. You **may** [set environment variables][azure auth] to authenticate with Azure. If you do not, a browser will open to the Azure portal to authenticate.\n6. Whenever possible, you should prefer using `AzureQuantumComputer.run_batch()` over `Program.write_memory(); AzureQuantumComputer.run()` to run programs which have multiple parameters. Calling `write_memory()` followed by `run()` will still work but will be much slower than running a batch of parameters all at once.\n\n\n## Examples\n\n### 1. Leveraging Hosted QVM and quilc\n\nWith this program, you do not need to run `qvm` nor `quilc` locally in order to leverage them, as they can run through Azure Quantum.\n\n```python\nfrom pyquil_for_azure_quantum import get_qpu, get_qvm\nfrom pyquil.gates import CNOT, MEASURE, H\nfrom pyquil.quil import Program\nfrom pyquil.quilbase import Declare\n\nprogram = Program(\n Declare(\"ro\", \"BIT\", 2),\n H(0),\n CNOT(0, 1),\n MEASURE(0, (\"ro\", 0)),\n MEASURE(1, (\"ro\", 1)),\n).wrap_in_numshots_loop(1000)\n\nqpu = get_qpu(\"Aspen-11\")\nqvm = get_qvm()\n\nexe = qpu.compile(program) # This does not run quilc yet.\nresults = qpu.run(exe) # Quilc will run in the cloud before executing the program.\nqvm_results = qvm.run(exe) # This runs the program on QVM in the cloud, not locally.\n```\n\n### 2. Running quilc Locally\n\nYou can optionally run quilc yourself and disable the use of quilc in the cloud.\n\n```python\nfrom pyquil_for_azure_quantum import get_qpu\nfrom pyquil.gates import CNOT, MEASURE, H\nfrom pyquil.quil import Program\nfrom pyquil.quilbase import Declare\n\n\nprogram = Program(\n Declare(\"ro\", \"BIT\", 2),\n H(0),\n CNOT(0, 1),\n MEASURE(0, (\"ro\", 0)),\n MEASURE(1, (\"ro\", 1)),\n).wrap_in_numshots_loop(1000)\nqpu = get_qpu(\"Aspen-11\")\nnative_quil = qpu.compiler.quil_to_native_quil(program) # quilc must be running locally to compile\nexe = qpu.compile(native_quil, to_native_gates=False) # Skip quilc in the cloud\nresults = qpu.run(exe)\n```\n\n### 3. Running Parametrized Circuits in a Batch\n\nWhen you have a program which should be run across multiple parameters, you can submit all the parameters at once to significantly improve performance.\n\n```python\nimport numpy as np\nfrom pyquil_for_azure_quantum import get_qpu\nfrom pyquil.gates import MEASURE, RX\nfrom pyquil.quil import Program\nfrom pyquil.quilbase import Declare\nfrom pyquil.quilatom import MemoryReference\n\n\nprogram = Program(\n Declare(\"ro\", \"BIT\", 1),\n Declare(\"theta\", \"REAL\", 1),\n RX(MemoryReference(\"theta\"), 0),\n MEASURE(0, (\"ro\", 0)),\n).wrap_in_numshots_loop(1000)\n\nqpu = get_qpu(\"Aspen-11\")\ncompiled = qpu.compile(program)\n\nmemory_map = {\"theta\": [[0.0], [np.pi], [2 * np.pi]]}\nresults = qpu.run_batch(compiled, memory_map) # This is a list of results, one for each parameter set.\n\nresults_0 = results[0].get_register_map().get(\"ro\")\nresults_pi = results[1].get_register_map().get(\"ro\")\nresults_2pi = results[2].get_register_map().get(\"ro\")\n```\n\n> Microsoft, Microsoft Azure, and Azure Quantum are trademarks of the Microsoft group of companies. \n\n[azure-quantum]: https://github.com/microsoft/qdk-python\n[pyQuil]: https://pyquil-docs.rigetti.com/en/stable/\n[azure auth]: https://docs.microsoft.com/en-us/azure/quantum/optimization-authenticate-service-principal#authenticate-as-the-service-principal\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Run Quil programs on Microsoft Azure Quantum using pyQuil",
"version": "0.0.3",
"project_urls": {
"Documentation": "https://rigetti.github.io/pyquil-for-azure-quantum/",
"Homepage": "https://github.com/rigetti/pyquil-for-azure-quantum",
"Repository": "https://github.com/rigetti/pyquil-for-azure-quantum"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a935693e24adfcb79c7aad584cc99543d0c9d2075200889a0a2370f01c96b2d",
"md5": "d54fae10111cfb9225073e7b62bbb35c",
"sha256": "ff4c3fe4705f36f6980dc1e700e8b15b5c08e901b14df8712f0cacfc05109a4b"
},
"downloads": -1,
"filename": "pyquil_for_azure_quantum-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d54fae10111cfb9225073e7b62bbb35c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.12",
"size": 11791,
"upload_time": "2024-03-01T18:50:49",
"upload_time_iso_8601": "2024-03-01T18:50:49.534544Z",
"url": "https://files.pythonhosted.org/packages/5a/93/5693e24adfcb79c7aad584cc99543d0c9d2075200889a0a2370f01c96b2d/pyquil_for_azure_quantum-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c3cf24ec73529c69b08e19b4a9c4c95dc4146930906d3cd5a4de0a0394c9a0e4",
"md5": "6e8c40c4ec51b7164c6bb01f8df4fa79",
"sha256": "7d4c78a993b468b05f64439801f1cffc93cbeaf7a820c2f9c0a2d7c64309d87e"
},
"downloads": -1,
"filename": "pyquil_for_azure_quantum-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "6e8c40c4ec51b7164c6bb01f8df4fa79",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.12",
"size": 10489,
"upload_time": "2024-03-01T18:50:50",
"upload_time_iso_8601": "2024-03-01T18:50:50.623667Z",
"url": "https://files.pythonhosted.org/packages/c3/cf/24ec73529c69b08e19b4a9c4c95dc4146930906d3cd5a4de0a0394c9a0e4/pyquil_for_azure_quantum-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-01 18:50:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rigetti",
"github_project": "pyquil-for-azure-quantum",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyquil-for-azure-quantum"
}
JSON
