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.

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.

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.

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 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\rangle$$ and $$|10\rangle$$ 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" 

Retrieve Task from Previous Session on AWS

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

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 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\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, 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\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 from Previous Session on IBM

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

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

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.

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 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 100.

UseErrorMitigation — Option to apply error mitigation

true or 1 (default) | false or 0

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

task — Task that runs circuit on quantum device

QuantumTaskAWS object | QuantumTaskIBM object

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

R2024b: OptimizationLevel argument is not supported (January 2025, Version 24.2.3)

The OptimizationLevel name-value argument is no longer supported. Code that uses this argument generates an error. This change affects all versions of MATLAB Support Package for Quantum Computing.

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 the IBM Qiskit^® Runtime Services.

• Represent an IBM quantum device by using a quantum.backend.QuantumDeviceIBM object.

• Represent a task on an IBM quantum device by using a quantum.backend.QuantumTaskIBM object.

• 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 Service.