Main Content

quantum.backend.QuantumTaskIBM class

Package: quantum.backend

Task sent to IBM for execution on quantum device

Since R2023b

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


A QuantumTaskIBM object represents a task sent for execution on a quantum device that is available through IBM® Qiskit® Runtime Services. To work with remote devices and data using IBM Qiskit Runtime Services, you must first set up access following the steps in Run Quantum Circuit on Hardware Using IBM Qiskit Runtime Services.

The quantum.backend.QuantumTaskIBM class is a handle class.


Use the run function to run a quantum circuit remotely on a quantum device available through IBM Qiskit Runtime Services and return the task as a QuantumTaskIBM object.

Additionally, you can create a QuantumTaskIBM object from an existing remote task on IBM using that task identifier with the following syntaxes.



task = quantum.backend.QuantumTaskIBM(taskID) returns a QuantumTaskIBM handle object that is created from an existing remote task on IBM Qiskit Runtime Services using that task identifier. You can retrieve the task identifier of an existing task by accessing its TaskID property value or by using the IBM web interface.

A remote task expires after some time. Use fetchOutput on the QuantumTaskIBM object and save the returned QuantumMeasurement object to store the result.

task = quantum.backend.QuantumTaskIBM(taskID,Name=Value) specifies additional options using one or more name-value arguments.

  • You can specify the file name of the JSON file that contains your credentials for authentication with the Qiskit Runtime Services using quantum.backend.QuantumTaskIBM(taskID,FileName=filename).

  • You can specify the account name in the credentials file to use for authentication when retrieving the task using quantum.backend.QuantumTaskIBM(taskID,AccountName=accountname).


Saving and loading QuantumTaskIBM objects in MATLAB® are not supported. To check on a task from a previous MATLAB session, save the TaskID property value of the QuantumTaskIBM object from the previous session and construct a new QuantumTaskIBM object in the new MATLAB session.

Input Arguments

expand all

Identifier of the task, specified as a string scalar.

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: s = quantum.backend.QuantumTaskIBM("123456abcdef",FileName="myIBMconnection.json",AccountName="my_second_acc")

File name of the JSON file for authentication, specified as a string scalar. By default, the file name is "qiskit-ibm.json" that is located in your .qiskit folder in the home directory. Do not manually edit this "qiskit-ibm.json" file. Instead, create a new JSON file with a different file name to specify your account credentials for authentication.

The JSON file must contain strings that represent scalar structures with the following three required fields.

  • "channel" — the channel for your account, which must be "ibm_quantum" or "ibm_cloud"

  • "instance" — the service instance for your account

  • "token" — the unique API token that is assigned to your account

To retrieve the information about these fields from your IBM account, see Set Up Access to IBM. In the JSON file, specify multiple sets of your account credentials by creating a structure with a given account name as the field name. For each of this account name, set its field value as a structure with the three required "channel", "instance", and "token" fields. For an example, see Specify JSON File and Account Name for Authentication.

Account name in the credentials file to use for authentication, specified as a string scalar. By default, the account name used is the first account listed in the JSON file for authentication.


expand all

Identifier of the task, returned as a string scalar.



Identifier of the session where the task belongs to, returned as a string scalar.



Account name in the credentials file to use for authentication, returned as a string scalar.



Status of the task, returned as "queued", "running", "finished", or "failed".




expand all


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 IBM Qiskit Runtime Services. Create a task by running the circuit on the device.

dev = quantum.backend.QuantumDeviceIBM("ibmq_qasm_simulator");
task = run(c,dev)
task = 

  QuantumTaskIBM with properties:

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

Wait for the task to finish and retrieve the result.

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.Probabilities,m.MeasuredStates, ...
ans =

  4×2 table

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

Version History

Introduced in R2023b

expand all