Run Quantum Circuit on Hardware Using AWS

Note

Installation Required: This functionality requires MATLAB Support Package for Quantum Computing.

This topic describes how to connect directly from MATLAB^® to Amazon^® Web Services (AWS^®) to enable running gate-based quantum circuits on remote quantum devices and simulators. Quantum hardware has limited availability as well as associated costs for each task that is run. A best practice is to finalize your circuit design as much as possible by simulating the circuit locally on your computer before running the circuit on a quantum device. See Local Quantum State Simulation for instructions on how to inspect simulated circuit results on your local computer.

Requirements

To run quantum circuits on an AWS device from within MATLAB, you need:

The MATLAB Support Package for Quantum Computing
An AWS account with access to Amazon Braket
An AWS Access Key and AWS Secret Access Key
An Amazon S3™ bucket to store results

Costs for the use of Amazon Braket devices are charged to your AWS account. See Amazon Braket Pricing for details.

Set Up Access to AWS

Follow these steps to enable communication between MATLAB and AWS.

Set up AWS account and retrieve credentials. Go to Setting up your local development environment in Amazon Braket and complete steps 1–3. If you have an existing account, then you can skip the first step and check your account settings in steps 2 and 3.
The account credentials (AWS Access Key and AWS Secret Access Key) are only available to download just after they are created. If your AWS account is managed through your organization, then you might need to contact your administrator for the recommended way to retrieve credentials.
At the end of this step, you should have:
- Configured or checked permissions for your AWS account
- Received account credentials (AWS Access Key and AWS Secret Access Key)
- Enabled Amazon Braket service for your account
Set environment variables. Specify these environment variables using your AWS Access Key and AWS Secret Access Key.
First, create a file named awsConfig.env that contains all necessary environment variables. At a minimum, you must specify values for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
```
AWS_ACCESS_KEY_ID=YOUR_AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY
```
Next, use the loadenv function with no output argument. This command loads each line as an environment variable in MATLAB.
```
loadenv('awsConfig.env')
```
Optional: Two optional environment variables that you can also specify in the configuration file are:
- AWS_SESSION_TOKEN: A token for one AWS session that expires after a given time period.
- AWS_DEFAULT_REGION: Restricts the region in which the server storing results must reside. When AWS_DEFAULT_REGION is set, you can still use QPUs that are located in any region.
Create Amazon S3 bucket to store results. See Create your first S3 bucket for more information about creating a bucket.
- The bucket you create must have a unique name. A suggested prefix for the name is amazon-braket-mathworks-.
- If you specified AWS_DEFAULT_REGION in the previous step, then the bucket must reside in the same region.

Device Availability

To see a list of available quantum devices:

Go to https://aws.amazon.com/.
Log in to your AWS account.
Navigate to Amazon Braket using the Services menu or the search bar.
Select Devices from the navigation menu.

The device list contains information on device providers, names, availability, and descriptions. Each device has different associated costs, and you can click on a device to see more details. If a device is offline, it does not accept tasks and creating a quantum.backend.QuantumDeviceAWS object for the device returns an error. However, devices that are not currently available might still accept tasks into their queue to be run later. Check the device details to determine the current status before submitting tasks.

The MATLAB Support Package for Quantum Computing works with gate-model QPU devices as well as simulators:

QPU Devices: These devices are quantum computers used to perform probabilistic measurements of circuits. Not all QPU devices are supported. To find out if a device is supported, try connecting to the device using quantum.backend.QuantumDeviceAWS. Availability and number of qubits supported can also vary, so check the device details before sending circuits for measurement.
Simulator Devices: Because memory usage scales exponentially with the number of qubits, larger circuits with many qubits might stretch the limits of memory available on your local computer. To address that issue, AWS also provides cloud-scale simulators. The functionality is similar to using randsample on your local system, but the simulators can support up to 34 qubits with cloud-scale performance.

Connect to Quantum Device

Connect to a quantum device using quantum.backend.QuantumDeviceAWS. Specify the name of the device as well as its region and the path of the Amazon S3 bucket to store results. The SV1 device is a state vector simulator that is preferred for prototyping circuits.

reg = "us-west-1";
bucketPath = "s3://amazon-braket-mathworks/doc-example";
device = quantum.backend.QuantumDeviceAWS("SV1",Region=reg,S3Path=bucketPath)

device = 

  QuantumDeviceAWS with properties:

         Name: "SV1"
    DeviceARN: "arn:aws:braket:::device/quantum-simulator/amazon/sv1"
       Region: "us-west-1"
       S3Path: "s3://amazon-braket-mathworks/doc-example"

Note

If you receive an error or warning while connecting to a device in this step, then your connection to AWS might not be set up properly. See Set Up Access to AWS for more information.

Use fetchDetails to get additional information about the device.

fetchDetails(device)

ans = 

  struct with fields:

             deviceArn: "arn:aws:braket:::device/quantum-simulator/amazon/sv1"
    deviceCapabilities: "{"service": {"braketSchemaHeader": {"name": "braket.device_schema.device_service_properties",..."
            deviceName: "SV1"
          deviceStatus: "ONLINE"
            deviceType: "SIMULATOR"
          providerName: "Amazon Braket"

Create Task to Run Circuit

Create a quantum circuit with three qubits and three gates, and then plot the circuit.

gates = [hGate(1);
         cxGate(1,2);
         cxGate(2,3)];
C = quantumCircuit(gates);
plot(C)

Quantum circuit diagram with three qubits and three gates

When a circuit is measured on quantum hardware, the superposition of states for the qubits collapses into a single state, and that result is probabilistic. That is, the result of a measurement can change between runs, but the probability of each result follows the state probabilities produced by the gates in the circuit. So, it is common to run several shots, or trials, of a circuit to reveal the underlying probability distribution of results. By default, the run method uses 100 shots.

Create a task to run the circuit on the device.

task = run(C,device)

task = 

  QuantumTaskAWS with properties:

    TaskARN: "arn:aws:braket:us-west-1:123456789012:quantum-task/1234abcd-ef56-7890-abc2-34de56f678ab"
     Status: "queued"

Quantum devices have limited availability, so tasks are often queued for execution. Once a task is finished, the Status property of the task object has a value of "finished". Check the status of a task by querying the Status property periodically, or use the wait method to internally check the status until the task is finished.

wait(task)

You can use cancel to cancel the task when needed. Canceling has no effect unless the status of the task is "queued" or "running".

Fetch Measurement Output

Once the task is finished, retrieve the result of running the circuit by using fetchOutput.

R = fetchOutput(task)

R = 

  QuantumMeasurement with properties:

    MeasuredStates: [2×1 string]
            Counts: [2×1 double]
     Probabilities: [2×1 double]
         NumQubits: 3

Examine the counts and probabilities of the measured states in a table. The counts can change slightly from run to run, but will tend to be evenly divided between the two possible states.

T = table(R.Counts,R.Probabilities,R.MeasuredStates, ...
    VariableNames=["Counts","Probabilities","States"])

T =

  2×3 table

    Counts    Probabilities    States
    ______    _____________    ______

      55          0.55         "000" 
      45          0.45         "111"