# Amazon Braket Python SDK
[](https://pypi.python.org/pypi/amazon-braket-sdk)
[](https://pypi.python.org/pypi/amazon-braket-sdk)
[](https://github.com/amazon-braket/amazon-braket-sdk-python/actions/workflows/python-package.yml)
[](https://codecov.io/gh/amazon-braket/amazon-braket-sdk-python)
[](https://amazon-braket-sdk-python.readthedocs.io/en/latest/?badge=latest)
The Amazon Braket Python SDK is an open source library that provides a framework that you can use to interact with quantum computing hardware devices through Amazon Braket.
## Prerequisites
Before you begin working with the Amazon Braket SDK, make sure that you've installed or configured the following prerequisites.
### Python 3.9 or greater
Download and install Python 3.9 or greater from [Python.org](https://www.python.org/downloads/).
### Git
Install Git from https://git-scm.com/downloads. Installation instructions are provided on the download page.
### IAM user or role with required permissions
As a managed service, Amazon Braket performs operations on your behalf on the AWS hardware that is managed by Amazon Braket. Amazon Braket can perform only operations that the user permits. You can read more about which permissions are necessary in the AWS Documentation.
The Braket Python SDK should not require any additional permissions aside from what is required for using Braket. However, if you are using an IAM role with a path in it, you should grant permission for iam:GetRole.
To learn more about IAM user, roles, and policies, see [Adding and Removing IAM Identity Permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html).
### Boto3 and setting up AWS credentials
Follow the installation [instructions](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) for Boto3 and setting up AWS credentials.
**Note:** Make sure that your AWS region is set to one supported by Amazon Braket. You can check this in your AWS configuration file, which is located by default at `~/.aws/config`.
### Configure your AWS account with the resources necessary for Amazon Braket
If you are new to Amazon Braket, onboard to the service and create the resources necessary to use Amazon Braket using the [AWS console](https://console.aws.amazon.com/braket/home ).
## Installing the Amazon Braket Python SDK
The Amazon Braket Python SDK can be installed with pip as follows:
```bash
pip install amazon-braket-sdk
```
You can also install from source by cloning this repository and running a pip install command in the root directory of the repository:
```bash
git clone https://github.com/amazon-braket/amazon-braket-sdk-python.git
cd amazon-braket-sdk-python
pip install .
```
### Check the version you have installed
You can view the version of the amazon-braket-sdk you have installed by using the following command:
```bash
pip show amazon-braket-sdk
```
You can also check your version of `amazon-braket-sdk` from within Python:
```
>>> import braket._sdk as braket_sdk
>>> braket_sdk.__version__
```
### Updating the Amazon Braket Python SDK
You can update the version of the amazon-braket-sdk you have installed by using the following command:
```bash
pip install amazon-braket-sdk --upgrade --upgrade-strategy eager
```
## Usage
### Running a circuit on an AWS simulator
```python
import boto3
from braket.aws import AwsDevice
from braket.circuits import Circuit
device = AwsDevice("arn:aws:braket:::device/quantum-simulator/amazon/sv1")
bell = Circuit().h(0).cnot(0, 1)
task = device.run(bell, shots=100)
print(task.result().measurement_counts)
```
The code sample imports the Amazon Braket framework, then defines the device to use (the SV1 AWS simulator). It then creates a Bell Pair circuit, executes the circuit on the simulator and prints the results of the hybrid job. This example can be found in `../examples/bell.py`.
### Running multiple quantum tasks at once
Many quantum algorithms need to run multiple independent circuits, and submitting the circuits in parallel can be faster than submitting them one at a time. In particular, parallel quantum task processing provides a significant speed up when using simulator devices. The following example shows how to run a batch of quantum tasks on SV1:
```python
circuits = [bell for _ in range(5)]
batch = device.run_batch(circuits, shots=100)
# The result of the first quantum task in the batch
print(batch.results()[0].measurement_counts)
```
### Running a hybrid job
```python
from braket.aws import AwsQuantumJob
job = AwsQuantumJob.create(
device="arn:aws:braket:::device/quantum-simulator/amazon/sv1",
source_module="job.py",
entry_point="job:run_job",
wait_until_complete=True,
)
print(job.result())
```
where `run_job` is a function in the file `job.py`.
The code sample imports the Amazon Braket framework, then creates a hybrid job with the entry point being the `run_job` function. The hybrid job creates quantum tasks against the SV1 AWS Simulator. The hybrid job runs synchronously, and prints logs until it completes. The complete example can be found in `../examples/job.py`.
### Available Simulators
Amazon Braket provides access to two types of simulators: fully managed simulators, available through the Amazon Braket service, and the local simulators that are part of the Amazon Braket SDK.
- Fully managed simulators offer high-performance circuit simulations. These simulators can handle circuits larger than circuits that run on quantum hardware. For example, the SV1 state vector simulator shown in the previous examples requires approximately 1 or 2 hours to complete a 34-qubit, dense, and square circuit (circuit depth = 34), depending on the type of gates used and other factors.
- The Amazon Braket Python SDK includes an implementation of quantum simulators that can run circuits on your local, classic hardware. For example the braket_sv local simulator is well suited for rapid prototyping on small circuits up to 25 qubits, depending on the hardware specifications of your Braket notebook instance or your local environment. An example of how to execute the quantum task locally is included in the repository `../examples/local_bell.py`.
For a list of available simulators and their features, consult the [Amazon Braket Developer Guide](https://docs.aws.amazon.com/braket/latest/developerguide/braket-devices.html).
### Debugging logs
Quantum tasks sent to QPUs don't always run right away. To view quantum task status, you can enable debugging logs. An example of how to enable these logs is included in repo: `../examples/debug_bell.py`. This example enables quantum task logging so that status updates are continuously printed to the terminal after a quantum task is executed. The logs can also be configured to save to a file or output to another stream. You can use the debugging example to get information on the quantum tasks you submit, such as the current status, so that you know when your quantum task completes.
### Running a Quantum Algorithm on a Quantum Computer
With Amazon Braket, you can run your quantum circuit on a physical quantum computer.
The following example executes the same Bell Pair example described to validate your configuration on a Rigetti quantum computer.
```python
import boto3
from braket.circuits import Circuit
from braket.aws import AwsDevice
device = AwsDevice("arn:aws:braket:::device/qpu/rigetti/Aspen-8")
bell = Circuit().h(0).cnot(0, 1)
task = device.run(bell)
print(task.result().measurement_counts)
```
When you execute your task, Amazon Braket polls for a result. By default, Braket polls for 5 days; however, it is possible to change this by modifying the `poll_timeout_seconds` parameter in `AwsDevice.run`, as in the example below. Keep in mind that if your polling timeout is too short, results may not be returned within the polling time, such as when a QPU is unavailable, and a local timeout error is returned. You can always restart the polling by using `task.result()`.
```python
task = device.run(bell, poll_timeout_seconds=86400) # 1 day
print(task.result().measurement_counts)
```
To select a quantum hardware device, specify its ARN as the value of the `device_arn` argument. A list of available quantum devices and their features can be found in the [Amazon Braket Developer Guide](https://docs.aws.amazon.com/braket/latest/developerguide/braket-devices.html).
**Important** Quantum tasks may not run immediately on the QPU. The QPUs only execute quantum tasks during execution windows. To find their execution windows, please refer to the [AWS console](https://console.aws.amazon.com/braket/home) in the "Devices" tab.
## Sample Notebooks
Sample Jupyter notebooks can be found in the [amazon-braket-examples](https://github.com/amazon-braket/amazon-braket-examples/) repo.
## Braket Python SDK API Reference Documentation
The API reference, can be found on [Read the Docs](https://amazon-braket-sdk-python.readthedocs.io/en/latest/).
**To generate the API Reference HTML in your local environment**
To generate the HTML, first change directories (`cd`) to position the cursor in the `amazon-braket-sdk-python` directory. Then, run the following command to generate the HTML documentation files:
```bash
pip install tox
tox -e docs
```
To view the generated documentation, open the following file in a browser:
`../amazon-braket-sdk-python/build/documentation/html/index.html`
## Testing
This repository has both unit and integration tests.
To run the tests, make sure to install test dependencies first:
```bash
pip install -e "amazon-braket-sdk-python[test]"
```
### Unit Tests
To run the unit tests:
```bash
tox -e unit-tests
```
You can also pass in various pytest arguments to run selected tests:
```bash
tox -e unit-tests -- your-arguments
```
For more information, please see [pytest usage](https://docs.pytest.org/en/stable/usage.html).
To run linters and doc generators and unit tests:
```bash
tox
```
### Integration Tests
First, configure a profile to use your account to interact with AWS. To learn more, see [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).
After you create a profile, use the following command to set the `AWS_PROFILE` so that all future commands can access your AWS account and resources.
```bash
export AWS_PROFILE=YOUR_PROFILE_NAME
```
To run the integration tests for local hybrid jobs, you need to have Docker installed and running. To install Docker follow these instructions: [Install Docker](https://docs.docker.com/get-docker/)
Run the tests:
```bash
tox -e integ-tests
```
As with unit tests, you can also pass in various pytest arguments:
```bash
tox -e integ-tests -- your-arguments
```
## Support
### Issues and Bug Reports
If you encounter bugs or face issues while using the SDK, please let us know by posting
the issue on our [Github issue tracker](https://github.com/amazon-braket/amazon-braket-sdk-python/issues/).
For other issues or general questions, please ask on the [Quantum Computing Stack Exchange](https://quantumcomputing.stackexchange.com/questions/ask?Tags=amazon-braket).
### Feedback and Feature Requests
If you have feedback or features that you would like to see on Amazon Braket, we would love to hear from you!
[Github issues](https://github.com/amazon-braket/amazon-braket-sdk-python/issues/) is our preferred mechanism for collecting feedback and feature requests, allowing other users
to engage in the conversation, and +1 issues to help drive priority.
### Code contributors
[](https://github.com/amazon-braket/amazon-braket-sdk-python/graphs/contributors)
## License
This project is licensed under the Apache-2.0 License.
Raw data
{
"_id": null,
"home_page": "https://github.com/amazon-braket/amazon-braket-sdk-python",
"name": "amazon-braket-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "Amazon AWS Quantum",
"author": "Amazon Web Services",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a9/75/2570dfe995d6c539d5fad6eea707eda67c28ab1de217263308470a8c041a/amazon_braket_sdk-1.78.0.tar.gz",
"platform": null,
"description": "# Amazon Braket Python SDK\n\n[](https://pypi.python.org/pypi/amazon-braket-sdk)\n[](https://pypi.python.org/pypi/amazon-braket-sdk)\n[](https://github.com/amazon-braket/amazon-braket-sdk-python/actions/workflows/python-package.yml)\n[](https://codecov.io/gh/amazon-braket/amazon-braket-sdk-python)\n[](https://amazon-braket-sdk-python.readthedocs.io/en/latest/?badge=latest)\n\nThe Amazon Braket Python SDK is an open source library that provides a framework that you can use to interact with quantum computing hardware devices through Amazon Braket.\n\n## Prerequisites\nBefore you begin working with the Amazon Braket SDK, make sure that you've installed or configured the following prerequisites.\n\n### Python 3.9 or greater\nDownload and install Python 3.9 or greater from [Python.org](https://www.python.org/downloads/).\n\n### Git\nInstall Git from https://git-scm.com/downloads. Installation instructions are provided on the download page.\n\n### IAM user or role with required permissions\nAs a managed service, Amazon Braket performs operations on your behalf on the AWS hardware that is managed by Amazon Braket. Amazon Braket can perform only operations that the user permits. You can read more about which permissions are necessary in the AWS Documentation.\n\nThe Braket Python SDK should not require any additional permissions aside from what is required for using Braket. However, if you are using an IAM role with a path in it, you should grant permission for iam:GetRole.\n\nTo learn more about IAM user, roles, and policies, see [Adding and Removing IAM Identity Permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html).\n\n### Boto3 and setting up AWS credentials\n\nFollow the installation [instructions](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) for Boto3 and setting up AWS credentials.\n\n**Note:** Make sure that your AWS region is set to one supported by Amazon Braket. You can check this in your AWS configuration file, which is located by default at `~/.aws/config`.\n\n### Configure your AWS account with the resources necessary for Amazon Braket\nIf you are new to Amazon Braket, onboard to the service and create the resources necessary to use Amazon Braket using the [AWS console](https://console.aws.amazon.com/braket/home ).\n\n## Installing the Amazon Braket Python SDK\n\nThe Amazon Braket Python SDK can be installed with pip as follows:\n\n```bash\npip install amazon-braket-sdk\n```\n\nYou can also install from source by cloning this repository and running a pip install command in the root directory of the repository:\n\n```bash\ngit clone https://github.com/amazon-braket/amazon-braket-sdk-python.git\ncd amazon-braket-sdk-python\npip install .\n```\n\n### Check the version you have installed\nYou can view the version of the amazon-braket-sdk you have installed by using the following command:\n```bash\npip show amazon-braket-sdk\n```\n\nYou can also check your version of `amazon-braket-sdk` from within Python:\n\n```\n>>> import braket._sdk as braket_sdk\n>>> braket_sdk.__version__\n```\n\n### Updating the Amazon Braket Python SDK\nYou can update the version of the amazon-braket-sdk you have installed by using the following command:\n```bash\npip install amazon-braket-sdk --upgrade --upgrade-strategy eager\n```\n\n## Usage\n\n### Running a circuit on an AWS simulator\n\n```python\nimport boto3\nfrom braket.aws import AwsDevice\nfrom braket.circuits import Circuit\n\ndevice = AwsDevice(\"arn:aws:braket:::device/quantum-simulator/amazon/sv1\")\n\nbell = Circuit().h(0).cnot(0, 1)\ntask = device.run(bell, shots=100)\nprint(task.result().measurement_counts)\n```\n\nThe code sample imports the Amazon Braket framework, then defines the device to use (the SV1 AWS simulator). It then creates a Bell Pair circuit, executes the circuit on the simulator and prints the results of the hybrid job. This example can be found in `../examples/bell.py`.\n\n### Running multiple quantum tasks at once\n\nMany quantum algorithms need to run multiple independent circuits, and submitting the circuits in parallel can be faster than submitting them one at a time. In particular, parallel quantum task processing provides a significant speed up when using simulator devices. The following example shows how to run a batch of quantum tasks on SV1:\n\n```python\ncircuits = [bell for _ in range(5)]\nbatch = device.run_batch(circuits, shots=100)\n# The result of the first quantum task in the batch\nprint(batch.results()[0].measurement_counts) \n```\n\n### Running a hybrid job\n\n```python\nfrom braket.aws import AwsQuantumJob\n\njob = AwsQuantumJob.create(\n device=\"arn:aws:braket:::device/quantum-simulator/amazon/sv1\",\n source_module=\"job.py\",\n entry_point=\"job:run_job\",\n wait_until_complete=True,\n)\nprint(job.result())\n```\nwhere `run_job` is a function in the file `job.py`.\n\n\nThe code sample imports the Amazon Braket framework, then creates a hybrid job with the entry point being the `run_job` function. The hybrid job creates quantum tasks against the SV1 AWS Simulator. The hybrid job runs synchronously, and prints logs until it completes. The complete example can be found in `../examples/job.py`.\n\n### Available Simulators\nAmazon Braket provides access to two types of simulators: fully managed simulators, available through the Amazon Braket service, and the local simulators that are part of the Amazon Braket SDK.\n\n- Fully managed simulators offer high-performance circuit simulations. These simulators can handle circuits larger than circuits that run on quantum hardware. For example, the SV1 state vector simulator shown in the previous examples requires approximately 1 or 2 hours to complete a 34-qubit, dense, and square circuit (circuit depth = 34), depending on the type of gates used and other factors.\n- The Amazon Braket Python SDK includes an implementation of quantum simulators that can run circuits on your local, classic hardware. For example the braket_sv local simulator is well suited for rapid prototyping on small circuits up to 25 qubits, depending on the hardware specifications of your Braket notebook instance or your local environment. An example of how to execute the quantum task locally is included in the repository `../examples/local_bell.py`.\n\nFor a list of available simulators and their features, consult the [Amazon Braket Developer Guide](https://docs.aws.amazon.com/braket/latest/developerguide/braket-devices.html).\n\n### Debugging logs\n\nQuantum tasks sent to QPUs don't always run right away. To view quantum task status, you can enable debugging logs. An example of how to enable these logs is included in repo: `../examples/debug_bell.py`. This example enables quantum task logging so that status updates are continuously printed to the terminal after a quantum task is executed. The logs can also be configured to save to a file or output to another stream. You can use the debugging example to get information on the quantum tasks you submit, such as the current status, so that you know when your quantum task completes.\n\n### Running a Quantum Algorithm on a Quantum Computer\nWith Amazon Braket, you can run your quantum circuit on a physical quantum computer.\n\nThe following example executes the same Bell Pair example described to validate your configuration on a Rigetti quantum computer.\n\n```python\nimport boto3\nfrom braket.circuits import Circuit\nfrom braket.aws import AwsDevice\n\ndevice = AwsDevice(\"arn:aws:braket:::device/qpu/rigetti/Aspen-8\")\n\nbell = Circuit().h(0).cnot(0, 1)\ntask = device.run(bell)\nprint(task.result().measurement_counts)\n```\n\nWhen you execute your task, Amazon Braket polls for a result. By default, Braket polls for 5 days; however, it is possible to change this by modifying the `poll_timeout_seconds` parameter in `AwsDevice.run`, as in the example below. Keep in mind that if your polling timeout is too short, results may not be returned within the polling time, such as when a QPU is unavailable, and a local timeout error is returned. You can always restart the polling by using `task.result()`.\n\n```python\ntask = device.run(bell, poll_timeout_seconds=86400) # 1 day\nprint(task.result().measurement_counts)\n```\n\nTo select a quantum hardware device, specify its ARN as the value of the `device_arn` argument. A list of available quantum devices and their features can be found in the [Amazon Braket Developer Guide](https://docs.aws.amazon.com/braket/latest/developerguide/braket-devices.html).\n\n**Important** Quantum tasks may not run immediately on the QPU. The QPUs only execute quantum tasks during execution windows. To find their execution windows, please refer to the [AWS console](https://console.aws.amazon.com/braket/home) in the \"Devices\" tab.\n\n## Sample Notebooks\nSample Jupyter notebooks can be found in the [amazon-braket-examples](https://github.com/amazon-braket/amazon-braket-examples/) repo.\n\n## Braket Python SDK API Reference Documentation\n\nThe API reference, can be found on [Read the Docs](https://amazon-braket-sdk-python.readthedocs.io/en/latest/).\n\n**To generate the API Reference HTML in your local environment**\n\nTo generate the HTML, first change directories (`cd`) to position the cursor in the `amazon-braket-sdk-python` directory. Then, run the following command to generate the HTML documentation files:\n\n```bash\npip install tox\ntox -e docs\n```\n\nTo view the generated documentation, open the following file in a browser:\n`../amazon-braket-sdk-python/build/documentation/html/index.html`\n\n## Testing\n\nThis repository has both unit and integration tests.\n\nTo run the tests, make sure to install test dependencies first:\n\n```bash\npip install -e \"amazon-braket-sdk-python[test]\"\n```\n\n### Unit Tests\n\nTo run the unit tests:\n\n```bash\ntox -e unit-tests\n```\n\nYou can also pass in various pytest arguments to run selected tests:\n\n```bash\ntox -e unit-tests -- your-arguments\n```\n\nFor more information, please see [pytest usage](https://docs.pytest.org/en/stable/usage.html).\n\nTo run linters and doc generators and unit tests:\n\n```bash\ntox\n```\n\n### Integration Tests\n\nFirst, configure a profile to use your account to interact with AWS. To learn more, see [Configure AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).\n\nAfter you create a profile, use the following command to set the `AWS_PROFILE` so that all future commands can access your AWS account and resources.\n\n```bash\nexport AWS_PROFILE=YOUR_PROFILE_NAME\n```\nTo run the integration tests for local hybrid jobs, you need to have Docker installed and running. To install Docker follow these instructions: [Install Docker](https://docs.docker.com/get-docker/)\n\nRun the tests:\n\n```bash\ntox -e integ-tests\n```\n\nAs with unit tests, you can also pass in various pytest arguments:\n\n```bash\ntox -e integ-tests -- your-arguments\n```\n\n## Support\n\n### Issues and Bug Reports\n\nIf you encounter bugs or face issues while using the SDK, please let us know by posting\nthe issue on our [Github issue tracker](https://github.com/amazon-braket/amazon-braket-sdk-python/issues/).\nFor other issues or general questions, please ask on the [Quantum Computing Stack Exchange](https://quantumcomputing.stackexchange.com/questions/ask?Tags=amazon-braket).\n\n### Feedback and Feature Requests\n\nIf you have feedback or features that you would like to see on Amazon Braket, we would love to hear from you!\n[Github issues](https://github.com/amazon-braket/amazon-braket-sdk-python/issues/) is our preferred mechanism for collecting feedback and feature requests, allowing other users\nto engage in the conversation, and +1 issues to help drive priority.\n\n### Code contributors\n\n[](https://github.com/amazon-braket/amazon-braket-sdk-python/graphs/contributors)\n\n## License\nThis project is licensed under the Apache-2.0 License.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "An open source library for interacting with quantum computing devices on Amazon Braket",
"version": "1.78.0",
"project_urls": {
"Homepage": "https://github.com/amazon-braket/amazon-braket-sdk-python"
},
"split_keywords": [
"amazon",
"aws",
"quantum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0a14b7ddb137efe3f0c1f2a46c22eef1632036dd6d23884ecf20014ffef7e78c",
"md5": "24d5078f816242ede76aae1a77c606f2",
"sha256": "e6d11e9b8e71039ab75edc346df071fadd59c12943b6b8328b62b0b6a1227278"
},
"downloads": -1,
"filename": "amazon_braket_sdk-1.78.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "24d5078f816242ede76aae1a77c606f2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 310097,
"upload_time": "2024-04-18T16:19:46",
"upload_time_iso_8601": "2024-04-18T16:19:46.261523Z",
"url": "https://files.pythonhosted.org/packages/0a/14/b7ddb137efe3f0c1f2a46c22eef1632036dd6d23884ecf20014ffef7e78c/amazon_braket_sdk-1.78.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a9752570dfe995d6c539d5fad6eea707eda67c28ab1de217263308470a8c041a",
"md5": "c814681f338962669de7228151b5600d",
"sha256": "9f0c49af85c4bd1be8ab190959f6bfa8625f8249543f0b471b1a3b36e24c6113"
},
"downloads": -1,
"filename": "amazon_braket_sdk-1.78.0.tar.gz",
"has_sig": false,
"md5_digest": "c814681f338962669de7228151b5600d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 398034,
"upload_time": "2024-04-18T16:19:50",
"upload_time_iso_8601": "2024-04-18T16:19:50.370940Z",
"url": "https://files.pythonhosted.org/packages/a9/75/2570dfe995d6c539d5fad6eea707eda67c28ab1de217263308470a8c041a/amazon_braket_sdk-1.78.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-18 16:19:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "amazon-braket",
"github_project": "amazon-braket-sdk-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "amazon-braket-sdk"
}
JSON
