Cloud and interoperability

amazon-braket-sdk-python

Maintained by aws

The Amazon Braket SDK is a cloud-facing Python entry point for running quantum workflows across managed services and provider integrations.

PythonApache-2.0vpy311FlagshipQtangl relevant

View on GitHub Open project siteCompare

Resource snapshot

Get running in a few lines.

Quickstart

import boto3
from braket.aws import AwsDevice
from braket.circuits import Circuit
from braket.devices import Devices

device = AwsDevice(Devices.Amazon.SV1)

bell = Circuit().h(0).cnot(0, 1)
task = device.run(bell, shots=100)
print(task.result().measurement_counts)

What it is

Braket is useful because it exposes the cloud layer of the ecosystem: job submission, managed runtimes, provider abstraction, and the operational realities of working through a hosted platform instead of a purely local SDK.

For readers mapping the landscape, it helps answer a practical question: what changes when quantum development moves from a local notebook or simulator into a provider-managed workflow?

Who it's for

Developers evaluating managed quantum services, provider integrations, or cloud-based experimentation paths.

What you can build or learn

Compare cloud access patterns against local SDK-only workflows.
Understand how provider abstraction and runtime orchestration are exposed in code.
See how managed services fit into a broader hybrid stack.

Code samples

Examples from the repository.

Ahs Lattice Factory (examples/ahs_lattice_factory.py)

#
# Licensed under the Apache License, Version 2.0 (the "License"). You
# may not use this file except in compliance with the License. A copy of
# the License is located at
#
#     http://aws.amazon.com/apache2.0/
#
# or in the "license" file accompanying this file. This file 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.
"""
Demonstration of AHS AtomArrangement factory methods.
This example shows how to use the new factory methods to create common
lattice arrangements for Analog Hamiltonian Simulation (AHS).
"""
from braket.ahs import AtomArrangement, Canvas, SiteType
# Define a canvas (boundary region) where atoms can be placed
canvas_boundary = [
    (0, 0),  # Bottom-left corner
    (30e-6, 0),  # Bottom-right corner
    (30e-6, 30e-6),  # Top-right corner
    (0, 30e-6),  # Top-left corner
]
canvas = Canvas(canvas_boundary)
print("AHS AtomArrangement Factory Methods Demo")
print("=" * 50)
# 1. Square Lattice
print("\n1. Square Lattice:")
spacing = 5e-6
square_arrangement = AtomArrangement.from_square_lattice(spacing, canvas)
print(f"   Created {len(square_arrangement)} atoms in square lattice")
print(f"   Spacing: {spacing * 1e6:.1f} μm")
# 2. Rectangular Lattice
print("\n2. Rectangular Lattice:")
spacing_x = 4e-6
spacing_y = 6e-6
rect_arrangement = AtomArrangement.from_rectangular_lattice(spacing_x, spacing_y, canvas)
print(f"   Created {len(rect_arrangement)} atoms in rectangular lattice")
print(f"   X spacing: {spacing_x * 1e6:.1f} μm, Y spacing: {spacing_y * 1e6:.1f} μm")

Bell (examples/bell.py)

#
# Licensed under the Apache License, Version 2.0 (the "License"). You
# may not use this file except in compliance with the License. A copy of
# the License is located at
#
#     http://aws.amazon.com/apache2.0/
#
# or in the "license" file accompanying this file. This file 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.
from braket.aws import AwsDevice
from braket.circuits import Circuit
from braket.devices import Devices
device = AwsDevice(Devices.Amazon.SV1)
# https://wikipedia.org/wiki/Bell_state
bell = Circuit().h(0).cnot(0, 1)
task = device.run(bell, shots=100)
print(task.result().measurement_counts)

Bell Result Types (examples/bell_result_types.py)

