Run a job with Amazon Braket Hybrid Jobs - Amazon Braket

Run a job with Amazon Braket Hybrid Jobs

To run a job with Amazon Braket Hybrid Jobs, you first need to define your algorithm. You can define it by writing the algorithm script and, optionally, other dependency files using the Amazon Braket Python SDK or PennyLane. If you want to use other (open source or proprietary) libraries, you can define your own custom container image using Docker, which includes these libraries. For more information, see Bring your own container (BYOC).

In either case, next you create a job using the Amazon Braket API, where you provide your algorithm script or container, select the target quantum device the job is to use, and then choose from a variety of optional settings. The default values provided for these optional settings work for the majority of use cases. For the target device to run your Hybrid Job, you have a choice between a QPU, an on-demand simulator (such as SV1, DM1 or TN1), or the classical job instance itself. With an on-demand simulator or QPU, your hybrid jobs container makes API calls to a remote device. With the embedded simulators, the simulator is embedded in the same container as your algorithm script. The lightning simulators from PennyLane are embedded with the default pre-built jobs container for you to use. If you run your code using an embedded PennyLane simulator or a custom simulator, you can specify an instance type as well as how many instances you wish to use. Refer to the Amazon Braket Pricing page for the costs associated with each choice.

            braket hybrid job run

If your target device is a managed or embedded simulator, Amazon Braket starts running the job right away. It spins up the job instance (you can customize the instance type in the API call), runs your algorithm, writes the results to Amazon S3, and releases your resources. This release of resources ensures that you only pay for what you use.

The total number of concurrent jobs per quantum processing unit (QPU) is restricted. Queues are used to control the number of jobs allowed to run so as not to exceed the limit allowed. If your target device is a QPU, your job first enters the job queue of the selected QPU. Once your job has moved up to first position and the device is ready to start a new job, Amazon Braket spins up the job instance needed and runs your job on the device. For the duration of your algorithm, your job has priority access, meaning that tasks from your job run ahead of other tasks queued up on the device. You are only billed when your job starts, which means you’re not billed for any wait time in the job queue.


Devices are regional and your job runs in the same AWS Region as your primary device.

In both the simulator and QPU target scenarios, you have the option to define custom algorithm metrics, such as the energy of your Hamiltonian, as part of your algorithm. These metrics are automatically reported to Amazon CloudWatch and from there, they display in near real-time in the Amazon Braket console.


If you wish to use a GPU based instance, be sure to use one of the GPU-based simulators available with the embedded simulators on Braket (for example, lightning.gpu). If you choose one of the CPU-based embedded simulators (for example, lightning.qubit, or braket:default-simulator), the GPU will not be used and you may incur unnecessary costs.