run

Run circuit on quantum device

Since R2023a

collapse all in page

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

Syntax

task = run(c,dev)
task = run(c,dev,Name=Value)

Description

task = run(c,dev) runs the quantum circuit c remotely on a quantum device dev.

The input dev must be a QuantumDeviceAWS or QuantumDeviceIBM object that connects to a quantum device available through AWS® or IBM®, respectively. The output task is a QuantumTaskAWS or QuantumTaskIBM object, which can be used to monitor the task and retrieve its result. By default, the run function runs the circuit with 100 shots.

example

task = run(c,dev,Name=Value) specifies options using one or more name-value arguments. For example, you can specify NumShots=n to run the circuit with n shots remotely on the quantum device.

Note

Running a circuit on a remote quantum device results in charges to your account with the remote service.

example

Examples

collapse all

Create a quantum circuit that consists of a Hadamard gate and a controlled X gate to entangle two qubits.

gates = [hGate(1); cxGate(1,2)];
c = quantumCircuit(gates);

Connect to a remote quantum device through AWS. Create a task that runs the circuit on the device with 100 shots.

dev = quantum.backend.QuantumDeviceAWS("Lucy");
task = run(c,dev)
task = 

  QuantumTaskAWS with properties:

     Status: "queued"
    TaskARN: "arn:aws:braket:eu-west-2:123456789012:quantum-task/abcd1234-4567-8901-ef12-abcd0987efab6543"

Wait for the task to finish. Retrieve the result of running the circuit on the device.

wait(task)
m = fetchOutput(task)
m = 

  QuantumMeasurement with properties:

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

Show the measurement result of running the circuit. Due to the noise in the physical quantum device, the |01〉 and |10〉 states can appear as measurements.

table(m.Counts,m.Probabilities,m.MeasuredStates, ...
    VariableNames=["Counts","Probabilities","States"])
ans =

  4×3 table

    Counts    Probabilities    States
    ______    _____________    ______

      46          0.46          "00" 
       9          0.09          "10" 
       3          0.03          "01" 
      42          0.42          "11"

Create a quantum circuit that applies the quantum Fourier transform to five qubits.

gates = qftGate(1:5);
c = quantumCircuit(gates);

Connect to a remote quantum device through AWS. Create a task that runs the circuit on the device with 2000 shots.

dev = quantum.backend.QuantumDeviceAWS("Aspen-M-3");
task = run(c,dev,NumShots=2000)
task = 

  QuantumTaskAWS with properties:

     Status: "queued"
    TaskARN: "arn:aws:braket:us-west-1:123456789012:quantum-task/12a34b5c-6a78-9a01-2ab3-4c56def7g890"

Save the ARN string value in the task.TaskARN property.

ARNstr = task.TaskARN;
save ARNstr.mat ARNstr

You can close the current MATLAB® session. To retrieve the previously queued task in a new MATLAB session, you can use the ARN of that task to create the QuantumTaskAWS object again.

load ARNstr.mat
task = quantum.backend.QuantumTaskAWS(ARNstr)
task = 

  QuantumTaskAWS with properties:

     Status: "running"
    TaskARN: "arn:aws:braket:us-west-1:123456789012:quantum-task/12a34b5c-6a78-9a01-2ab3-4c56def7g890"

Wait for the task to finish and retrieve the result.

wait(task)
m = fetchOutput(task)
m = 

  QuantumMeasurement with properties:

    MeasuredStates: [32×1 string]
            Counts: [32×1 double]
     Probabilities: [32×1 double]
         NumQubits: 5

Create a quantum circuit that consists of a Hadamard gate and a controlled X gate to entangle two qubits.

gates = [hGate(1); cxGate(1,2)];
c = quantumCircuit(gates);

Connect to a remote quantum device through IBM. Create a task that runs the circuit 500 times on the device without error mitigation.

dev = quantum.backend.QuantumDeviceIBM("ibm_fez");
task = run(c,dev,NumShots=500,UseErrorMitigation=false);
task = 

  QuantumTaskIBM with properties:

         TaskID: "123abcd4efa5bcdef678"
      SessionID: <missing>
    AccountName: "<my account name>"
         Status: "queued"

Wait for the task to finish. Retrieve the result of running the circuit on the device.

wait(task)
m = fetchOutput(task)
m = 

  QuantumMeasurement with properties:

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

Show the measurement result of running the circuit. Due to the noise in the physical quantum device, the |01〉 and |10〉 states can appear as measurements.

