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.
Before you begin working with the Amazon Braket SDK, make sure that you've installed or configured the following prerequisites.
Download and install Python 3.7.2 or greater from Python.org.
Install Git from https://git-scm.com/downloads. Installation instructions are provided on the download page.
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.
Follow the installation instructions 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
If you are new to Amazon Braket, onboard to the service and create the resources necessary to use Amazon Braket using the AWS console.
The Amazon Braket Python SDK can be installed with pip as follows:
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:
git clone https://github.com/aws/amazon-braket-sdk-python.git cd amazon-braket-sdk-python pip install .
You can view the version of the amazon-braket-sdk you have installed by using the following command:
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__
You can update the version of the amazon-braket-sdk you have installed by using the following command:
pip install amazon-braket-sdk --upgrade --upgrade-strategy eager
import boto3 from braket.aws import AwsDevice from braket.circuits import Circuit device = AwsDevice("arn:aws:braket:::device/quantum-simulator/amazon/sv1") s3_folder = ("amazon-braket-Your-Bucket-Name", "folder-name") # Use the S3 bucket you created during onboarding bell = Circuit().h(0).cnot(0, 1) task = device.run(bell, s3_folder, 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). The
s3_folder statement defines the Amazon S3 bucket for the task result and the folder in the bucket to store the task result. This folder is created when you run the task. It then creates a Bell Pair circuit, executes the circuit on the simulator and prints the results of the job. This example can be found in
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 task processing provides a significant speed up when using simulator devices. The following example shows how to run a batch of tasks on SV1:
circuits = [bell for _ in range(5)] batch = device.run_batch(circuits, s3_folder, shots=100) print(batch.results().measurement_counts) # The result of the first task in the batch
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.
For a list of available simulators and their features, consult the Amazon Braket Developer Guide.
Tasks sent to QPUs don't always run right away. To view 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 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 tasks you submit, such as the current status, so that you know when your task completes.
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.
import boto3 from braket.circuits import Circuit from braket.aws import AwsDevice device = AwsDevice("arn:aws:braket:::device/qpu/rigetti/Aspen-8") s3_folder = ("amazon-braket-Your-Bucket-Name", "RIGETTI") # Use the S3 bucket you created during onboarding bell = Circuit().h(0).cnot(0, 1) task = device.run(bell, s3_folder) 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 = device.run(bell, s3_folder, 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.
Important Tasks may not run immediately on the QPU. The QPUs only execute tasks during execution windows. To find their execution windows, please refer to the AWS console in the "Devices" tab.
Sample Jupyter notebooks can be found in the amazon-braket-examples repo.
The API reference, can be found on Read the Docs.
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:
pip install tox tox -e docs
To view the generated documentation, open the following file in a browser:
This repository has both unit and integration tests.
To run the tests, make sure to install test dependencies first:
pip install -e "amazon-braket-sdk-python[test]"
To run the unit tests:
tox -e unit-tests
You can also pass in various pytest arguments to run selected tests:
tox -e unit-tests -- your-arguments
For more information, please see pytest usage.
To run linters and doc generators and unit tests:
First, configure a profile to use your account to interact with AWS. To learn more, see Configure AWS CLI.
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.
Run the tests:
tox -e integ-tests
As with unit tests, you can also pass in various pytest arguments:
tox -e integ-tests -- your-arguments
If you encounter bugs or face issues while using the SDK, please let us know by posting
the issue on our Github issue tracker.
For issues with the Amazon Braket service in general, please use the Developer Forum.
If you have feedback or features that you would like to see on Amazon Braket, we would love to hear from you!
Github 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.
This project is licensed under the Apache-2.0 License.