Run Quantum Circuit on Hardware Using IBM Qiskit Runtime Service

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

  • A JSON file that contains your IBM account credentials (one-time setup)

Set Up Access to IBM

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

  1. Set up account. Authentication requires using an access plan available through the IBM Cloud® 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.

  2. Retrieve credentials. Log in to your IBM Cloud account to retrieve access credentials, which include the "ibm_cloud" 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. You can 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.

    At this point, confirm that you have an IBM Cloud account with the service instance and token accessible from the respective web pages.

  3. Create JSON file. Store your account credentials in a JSON file for authentication purposes when running tasks on IBM quantum devices. Create the JSON file by executing the following code in a MATLAB program file (.m or .mlx) or in the MATLAB Command Window. This code ensures the JSON file has the expected fields.

    Replace the ellipses in this code with the three credentials obtained from the previous step.

    myChannel = "ibm_cloud";
myInstance = "...";
myToken = "...";

    Replace the string in this code with a name you want to associate with this set of account credentials.

    myAccountName = "myName";

    Replace the string in this code with a filename for your JSON credentials file. The name of the file must end in .json.

    myFileName = "myFolder/myFile.json";

    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. This step generates the JSON file using the filename and folder path you provided.

    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 IBM Cloud account. Then go to Compute resources and 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 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 exceed 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 by running the following code in MATLAB. Specify the name of the device. Use the account name associated with your credentials and set the filename to the previously saved JSON file that contains your credentials.

myAccountName = "myName";
myFileName = "myFolder/myFile.json";
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 can 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"

See Also

| | |

Topics