Run Quantum Circuit on Hardware Using IBM Qiskit Runtime Services

Note

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

This topic describes how to connect directly from MATLAB^® to the Qiskit^® Runtime Services offered by IBM^® for running gate-based quantum circuits on remote quantum devices and simulators. Quantum hardware has limited availability as well as associated costs for each task that is run. A best practice is to finalize your circuit design as much as possible by simulating the circuit locally on your computer before running the circuit on a quantum device. See Local Quantum State Simulation for instructions on how to inspect simulated circuit results on your local computer.

Requirements

To run quantum circuits on an IBM quantum device from within MATLAB, you need:

The MATLAB Support Package for Quantum Computing
An IBM account (free to create), which provides access to Qiskit Runtime Services

Set Up Access to IBM

To enable communication between MATLAB and IBM Qiskit Runtime Services, follow these steps:

Set up account. Authentication is required using an access plan available through the IBM Cloud^® or IBM Quantum^® platform. Go to the Qiskit Runtime page to sign up for an access plan. Running jobs on hardware with the Standard plan on IBM Cloud incurs costs. These costs are charged to your account. See the access plan information for details.
Retrieve credentials. Log in to your IBM Cloud or IBM Quantum account to retrieve access credentials, which include a channel, an instance, and a token. If your account is managed by your organization, then you might need to contact your administrator for the recommended way to retrieve credentials. For more details, see Select an IBM Quantum channel. You can retrieve the three credentials by following these links, depending on your access plan:
- IBM Cloud — The channel is "ibm_cloud". View or create a service instance by accessing the Instances page. After clicking an instance, in the page that opens, click the icon to copy the Cloud Resource Name (CRN), which is the service instance. Create an API token by accessing the API keys page.
- IBM Quantum — The channel is "ibm_quantum". Go to Manage account using the user icon at the top right of the page. From here, create an API token for authentication. At the bottom of this page, the service instance is located in the Instances section and has the form {hub}/{group}/{project}.
At this point, you should have an IBM Cloud or IBM Quantum account with the service instance and token accessible from the respective web pages.
Create JSON file. Store your account credentials in a JSON file for authentication purposes when running tasks on IBM quantum devices. Create the file by running the following code in MATLAB.
Replace the ellipses in this code with the three credentials obtained from the previous step.
```
myChannel = "...";
myInstance = "...";
myToken = "...";
```
Replace the account name in this code with a name you want to associate with this set of account credentials.
```
myAccountName = "myAccountName";
```
Replace the ellipsis in this code with a filename for your JSON credentials file. The name of the file must end in .json.
```
myFileName = "...";
```
Write the account credentials into the expected JSON format. You can add multiple sets of account credentials to the same JSON file by repeatedly using jsonencode and writelines.
```
myCredentials = struct("channel",myChannel, ...
    "instance",myInstance,"token",myToken);
text = jsonencode(struct(myAccountName,myCredentials), ...
    PrettyPrint=true);
writelines(text,myFileName)
```

Device Availability

To see a list of available quantum devices, log in to your account and follow the instructions for your account type:

IBM Cloud — Go to Compute resources and then click Your resources.
IBM Quantum — Go to Compute resources and then click Your resources.

The Your resources page contains information on quantum devices, including their availability. Devices that are not currently online might still accept tasks into their queue to be run later. Check the device details to determine the status before submitting tasks.

The MATLAB Support Package for Quantum Computing works with gate-model QPU devices as well as simulators:

QPU Devices — These devices are quantum computers used to perform probabilistic measurements of circuits. Availability and number of qubits supported can also vary, so check the device details before sending circuits for measurement.
Simulator Devices — Because memory usage scales exponentially with the number of qubits, larger circuits with many qubits might exceeds the limits of memory available on your local computer. To address that issue, IBM also provides cloud-scale simulators.

Connect to Quantum Device

Connect to a quantum device using quantum.backend.QuantumDeviceIBM. Specify the names of the device and the account you want to use. Set the filename to the previously saved JSON file that contains your credentials.

device = quantum.backend.QuantumDeviceIBM("ibmq_qasm_simulator", ...
    AccountName=myAccountName,FileName=myFileName);

device = 

  QuantumDeviceIBM with properties:

           Name: "ibmq_qasm_simulator"
    AccountName: "myAccountName"
     UseSession: 0

Use fetchDetails to get additional information about the device. The returned information is the most recent available and may vary depending on the device.

fetchDetails(device)

ans = 

  struct with fields:

           Status: [1×1 struct]
    Configuration: [1×1 struct]

Create Task to Run Circuit

Create a quantum circuit with three qubits and three gates, and then plot the circuit.

gates = [hGate(1);
         cxGate(1,2);
         cxGate(2,3)];
C = quantumCircuit(gates);
plot(C)

Quantum circuit diagram with three qubits and three gates

When a circuit is measured on quantum hardware, the superposition of states for the qubits collapses into a single state, and that result is probabilistic. That is, the result of a measurement can change between runs, but the probability of each result follows the state probabilities produced by the gates in the circuit. So, it is common to run several shots, or trials, of a circuit to reveal the underlying probability distribution of results. By default, the run method uses 100 shots.

Create a task to run the circuit on the device.

task = run(C,device)

task = 

  QuantumTaskIBM with properties:

         TaskID: "abc123456defa78bcd9e"
      SessionID: <missing>
    AccountName: "myAccountName"
         Status: "queued"

Quantum devices can be in high demand, so tasks are often queued for execution. Once a task is finished, the Status property of the task object has a value of "finished". Check the status of a task by querying the Status property periodically, or use the wait method to internally check the status until the task is finished.

wait(task)

You can use cancel to cancel the task when needed. Canceling has no effect unless the status of the task is "queued" or "running".

Fetch Measurement Output

Once the task is finished, retrieve the result of running the circuit by using fetchOutput.

R = fetchOutput(task)

R = 

  QuantumMeasurement with properties:

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

Examine the measured states and their estimated probabilities in a table. The estimated probabilities can change slightly from run to run, but tend to be evenly divided between the two possible states.

T = table(R.Probabilities,R.MeasuredStates, ...
    VariableNames=["Probabilities","States"])

T =

  2×2 table

    Probabilities    States
    _____________    ______
        0.46         "000" 
        0.54         "111"