amazon-braket-examples: notebooks for learning quantum computing on AWS

The structure follows a curriculum, not a feature list

This repository is the primary one for Amazon Braket examples and tutorials, and it teaches how to build, test and run quantum circuits and programs using Braket with simulators and quantum hardware. Introductory examples on a variety of topics are included, as well as more canonical quantum algorithms, and there is also information on using particular devices or using Braket with other supported tools.

The readme organises the notebooks under headings that read like a course. Build covers the getting started examples, using Braket features, advanced circuits and algorithms, and building hybrid quantum algorithms. Test covers simulators, modelling noise and using hybrid jobs. Run covers quantum devices, controlling pulse sequences, Analog Hamiltonian Simulation, and accessing experimental capabilities. Then there are providers, IonQ, IQM, QuEra and Rigetti, and a supported tools section for CUDA-Q, PennyLane and Qiskit.

That structure is the point of the repository. A notebook collection can be an unordered dumping ground, and this one is ordered by what you should learn and when, which is what makes it usable by someone who does not already know the field.

The getting started sequence shows the intent. The first is a hello-world tutorial that builds a simple circuit and runs it on a local simulator. The second runs quantum circuits on simulators and prepares a paradigmatic example for a multi-qubit entangled state, the so-called GHZ state, named after the three physicists Greenberger, Horne and Zeilinger. The readme explains why that example is worth running, because the GHZ state is extremely non-classical and therefore very sensitive to decoherence, which is why it is often used as a performance benchmark for today's hardware and is used as a resource for quantum error correction, quantum communication and quantum metrology.

The third notebook runs circuits on QPU devices, preparing a maximally entangled Bell state between two qubits for both classical simulators and real hardware.

The same circuit on different hardware, and what QPUs add

The QPU notebook is the one that shows what changes when you leave the simulator, and it is worth reading the way it is written rather than just running it.

The circuit is a Bell state, and it is run three ways. On classical devices, the circuit runs on a local simulator or a cloud-based on-demand simulator. On the quantum devices, it runs on the superconducting machine from Rigetti and on the ion-trap machine provided by IonQ.

The demonstration is that you can swap between devices without any modification to the circuit definition, by redefining the device object. That is the practical argument for a managed service: the hardware abstraction is the same whether you are running a superconducting chip or an ion trap, and the difference is one object.

The notebook also shows how to recover results using the unique Amazon resource identifier associated with every quantum task, and it says why that matters in practice, because you may have to deal with potential delays if your quantum task sits in the queue awaiting execution. That is the honest bit about QPUs that most marketing leaves out. A quantum task is a job submitted to a queue, it has an ARN, and you can come back later for the result or cancel it.

The other getting started notebook is superdense coding, which transmits two classical bits by sending only one qubit. Starting from a pair of entangled qubits, the sender, Alice, applies a quantum gate to their qubit and sends the result to the receiver, Bob, who decodes the full two-bit message.

The deep dive into the anatomy of quantum circuits covers the SDK mechanics in detail. You learn to build parameterized circuits and display them graphically, and to append circuits to each other, and the readme discusses the associated circuit depth and circuit size, which matters because depth is what determines whether a circuit fits on a real device within its coherence time. It then covers executing the circuit by defining a quantum task, and how to track, log, recover or cancel one efficiently.

Noisy simulators, hybrid jobs and the rest of the test section

The test section of the readme is where the interesting engineering sits, because it covers the parts of quantum computing that are not just circuits.

Modelling noise is one of them, with a dedicated page on modeling noise on Braket. This matters more than it sounds. A simulator without noise returns exact amplitudes, and a real QPU returns something much less useful, so a circuit that works perfectly in simulation may fail on hardware for reasons that have nothing to do with the algorithm. A section on noise modelling is how a notebook collection teaches you that difference rather than hiding it.

Hybrid jobs covers running a quantum task as part of a longer classical workflow, which is what most practical quantum algorithms actually are. A variational algorithm, for instance, is a loop where a classical optimiser proposes circuit parameters, the circuit is run on hardware, and the measurement results feed the next iteration. The quantum part is a subroutine called thousands of times, and the latency and queueing of a real device make the job model the point.

In the Braket features section there are notebooks on OpenQASM support, on getting notifications when a quantum task completes, on the Adjoint Gradient result type, and on verbatim compilation.

The EventBridge notebook is a good example of the platform integration angle. It shows how Braket integrates with Amazon EventBridge for event-based processing, how to configure both to receive a text notification about quantum task completions on your phone, and notes that EventBridge also allows building full event-driven applications from the events Braket emits. That is the bridge between a quantum task and the rest of a cloud application, and it is the piece that makes an asynchronous queue usable in a real system rather than a script you run and wait for.

The Adjoint Gradient result type covers what a gradient is and how to compute one on a quantum circuit, and shows an example of gradients in action on a hybrid quantum algorithm.

Providers, pulse control and the wider tooling

The run section covers what you can do with hardware specifically.

Controlling pulse sequences is the most hardware-specific part of the whole repository, and the most different from anything else in quantum computing. Instead of abstract gates, you are working with the physical signals that drive the device, which is the level where a gate library like Rigetti's is not enough.

Analog Hamiltonian Simulation is the other major one, and it is a different computational model rather than a different device. Rather than gate sequences, you describe a Hamiltonian and let the device simulate its dynamics, which is a fundamentally different way of asking a quantum computer to solve a problem.