table(m.Probabilities,m.MeasuredStates, ...
    VariableNames=["Probabilities","States"])
ans =

  4×2 table

    Probabilities    States
    _____________    ______
        0.536         "00" 
        0.018         "10" 
        0.024         "01" 
        0.422         "11"

Next, create a task that runs the circuit on the same device, but with quantum error mitigation. The error mitigation applies a collection of tools and methods to the measurement results that attempts to reduce the effects of measurement errors.

task = run(c,dev,NumShots=500,UseErrorMitigation=true);

Wait for the task to finish. Retrieve the result of running the circuit on the device.

wait(task)
m = fetchOutput(task)
m = 

  QuantumMeasurement with properties:

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

Show the measurement result of running the circuit with error mitigation. Here, the estimated probabilities of the |01〉 and |10〉 states are closer to 0.

table(m.Probabilities,m.MeasuredStates, ...
    VariableNames=["Probabilities","States"])
ans =

  4×2 table

    Probabilities    States
    _____________    ______
        0.59254       "00" 
       0.001586       "10" 
     -0.0094173       "01" 
         0.4153       "11"

Create a quantum circuit that applies the quantum Fourier transform to five qubits.

gates = qftGate(1:5);
c = quantumCircuit(gates);

Connect to a remote quantum device through IBM. Create a task that runs the circuit on the device with 500 shots.

dev = quantum.backend.QuantumDeviceIBM("ibm_fez");
task = run(c,dev,NumShots=500);
task = 

  QuantumTaskIBM with properties:

         TaskID: "123abcd4efa5bcdef678"
      SessionID: <missing>
    AccountName: "<my account name>"
         Status: "queued"

Save the task identifier string value in the task.TaskID property.

taskIDstr = task.TaskID;
save taskIDstr.mat taskIDstr

You can close the current MATLAB session. To retrieve the previously queued task in a new MATLAB session, you can use the identifier of that task to create the QuantumTaskIBM object again.

load taskIDstr.mat
task = quantum.backend.QuantumTaskIBM(taskIDstr)
task = 

  QuantumTaskIBM with properties:

         TaskID: "123abcd4efa5bcdef678"
      SessionID: <missing>
    AccountName: "<my account name>"
         Status: "running"

Wait for the task to finish and retrieve the result.

wait(task)
m = fetchOutput(task)
m = 

  QuantumMeasurement with properties:

    MeasuredStates: [32×1 string]
            Counts: [32×1 double]
     Probabilities: [32×1 double]
         NumQubits: 5

Input Arguments

collapse all

Quantum circuit, specified as a quantumCircuit object or, if dev is a QuantumDeviceIBM object, a vector of quantumCircuit objects.

Quantum device, specified as a QuantumDeviceAWS or QuantumDeviceIBM object. Use the quantum.backend.QuantumDeviceAWS or quantum.backend.QuantumDeviceIBM constructor to create this object, which connects to a remote quantum device through AWS or IBM, respectively.

Name-Value Arguments

expand all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: task = run(c,dev,NumShots=500) runs the quantum circuit c with 500 shots remotely on the quantum device dev.

All Devices

expand all

Observable, specified as an observable object or, if dev is a QuantumDeviceIBM object, a vector of observable objects. Use this name-value argument to specify the possible Pauli basis measurement results of running the input quantum circuit. If you specify the Observable name-value argument, the function returns a QuantumTaskAWS or QuantumTaskIBM object whose result is the expectation value of measuring the quantum circuit c in the basis specified by the observable.

AWS Devices

expand all

Number of times to run the circuit, specified as a positive integer scalar. By default, NumShots is 100.

IBM Devices

expand all

Number of times to run the circuit, specified as a positive integer scalar. By default, NumShots is 100.

Option to apply error mitigation, specified as a numeric or logical 1 (true) or 0 (false). The error mitigation applies a collection of tools and methods to the measurement results that attempts to reduce the effects of measurement errors.

Output Arguments

collapse all

Task that runs the circuit on a quantum device, returned as a QuantumTaskAWS object, QuantumTaskIBM object, or vector of QuantumTaskIBM objects. You can check the status of the task by querying the Status property of this object, where the status can be "queued", "running", "finished", or "failed". Once the task is finished, you can retrieve the measurement result from this object by using the fetchOutput function.

Version History

Introduced in R2023a

expand all

See Also

Classes

Functions

Topics