run

Run circuit on quantum device

Since R2023a

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.

Input dev must be a QuantumDeviceAWS or a QuantumDeviceIBM object that connects to a quantum device available through AWS^® or IBM^®, respectively. The output task is a QuantumTaskAWS or a 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.

task = run(c,dev,Name=Value) specifies additional options by one or more name-value pair 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 will result in charges to your account with the remote service.

Examples

Run Circuit Remotely on AWS Quantum Device

Create a quantum circuit that consists of a Hadamard gate and a controlled X gate to entangle 2 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.

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" 

Retrieve Task on AWS from Previous Session

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 previously saved 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

Run Circuit Remotely on IBM Quantum Device With Error Mitigation

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 available through IBM. Create a task that runs the circuit 500 times on the device without error mitigation.

dev = quantum.backend.QuantumDeviceIBM("ibmq_qasm_simulator");
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\rangle$$ and $$|10\rangle$$ 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 by applying quantum error mitigation. The error mitigation is a collection of tools and methods to process measurement results that are aimed at reducing 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\rangle$$ and $$|10\rangle$$ 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" 

Retrieve Task on IBM from Previous Session

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("ibmq_qasm_simulator");
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 previously saved 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

c — Quantum circuit

quantumCircuit object

Quantum circuit, specified as a quantumCircuit object.

dev — Quantum device

QuantumDeviceAWS object | QuantumDeviceIBM object

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

Name-Value Arguments

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: NumShots=100 runs the quantum circuit with 100 shots remotely on the quantum device

AWS Devices

NumShots — Number of times to run circuit

100 (default) | positive integer scalar

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

IBM Devices

NumShots — Number of times to run circuit

100 (default) | positive integer scalar

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

OptimizationLevel — Optimization level to perform on circuit

3 (default) | 2 | 1 | 0

Optimization level to perform on the circuit, specified as a 3, 2, 1, or 0. By default, OptimizationLevel is equal to 3.

Higher levels generate more optimized circuits. However, because the optimization is done by rewriting a given input circuit to match the topology of a specific quantum device for execution (also known as transpilation), a better optimization comes at the expense of longer transpilation times. For example, OptimizationLevel of 0 provides no optimization and OptimizationLevel of 3 provides high optimization.

UseErrorMitigation — Toggle to apply error mitigation

logical 1 (true) (default) | logical 0 (false)

Toggle to apply error mitigation, specified as a logical 1 (true) or 0 (false). The error mitigation is a collection of tools and methods to process measurement results that are aimed at reducing the effects of measurement errors.

Output Arguments

task — Task that runs circuit on quantum device

QuantumTaskAWS object | QuantumTaskIBM object

Task that runs the circuit on a quantum device, returned as a QuantumTaskAWS or a QuantumTaskIBM object. 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

R2023b: Connect to quantum hardware through IBM (October 2023; Version 23.2.1)

Run gate-based quantum algorithms by connecting to quantum hardware provided by IBM Qiskit^® Runtime Services.

• quantum.backend.QuantumDeviceIBM

• quantum.backend.QuantumTaskIBM

• Use the run function to run a quantum circuit on a QuantumDeviceIBM object

To set up access using your IBM account, see Run Quantum Circuit on Hardware Using IBM Qiskit Runtime Services.