# Working with reservations
(Advanced) Working with reservations

Reservations give you exclusive access to the quantum device of your choice. You can schedule a reservation at your convenience, so you know exactly when your workload starts and ends execution. Reservations are available in 1-hour increments for all Braket devices and can be cancelled up to 48 hours in advance, at no additional charge. We recommend queuing quantum tasks and hybrid jobs for an upcoming reservation in advance, using your Braket Direct Reservation ARN, or submitting workloads during your reservation.

The cost of dedicated device access is based on the duration of your reservation, regardless of how many quantum tasks and hybrid jobs you run on the quantum processing unit (QPU). An updated list of quantum computers available for reservations can be found on our [pricing page](https://aws.amazon.com/braket/pricing/) or via the [Amazon Braket management console](https://us-east-1.console.aws.amazon.com/braket/home?region=us-east-1#/devices). 

**Note**  
In a reservation, there are no [gateshot](braket-terms.md#gateshot-limit-term) limits. Additionally, for IonQ devices, the minimum shot count for [Error mitigation](https://docs.aws.amazon.com/braket/latest/developerguide/braket-error-mitigation.html) tasks is reduced to 500 (vs. 2500 for on-demand).

 **When to use a reservation** 

Leveraging reservation access provides you the convenience and predictability of knowing exactly when your quantum workload starts and ends execution. Compared to submitting tasks and hybrid jobs on-demand, you do not have wait in a queue with other customer tasks. Because you have exclusive access to the device during your reservation, only your workloads run on the device for the entirety of the reservation.

We recommend using on-demand access for the design and prototyping phase of your research, enabling quick and cost-efficient iteration of your algorithms. Once you are ready to produce final experiment results, consider scheduling a device reservation at your convenience to ensure that you can meet project or publication deadlines. We also recommend using reservations when you desire task execution during specific times, such as when you're running a live demo or workshop on a quantum computer.

**Topics**
+ [

# How to create a reservation
](braket-create-a-reservation.md)
+ [

# Running quantum tasks during a reservation
](braket-run-quantum-task-with-reservation.md)
+ [

# Running hybrid jobs during a reservation
](braket-run-hybrid-jobs-with-reservation.md)
+ [

# What happens at the end of your reservation
](braket-end-of-reservation.md)
+ [

# Cancel or reschedule an existing reservation
](braket-cancel-reservation.md)

# How to create a reservation


To create a reservation, contact the Braket team by following these steps:

1. Open the Amazon Braket console.

1. Choose **Braket Direct** in the left pane, and then in the **Reservations** section, choose **Reserve device **.

1. Select the **Device** that you would like to reserve.

1. Provide your contact information including **Name** and **Email**. Be sure to provide a valid email address that you regularly check.

1. Under **Tell us about your workload**, provide any details about the workload to run using your reservation. For example, desired reservation length, relevant constraints, or desired schedule.

After you submit the form, you receive an email from the Braket team with the next steps. Once your reservation is confirmed, you will receive the reservation ARN through your email. You will need the to use the reservation ARN to create reservation tasks. Tasks created without the reservation ARN will be submitted to the regular on-demand queue and will NOT run during your reservation.

**Note**  
Your reservation is only confirmed once you receive the reservation ARN.

Reservations are available in minimum 1-hour increments and certain devices might have additional reservation length constraints (including minimum and maximum reservation durations). The Braket team shares any relevant information with you prior to confirming the reservation.

The Braket team will contact you through your email to arrange a 30-minute session with a Braket expert.

# Running quantum tasks during a reservation


After obtaining a valid reservation ARN from [Create a reservation](https://docs.aws.amazon.com/braket/latest/developerguide/braket-reservations.html#braket-create-a-reservation), you can create quantum tasks to run during the reservation. Quantum tasks and hybrid jobs submitted with a reservation ARN will not show up in a device queue. Tasks submitted before reservation start time will remain in the `QUEUED` state until your reservation begins. 

**Note**  
Reservations are AWS account and device-specific. Only the AWS account that created the reservation can use your reservation ARN.   
During a reservation, both reservation and regular tasks can be created. To verify that a created Braket quantum task is associated with a reservation, check the “Reservation ARN” field on the page of the quantum task in the Braket console, or query the same field in the task metadata using the SDK. The rest of this page describes how to specify which tasks are associated to the reseravation. 

You can create quantum tasks using Python SDKs such as [Braket](https://docs.aws.amazon.com/braket/latest/developerguide/braket-references.html), [https://github.com/NVIDIA/cuda-quantum](https://github.com/NVIDIA/cuda-quantum), [https://github.com/amazon-braket/amazon-braket-pennylane-plugin-python](https://github.com/amazon-braket/amazon-braket-pennylane-plugin-python), [https://github.com/qiskit-community/qiskit-braket-provider](https://github.com/qiskit-community/qiskit-braket-provider), or directly with boto3 ([Working with Boto3](https://docs.aws.amazon.com/braket/latest/developerguide/braket-using-boto3.html)). To use reservations, you must have version [v1.79.0](https://github.com/amazon-braket/amazon-braket-sdk-python/releases/tag/v1.79.0) or higher of the [Amazon Braket Python SDK](https://github.com/amazon-braket/amazon-braket-sdk-python). You can update to the latest Braket SDK, Qiskit provider and PennyLane plugin with the following code. 

```
pip install --upgrade amazon-braket-sdk amazon-braket-pennylane-plugin qiskit-braket-provider
```

**Run tasks with the `DirectReservation` context manager**

The recommended way to run a task within your scheduled reservation is to use the `DirectReservation` context manager. By specifying your target device and reservation ARN, the context manager ensures that all tasks created within the Python `with` statement are run with exclusive access to the device. 

First, define a quantum circuit and the device. Then use the reservation context and run the task. **Ensure that your entire workload is run inside the `with` block; anything run outside the scope of the `with` block will not be associated with your reservation\$1**

```
from braket.aws import AwsDevice, DirectReservation
from braket.circuits import Circuit
from braket.devices import Devices

bell = Circuit().h(0).cnot(0, 1)
device = AwsDevice(Devices.IonQ.ForteEnterprise1)

# run the circuit in a reservation
with DirectReservation(device, reservation_arn="<my_reservation_arn>"):
    task = device.run(bell, shots=100)
```

You can create quantum tasks in a reservation using CUDA-Q, PennyLane, and Qiskit plugins, as long as the `DirectReservation` context is active while creating quantum tasks. For example, with the Qiskit-Braket provider, you can run tasks as follows.

```
from braket.devices import Devices
from braket.aws import DirectReservation
from qiskit import QuantumCircuit
from qiskit_braket_provider import BraketProvider


qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

qpu = BraketProvider().get_backend("Forte Enterprise 1")

# run the circuit in a reservation
with DirectReservation(Devices.IonQ.ForteEnterprise1, reservation_arn="<my_reservation_arn>"):
    qpu_task = qpu.run(qc, shots=10)
```

Similarly, the following code runs a circuit during a reservation using the Braket-PennyLane plugin.

```
from braket.devices import Devices
from braket.aws import DirectReservation
import pennylane as qml


dev = qml.device("braket.aws.qubit", device_arn=Devices.IonQ.ForteEnterprise1.value, wires=2, shots=10)

@qml.qnode(dev)
def bell_state():
    qml.Hadamard(wires=0)
    qml.CNOT(wires=[0, 1])
    return qml.probs(wires=[0, 1])

# run the circuit in a reservation
with DirectReservation(Devices.IonQ.ForteEnterprise1, reservation_arn="<my_reservation_arn>"):
    probs = bell_state()
```

**Manually setting the reservation context**

Alternatively, you can manually set the reservation context with the following code.

```
# set reservation context 
reservation_context = DirectReservation(device, reservation_arn="<my_reservation_arn>").start()

# run circuit during reservation
task = device.run(bell, shots=100)
```

This is ideal for Jupyter notebooks where the context can be run in the first cell and all subsequent tasks will run in the reservation.

**Note**  
The cell containing the `.start()` call should *only be run once*. 

To switch back to the on-demand mode: Restart the Jupyter notebook, or call the following to change the context back to on-demand mode.

```
reservation_context.stop()  # unset reservation context 
```

**Note**  
 Reservations have a pre-determined start and end time (see [Create a reservation](https://docs.aws.amazon.com/braket/latest/developerguide/braket-reservations.html#braket-create-a-reservation)). The `reservation_context.start()` and `reservation_context.stop()` methods **do not begin or terminate a reservation**. Instead, while the context is active, any quantum tasks that you create will be associated with your reservation, and will run only during your scheduled reservation. The reservation context has no effect on the scheduled reservation time. 

**Explicitly pass the reservation ARN when creating task**

Another way to create tasks during a reservation is to explicitly pass the reservation ARN when calling `device.run()`. 

```
task = device.run(bell, shots=100, reservation_arn="<my_reservation_arn>")
```

This method directly associates the quantum task with the reservation ARN, ensuring it runs during the reserved period. For this option, add the reservation ARN to each task you plan to run during a reservation. However, note that when using third-party libraries such as Qiskit or PennyLane, it may be difficult to ensure that submitted tasks are using the correct reservation ARN. For this reason, using the DirectReservation context manager is recommended. 

When directly using boto3, pass the reservation ARN as an association when creating a task.

```
import boto3

braket_client = boto3.client("braket")


kwargs["associations"] = [
    {
        "arn": "<my_reservation_arn>",
        "type": "RESERVATION_TIME_WINDOW_ARN",
    }
]

response = braket_client.create_quantum_task(**kwargs)
```

# Running hybrid jobs during a reservation


Once you have a Python function to run as a hybrid job, you can run the hybrid job in a reservation by passing the `reservation_arn` keyword argument. All the tasks within the hybrid job use the reservation ARN. Importantly, the hybrid job with `reservation_arn` *only spins up the classical compute once your reservation starts*. 

**Note**  
A hybrid job running during a reservation *only successfully runs* quantum tasks on the reserved device. Attempting to use a different on-demand Braket device will result in an error. If you need to run tasks on both an on-demand simulator and the reserved device within the same hybrid job, use `DirectReservation` instead.

The following code demonstrates how to run a hybrid job during a reservation.

```
from braket.aws import AwsDevice
from braket.devices import Devices
from braket.jobs import get_job_device_arn, hybrid_job

@hybrid_job(device=Devices.IonQ.ForteEnterprise1, reservation_arn="<my_reservation_arn>")
def example_hybrid_job():
    # declare AwsDevice within the hybrid job
    device = AwsDevice(get_job_device_arn())
    bell = Circuit().h(0).cnot(0, 1)
    
    task = device.run(bell, shots=10)
```

For hybrid jobs that use a Python script (see the section on [Creating your first Hybrid Job](https://docs.aws.amazon.com/braket/latest/developerguide/braket-jobs-first.html) in the developer guide), you can run them within the reservation by passing the `reservation_arn` keyword argument when creating the job.

```
from braket.aws import AwsQuantumJob 
from braket.devices import Devices

job = AwsQuantumJob.create( 
    Devices.IonQ.ForteEnterprise1,
    source_module="algorithm_script.py", 
    entry_point="algorithm_script:start_here",
    reservation_arn="<my_reservation_arn>"
)
```

# What happens at the end of your reservation


After your reservation ends, you no longer have dedicated access to the device. Any remaining workloads that are queued with this reservation are automatically canceled.

**Note**  
Any job that was in `RUNNING` status when the reservation ends is canceled. We recommend using [checkpoints to save and restart](https://docs.aws.amazon.com/braket/latest/developerguide/braket-jobs-checkpoints.html) jobs at your convenience.

An ongoing reservation, such as after reservation start and before reservation end, can't be extended because each reservation represents standalone dedicated device access. For example, two back-to-back reservations are considered separate and any pending tasks from the first reservation are automatically canceled. They do not resume in the second reservation.

**Note**  
Reservations represent dedicated device access for your AWS account. Even if the device remains idle, no other customers can use it. Therefore, you are charged for the length of the reserved time, regardless of the utilized time.

# Cancel or reschedule an existing reservation


You can cancel your reservation no less than 48 hours before the scheduled reservation start time. To cancel, respond to the reservation confirmation email you received with your cancellation request.

To reschedule, you have to cancel your existing reservation, and then create a new one.