#
# Licensed under the Apache License, Version 2.0 (the "License"). You
# may not use this file except in compliance with the License. A copy of
# the License is located at
#
#     http://aws.amazon.com/apache2.0/
#
# or in the "license" file accompanying this file. This file 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.
from braket.circuits import Circuit, observables
from braket.devices import LocalSimulator
device = LocalSimulator()
print("Example for shots=0")
# Result types can be requested in the circuit
# Example of result types for shots=0
bell = (
    Circuit()
    .h(0)
    .cnot(0, 1)
    .probability(target=[0])
    .expectation(observable=observables.Z(1))
    .amplitude(state=["00"])
    .state_vector()
)
# State vector and amplitude can only be requested when shots=0 for a simulator
# When shots=0 for a simulator, probability, expectation, variance are the exact values,
# not calculated from measurements
# Users cannot request Sample as a result when shots=0
result = device.run(bell).result()
print("Marginal probability for target 0 in computational basis:", result.values[0])
print("Expectation of target 1 in the computational basis:", result.values[1])
print("Amplitude of state 00:", result.values[2])
print("State vector:", result.values[3])
print("\nExample for shots>0")
# Example of result types for shots > 0
bell = (
    Circuit()
    .h(0)

Plays well with

amazon-braket-sdk-python

License

Apache-2.0

SPDX identifier detected from the repository metadata or license files.

Repository README

Preview from the project README.

Rendered as Markdown inside a scrollable preview. Long READMEs stay contained; expand or open on GitHub for the full document.

~1,587 words · about 7 min readOpen on GitHub

Amazon Braket Python SDK

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.11 or greater

Download and install Python 3.11 or greater from Python.org.

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.

Boto3 and setting up AWS credentials

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 ~/.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.

Installing the Amazon Braket Python SDK

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/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:

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:

pip install amazon-braket-sdk --upgrade --upgrade-strategy eager

Usage

Running a circuit on an AWS simulator

import boto3
from braket.aws import AwsDevice
from braket.circuits import Circuit
from braket.devices import Devices

device = AwsDevice(Devices.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:

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

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.

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.

import boto3
from braket.aws import AwsDevice
from braket.circuits import Circuit
from braket.devices import Devices

device = AwsDevice(Devices.Rigetti.Cepheus1108Q)

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().

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.

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 in the "Devices" tab.

Sample Notebooks

Sample Jupyter notebooks can be found in the amazon-braket-examples repo.

Recent Publications

See PUBLICATIONS.md for a list of recent arXiv preprints that use Amazon Braket.

Braket Python SDK API Reference Documentation

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: ../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:

pip install -e "amazon-braket-sdk-python[test]"

Unit Tests

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:

tox

or if your machine can handle multithreaded workloads, run them in parallel with:

tox -p auto

Integration 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.

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

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

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. For other issues or general questions, please ask on the Quantum Computing Stack Exchange.

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 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

License

This project is licensed under the Apache-2.0 License.

Read on GitHub

Activity

Latest release

—

Watchers

Python support

>= 3.11

Key dependencies

amazon-braket-schemas, amazon-braket-default-simulator, oqpy, backoff, boltons, boto3, cloudpickle, nest-asyncio, networkx, numpy, openpulse, openqasm3

External links

How this relates to Qtangl

Qtangl's product value is not tied to any single provider, but Braket matters because it shows how hybrid experiments and backend access can be operationalized behind a stable developer surface. That is useful context whenever Qtangl evaluates where provider-hosted quantum steps might fit into a future bounded research band.

Learn digest

Get monthly updates when library entries change.

Related resources

Keep exploring nearby tools.

quantumlib

Cirq

Python framework for creating, editing, and running Noisy Intermediate-Scale Quantum (NISQ) circuits.

PythonApache-2.0Flagship

4,971 stars · Updated 3mo ago

XanaduAI

pennylane

PennyLane is an open-source quantum software platform for quantum computing, quantum machine learning, and quantum chemistry.

PythonApache-2.0FlagshipQtangl relevant

3,229 stars · Updated 3mo ago

qBraid

A platform-agnostic quantum runtime framework

PythonApache-2.0

109 stars · Updated 3mo ago

QISKit

qiskit

Qiskit is an open-source SDK for working with quantum computers at the level of extended quantum circuits, operators, and primitives.

PythonApache-2.0FlagshipQtangl relevant

7,412 stars · Updated 3mo ago

Microsoft

QuantumKatas

Tutorials and programming exercises for learning Q# and quantum computing

Jupyter NotebookMITFlagshipArchive

4,862 stars · Updated 2y ago

ORNL-QCI

xacc

XACC - eXtreme-scale Accelerator programming framework

C++BSD-3-Clause

3 stars · Updated 1y ago