Main Content

quantum.backend.QuantumTaskIBM Class

Namespace: 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 the 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 the task identifier with the following syntaxes.



task = quantum.backend.QuantumTaskIBM(taskID) returns a QuantumTaskIBM handle object that represents an existing remote task on the IBM Qiskit Runtime Services with the specified 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. This syntax sets the TaskID property to taskID.

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 options using one or more name-value arguments.

  • You can specify the filename of a 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

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

Name of the JSON file for authentication, specified as a string scalar. By default, the filename is "qiskit-ibm.json", which 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 filename to specify your account credentials for authentication.

The JSON file must contain strings that represent scalar structures with these 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 for these fields from your IBM account, see Set Up Access to IBM.

In the JSON file, you can specify multiple sets of account credentials by creating a structure for each account. For each account structure, specify the field name as the account name and the 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 credentials file.

This argument sets the AccountName property.


expand all

Identifier of the task, returned as a string scalar. Specify the value of this property during creation of the object.

This property value can be saved and used in a future MATLAB session to construct a new QuantumTaskIBM object and query the task status.



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



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

This property is set by the AccountName name-value argument.



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