Main Content

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

Follow these steps to enable communication between MATLAB and IBM Qiskit Runtime Services.

  1. Set up account. Authentication is required using an access plan available through the IBM Cloud® and/or IBM Quantum® platforms. See the Qiskit Runtime page to sign up for an access plan. Running jobs on hardware by using 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. Follow the corresponding link to log in to your account and retrieve access credentials. If your account is managed by your organization, then you might need to contact your administrator for the recommended way to retrieve credentials. Authentication requires a channel, an instance, and a token. For more details, see Select an IBM Quantum channel. After setting up your account, you need these three credentials to create the JSON file in the next step, which can be acquired by following the respective links:

    • IBM Cloud: The channel is "ibm_cloud". View or create a service instance by accessing the Instances page and clicking an instance. In the page that opened, click the icon to copy the Cloud Resource Name (CRN), which will be the service instance. Create an API token by accessing the API keys page.

    • IBM Quantum: The channel is "ibm_quantum". Once logged in, navigate to Manage account using the user icon at the top right of the page. From here, generate an API token which is used as the token for authentication. At the bottom of this page, the service instance is located under 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 page. The channel is either "ibm_cloud" or "ibm_quantum" depending on where the token and service instance were obtained from.

  3. Create JSON file.

    Replace the ellipses below with your three credentials obtained from the previous step.

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

    Replace the account name below with a name you would like to associate with this set of account credentials.

    myAccountName = "myAccountName";

    Replace the ellipse below with a file name that will contain the account credentials. The name of the file must end in .json.

    myFileName = "...";

    Create the JSON file by executing the following code block in MATLAB. This writes the account credentials into the expected JSON format. Multiple sets of account credentials can be added to the same file in JSON format 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, go to the main page for your account and log in. Follow the steps below for your account type:

This page contains information on various devices, including availability, and other data. 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 stretch 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 name of the device and the account name to authenticate using the associated credentials. Set the file name 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 will 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

| | |

Related Topics