run
Installation Required: This functionality requires MATLAB Support Package for Quantum Computing.
Description
runs the quantum circuit task
= run(c
,dev
)c
remotely on a quantum device
dev
.
The input dev
must be a QuantumDeviceAWS
or
QuantumDeviceIBM
object that connects to a quantum device available
through AWS® or IBM®, respectively. The output task
is a
QuantumTaskAWS
or QuantumTaskIBM
object, which can
be used to monitor the task and retrieve its result. By default, the run
function runs the circuit with 100 shots.
specifies options using one or more name-value arguments. For example, you can specify
task
= run(c
,dev
,Name=Value
)NumShots=n
to run the circuit with n
shots remotely
on the quantum device.
Note
Running a circuit on a remote quantum device results in charges to your account with the remote service.
Examples
Run Circuit Remotely on AWS Quantum Device
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 AWS. Create a task that runs the circuit on the device with 100 shots.
dev = quantum.backend.QuantumDeviceAWS("Lucy");
task = run(c,dev)
task = QuantumTaskAWS with properties: Status: "queued" TaskARN: "arn:aws:braket:eu-west-2:123456789012:quantum-task/abcd1234-4567-8901-ef12-abcd0987efab6543"
Wait for the task to finish. Retrieve the result of running the circuit on the device.
wait(task) 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. Due to the noise in the physical quantum device, the and states can appear as measurements.
table(m.Counts,m.Probabilities,m.MeasuredStates, ... VariableNames=["Counts","Probabilities","States"])
ans = 4×3 table Counts Probabilities States ______ _____________ ______ 46 0.46 "00" 9 0.09 "10" 3 0.03 "01" 42 0.42 "11"
Retrieve Task from Previous Session on AWS
Create a quantum circuit that applies the quantum Fourier transform to five qubits.
gates = qftGate(1:5); c = quantumCircuit(gates);
Connect to a remote quantum device through AWS. Create a task that runs the circuit on the device with 2000 shots.
dev = quantum.backend.QuantumDeviceAWS("Aspen-M-3");
task = run(c,dev,NumShots=2000)
task = QuantumTaskAWS with properties: Status: "queued" TaskARN: "arn:aws:braket:us-west-1:123456789012:quantum-task/12a34b5c-6a78-9a01-2ab3-4c56def7g890"
Save the ARN string value in the task.TaskARN
property.
ARNstr = task.TaskARN; save ARNstr.mat ARNstr
You can close the current MATLAB® session. To retrieve the previously queued task in a new MATLAB session, you can use the ARN of that task to create the
QuantumTaskAWS
object again.
load ARNstr.mat
task = quantum.backend.QuantumTaskAWS(ARNstr)
task = QuantumTaskAWS with properties: Status: "running" TaskARN: "arn:aws:braket:us-west-1:123456789012:quantum-task/12a34b5c-6a78-9a01-2ab3-4c56def7g890"
Wait for the task to finish and retrieve the result.
wait(task) m = fetchOutput(task)
m = QuantumMeasurement with properties: MeasuredStates: [32×1 string] Counts: [32×1 double] Probabilities: [32×1 double] NumQubits: 5
Run Circuit Remotely on IBM Quantum Device with Error Mitigation
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. Create a task that runs the circuit 500 times on the device without error mitigation.
dev = quantum.backend.QuantumDeviceIBM("ibmq_qasm_simulator");
task = run(c,dev,NumShots=500,UseErrorMitigation=false);
task = QuantumTaskIBM with properties: TaskID: "123abcd4efa5bcdef678" SessionID: <missing> AccountName: "<my account name>" Status: "queued"
Wait for the task to finish. Retrieve the result of running the circuit on the device.
wait(task) 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. Due to the noise in the physical quantum device, the and states can appear as measurements.
table(m.Probabilities,m.MeasuredStates, ... VariableNames=["Probabilities","States"])
ans = 4×2 table Probabilities States _____________ ______ 0.536 "00" 0.018 "10" 0.024 "01" 0.422 "11"
Next, create a task that runs the circuit on the same device, but with quantum error mitigation. The error mitigation applies a collection of tools and methods to the measurement results that attempts to reduce the effects of measurement errors.
task = run(c,dev,NumShots=500,UseErrorMitigation=true);
Wait for the task to finish. Retrieve the result of running the circuit on the device.
wait(task) 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 with error mitigation. Here, the estimated probabilities of the and states are closer to 0.
table(m.Probabilities,m.MeasuredStates, ... VariableNames=["Probabilities","States"])
ans = 4×2 table Probabilities States _____________ ______ 0.59254 "00" 0.001586 "10" -0.0094173 "01" 0.4153 "11"
Retrieve Task from Previous Session on IBM
Create a quantum circuit that applies the quantum Fourier transform to five qubits.
gates = qftGate(1:5); c = quantumCircuit(gates);
Connect to a remote quantum device through IBM. Create a task that runs the circuit on the device with 500 shots.
dev = quantum.backend.QuantumDeviceIBM("ibmq_qasm_simulator");
task = run(c,dev,NumShots=500);
task = QuantumTaskIBM with properties: TaskID: "123abcd4efa5bcdef678" SessionID: <missing> AccountName: "<my account name>" Status: "queued"
Save the task identifier string value in the task.TaskID
property.
taskIDstr = task.TaskID; save taskIDstr.mat taskIDstr
You can close the current MATLAB session. To retrieve the previously queued task in a new MATLAB session, you can use the identifier of that task to create the
QuantumTaskIBM
object again.
load taskIDstr.mat
task = quantum.backend.QuantumTaskIBM(taskIDstr)
task = QuantumTaskIBM with properties: TaskID: "123abcd4efa5bcdef678" SessionID: <missing> AccountName: "<my account name>" Status: "running"
Wait for the task to finish and retrieve the result.
wait(task) m = fetchOutput(task)
m = QuantumMeasurement with properties: MeasuredStates: [32×1 string] Counts: [32×1 double] Probabilities: [32×1 double] NumQubits: 5
Input Arguments
c
— Quantum circuit
quantumCircuit
object
Quantum circuit, specified as a quantumCircuit
object.
dev
— Quantum device
QuantumDeviceAWS
object | QuantumDeviceIBM
object
Quantum device, specified as a QuantumDeviceAWS
or
QuantumDeviceIBM
object. Use the quantum.backend.QuantumDeviceAWS
or quantum.backend.QuantumDeviceIBM
constructor to create this object, which
connects to a remote quantum device through AWS or IBM, respectively.
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 = run(c,dev,NumShots=500)
runs the quantum circuit
c
with 500
shots remotely on the quantum device
dev
.
NumShots
— Number of times to run circuit
100 (default) | positive integer scalar
Number of times to run the circuit, specified as a positive integer scalar. By
default, NumShots
is 100.
NumShots
— Number of times to run circuit
100 (default) | positive integer scalar
Number of times to run the circuit, specified as a positive integer scalar. By
default, NumShots
is 100.
OptimizationLevel
— Level of optimization to perform on circuit
3 (default) | 2 | 1 | 0
Level of optimization to perform on the circuit, specified as a 3, 2, 1, or 0. An
optimization level of 0 provides no optimization, and an optimization level of 3
provides the most optimization. By default, OptimizationLevel
is
3.
Higher levels generate more optimized circuits. However, because the optimization rewrites a given input circuit to match the topology of a specific quantum device for execution (also known as transpilation), better optimization comes at the expense of longer transpilation times.
UseErrorMitigation
— Option to apply error mitigation
true
or 1
(default) | false
or 0
Option to apply error mitigation, specified as a numeric or logical
1
(true
) or 0
(false
). The error mitigation applies a collection of tools and
methods to the measurement results that attempts to reduce the effects of measurement
errors.
Output Arguments
task
— Task that runs circuit on quantum device
QuantumTaskAWS
object | QuantumTaskIBM
object
Task that runs the circuit on a quantum device, returned as
QuantumTaskAWS
or a QuantumTaskIBM
object. You
can check the status of the task by querying the Status
property of
this object, where the status can be "queued"
,
"running"
, "finished"
, or
"failed"
. Once the task is finished, you can retrieve the
measurement result from this object by using the fetchOutput
function.
Version History
Introduced in R2023aR2023b: Connect to quantum hardware through IBM (October 2023; Version 23.2.1)
Run gate-based quantum algorithms by connecting to quantum hardware provided by the IBM Qiskit® Runtime Services.
Represent an IBM quantum device by using a
quantum.backend.QuantumDeviceIBM
object.Represent a task on an IBM quantum device by using a
quantum.backend.QuantumTaskIBM
object.Use the
run
function to run a quantum circuit on aQuantumDeviceIBM
object.
To set up access using your IBM account, see Run Quantum Circuit on Hardware Using IBM Qiskit Runtime Services.
See Also
Classes
quantumCircuit
|quantum.backend.QuantumDeviceAWS
|quantum.backend.QuantumTaskAWS
|quantum.backend.QuantumDeviceIBM
|quantum.backend.QuantumTaskIBM
Functions
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)