Accessing experimental capabilities is the section for the frontier, and the examples directory shows it as a distinct area, alongside directories for advanced circuits and algorithms, error mitigation, and hybrid quantum algorithms. Error mitigation being its own directory tells you how central it has become, because a usable algorithm on today's hardware usually needs it.

The provider list in the readme is IonQ, IQM, QuEra and Rigetti, and the examples directory names a provider set that is broader still, with a qiskit directory and a nvidia_cuda_q directory, plus pennylane. The provider pages are per-vendor, and the notable ones are the ion trap from IonQ, the superconducting machine from Rigetti, QuEra which is the neutral atom company, and IQM.

The supported tools section covers CUDA-Q from NVIDIA, PennyLane and Qiskit, and these are the interoperability notebooks. The point of including them is that Braket is not asking you to use only its SDK. The qiskit-braket-provider in the requirements is the bridge that lets a Qiskit program target a Braket device, and the PennyLane plugin does the same for a PennyLane circuit. The requirements also carry amazon-braket-pennylane-plugin and the CUDA-Q packages, cuda-quantum-cu12 and cudaq-qec-cu12, both of which are restricted to Linux by their environment markers, because the CUDA-Q stack needs a GPU.

Running the notebooks yourself, and the managed option

There is a choice to make before you write any code, and the readme puts it plainly. Amazon Braket provides managed Jupyter notebook instances which can be run and maintained remotely. To run the examples locally, the dependencies can be installed following the instructions in the repository.

The managed path is the one to try first if you are evaluating the platform rather than the notebooks, because it removes the local setup entirely and gives you a preconfigured environment with the Braket SDK already installed and credentials wired to your account. The cost is that the instance is a hosted environment rather than your own machine, so a notebook that works there may not run identically elsewhere.

The local path means installing from requirements.txt, and that file is where the constraints live, as the pins in the next section show. The Braket SDK is the only piece you strictly need for the getting started notebooks, and the rest of the stack is there for the PennyLane, Qiskit and CUDA-Q sections. Installing everything is the simplest way to be sure the notebooks run, but it is a large install with a GPU-only subset.

The documentation also points beyond the notebooks at two other resources. For anyone just getting started with Braket, there is a Getting Started section and an Amazon Skill Builder learning plan with a digital badge, which is a structured path with a credential at the end. And the Amazon Braket Algorithm Library is a separate repository containing detailed examples and preimplemented algorithms, which is where you would go for a working implementation of a specific algorithm rather than for the theory.

The support section of the readme covers local installations, feature requests and more, and the repository also carries a TESTING.md and a CONTRIBUTING.md for anyone adding a notebook.

A notebook collection with real dependency pinning

The repository is a package on PyPI as well as a notebook collection, and the packaging tells you how it is meant to be used and tested.

The build backend is hatchling with a hatch-requirements-txt plugin, and the dependencies are dynamic, pulled from the requirements.txt file by that plugin. The project requires Python 3.11 or newer, is licensed apache-2.0, and is classified as Development Status 5, Production/Stable with an intended audience of developers, education and science or research.

The wheel target only includes the examples directory, so the package is essentially a distribution of the notebooks rather than an importable library. The version is 0.0.1.

The test setup is where the repository earns its Production/Stable label, because running quantum notebooks is not a thing you can do casually. The default hatch environment pulls in jupyter, nbconvert, pytest, pytest-rerunfailures, pytest-xdist with psutil, and testbook, and the test script installs a conda_braket ipykernel, runs the repository tests, and then runs the integration tests with pytest distributed across workers using the worksteal distribution. The integration tests are the ones that actually execute the notebooks, and the parallel distribution exists because each one submits work to a real backend or spins a simulator, which is slow.

The requirements file is where the pinning discipline shows, and the comments in it are the interesting part. jax is pinned to 0.6.2 with a note that JAX above 0.6.2 is not compatible with PennyLane, and pandas is pinned to 2.3.3 with a note that pandas 3.0.0 and above is not compatible with JAX 0.6.2. In other words, the versions of two major libraries are constrained by a third one, and the pins are there to keep the PennyLane notebooks runnable.

The rest of the file is a full quantum stack: the Braket SDK at 1.127.3, the default simulator at 1.40.2, the algorithm library at 1.7.10, PennyLane at 0.45.1 with its lightning plugin, Qiskit at 2.5.2 with aer, algorithms, optimization and the Braket provider, OpenFermion with its PySCF interface, CVXPY, SciPy, JAX and JAXlib, optax, boto3 and botocore, and the AWS CLI.

The repository top level also holds a TESTING.md, a CODEOWNERS, a NOTICE file, an environment.yml, a docs directory and an nbi directory, plus a test directory with the repository and integration test suites.

Editorial conclusion

Adopt the Braket examples as a learning path if you are new to quantum computing and want to work in notebooks rather than read papers, since the sequence from a local simulator to a real device is already laid out. Do not adopt it as a library, because it is a notebook collection rather than a package with an API, and note that the dependency set is large and pinned with known incompatibilities between JAX, PennyLane and pandas. Before you start, decide between the managed Jupyter notebook instances Braket provides and a local install, and read the requirements file, because the pins there are load-bearing and the comments explain why.

Frequently asked questions

Official sources

1. amazon-braket/amazon-braket-examples on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README