Skip to main content

​
Haiqu.run(circuits: QuantumCircuit | list[QuantumCircuit] | CircuitModel | list[CircuitModel], parameters: list | None = None, shots: int = 1000, observables: SparsePauliOp | list[SparsePauliOp] | list[list[SparsePauliOp]] | None = None, device: DeviceModel | None = None, device_id: str | None = None, options: dict | None = None, use_mitigation: bool = False, job_name: str | None = None, job_description: str | None = None) → RunJobModel

Run quantum circuits on the selected backend. This flexible method supports multiple execution scenarios, with different combinations of circuits, parameters, and observables. When multiple values are provided for any of them, the results are returned as nested lists with up to 3 layers, ordered by circuits, then observables, and finally parameters.
  • Parameters:
    • circuits — The quantum circuit(s) to execute. Can be a single circuit or a list of circuits.
    • parameters — The parameters for the circuits. Can be a single set of parameters or nested lists of parameter sets. For multiple circuits, must be a list where each element corresponds to parameters for that circuit. Defaults to None, in which case the circuits must not have any parameters.
    • shots (int) — The number of shots for each circuit execution. Defaults to 1000.
    • observables — The observable(s) to measure. The order of Pauli terms follows the Qiskit reversed-order convention. Can be a single SparsePauliOp or nested lists of SparsePauliOp. For multiple circuits, must be a list where each element corresponds to observables for that circuit. Defaults to None, in which case the circuits must include their own measurements.
    • device (DeviceModel | None) — The device to run the circuits on. If specified, device_id is ignored.
    • device_id (str | None) — The ID of the device to run the circuits on. Defaults to None.
    • options (dict | None) — Options to pass to the device.
    • use_mitigation (bool) — Whether to use error mitigation techniques. Defaults to False.
    • job_name (str | None) — The name for the job. If None (default), a name will be automatically generated.
    • job_description (str | None) — The description for the job.
  • Returns: The Run job that will execute the circuit. : Call .result() to get measurement distributions (bitstrings in Qiskit convention).
  • Return type: RunJobModel

​
Examples

Single circuit, no parameters, no observables: 
>>> from qiskit import QuantumCircuit
>>> qc = QuantumCircuit(2)
>>> qc.h(0)
>>> qc.cx(0, 1)
>>> qc.measure_all()
>>> job = haiqu.run(circuits=qc, device_id="aer_simulator")
>>> job.result()  # Returns: [dist_c1] (bitstrings in Qiskit convention)
[{'00': 0.504, '11': 0.496}]
Single circuit, multiple parameters, no observables: 
>>> from qiskit import QuantumCircuit
>>> from qiskit.circuit import Parameter
>>> theta = Parameter('θ')
>>> qc = QuantumCircuit(2)
>>> qc.ry(theta, 0)
>>> qc.cx(0, 1)
>>> qc.measure_all()
>>> job = haiqu.run(
...     circuits=qc,
...     parameters=[[0.5], [1.0]],
...     device_id="aer_simulator",
... )
>>> job.result()  # Returns: [[dist_c1_p1, dist_c1_p2]]
[[{'00': 0.934, '11': 0.066}, {'00': 0.802, '11': 0.198}]]
Single circuit, no parameters, multiple observables: 
>>> from qiskit import QuantumCircuit
>>> from qiskit.quantum_info import SparsePauliOp
>>> qc = QuantumCircuit(2)
>>> qc.h(0)
>>> qc.cx(0, 1)
>>> obs = [SparsePauliOp("ZZ"), SparsePauliOp("XY")]
>>> job = haiqu.run(
...     circuits=qc,
...     observables=obs,
...     device_id="aer_simulator",
... )
>>> job.result()  # Returns: [[exp_c1_obs1, exp_c1_obs2]]
[[1.0, 0.018000000000000016]]
Single circuit, multiple parameters, multiple observables: 
>>> from qiskit import QuantumCircuit
>>> from qiskit.circuit import Parameter
>>> from qiskit.quantum_info import SparsePauliOp
>>> theta = Parameter('θ')
>>> qc = QuantumCircuit(2)
>>> qc.ry(theta, 0)
>>> qc.cx(0, 1)
>>> params = [[0.5], [1.0]]
>>> obs = [SparsePauliOp("ZZ"), SparsePauliOp("XX")]
>>> job = haiqu.run(
...     circuits=qc,
...     parameters=params,
...     observables=obs,
...     device_id="aer_simulator",
... )
>>> job.result()  # Returns: [[[exp_c1_obs1_p1, exp_c1_obs1_p2], [exp_c1_obs2_p1, exp_c1_obs2_p2]]]
[[[1.0, 1.0], [0.49, 0.846]]]
Multiple circuits, no parameters, no observables: 
>>> from qiskit import QuantumCircuit
>>> qc1 = QuantumCircuit(2)
>>> qc1.h(0)
>>> qc1.cx(0, 1)
>>> qc1.measure_all()
>>> qc2 = QuantumCircuit(2)
>>> qc2.x(0)
>>> qc2.cx(0, 1)
>>> qc2.measure_all()
>>> circuits = [qc1, qc2]
>>> job = haiqu.run(circuits=circuits, device_id="aer_simulator")
>>> job.result()  # Returns: [dist_c1, dist_c2]
[{'11': 0.524, '00': 0.476}, {'11': 1.0}]
Multiple circuits, multiple parameters, no observables: 
>>> from qiskit import QuantumCircuit
>>> from qiskit.circuit import Parameter
>>> theta = Parameter('θ')
>>> qc1 = QuantumCircuit(2)
>>> qc1.ry(theta, 0)
>>> qc1.cx(0, 1)
>>> qc1.measure_all()
>>> qc2 = QuantumCircuit(2)
>>> qc2.rx(theta, 0)
>>> qc2.cz(0, 1)
>>> qc2.measure_all()
>>> circuits = [qc1, qc2]
>>> params = [[[0.5], [1.0]], [[0.3], [0.7]]]  # Parameters for each circuit
>>> job = haiqu.run(
...     circuits=circuits,
...     parameters=params,
...     device_id="aer_simulator",
... )
>>> job.result()  # Returns: [[dist_c1_p1, dist_c1_p2], [dist_c2_p1, dist_c2_p2]]
[[{'00': 0.955, '11': 0.045}, {'00': 0.783, '11': 0.217}],
 [{'00': 0.982, '01': 0.018}, {'00': 0.882, '01': 0.118}]]
Multiple circuits, no parameters, multiple observables: 
>>> from qiskit import QuantumCircuit
>>> from qiskit.quantum_info import SparsePauliOp
>>> qc1 = QuantumCircuit(2)
>>> qc1.h(0)
>>> qc1.cx(0, 1)
>>> qc2 = QuantumCircuit(2)
>>> qc2.x(0)
>>> qc2.cx(0, 1)
>>> circuits = [qc1, qc2]
>>> obs = [[SparsePauliOp("ZZ"), SparsePauliOp("XX")],
...        [SparsePauliOp("YY"), SparsePauliOp("ZX")]]  # Observables for each circuit
>>> job = haiqu.run(
...     circuits=circuits,
...     observables=obs,
...     device_id="aer_simulator",
... )
>>> job.result()  # Returns: [[exp_c1_obs1, exp_c1_obs2], [exp_c2_obs1, exp_c2_obs2]]
[[1.0, 1.0], [0.0, -0.0020000000000000018]]
Multiple circuits, multiple parameters, multiple observables: 
>>> from qiskit import QuantumCircuit
>>> from qiskit.circuit import Parameter
>>> from qiskit.quantum_info import SparsePauliOp
>>> theta = Parameter('θ')
>>> qc1 = QuantumCircuit(2)
>>> qc1.ry(theta, 0)
>>> qc1.cx(0, 1)
>>> qc2 = QuantumCircuit(2)
>>> qc2.rx(theta, 0)
>>> qc2.cz(0, 1)
>>> circuits = [qc1, qc2]
>>> params = [[[0.5], [1.0]], [[0.3], [0.7]]]  # Parameters for each circuit
>>> obs = [[SparsePauliOp("ZZ"), SparsePauliOp("XX")],
...        [SparsePauliOp("YY"), SparsePauliOp("ZX")]]  # Observables for each circuit
>>> job = haiqu.run(
...     circuits=circuits,
...     parameters=params,
...     observables=obs,
...     device_id="aer_simulator",
... )
>>> job.result()
# Returns: [
#     [[exp_c1_obs1_p1, exp_c1_obs1_p2], [exp_c1_obs2_p1, exp_c1_obs2_p2]],
#     [[exp_c2_obs1_p1, exp_c2_obs1_p2], [exp_c2_obs2_p1, exp_c2_obs2_p2]],
# ]
[[[1.0, 1.0], [0.482, 0.8280000000000001]],
 [[-0.016000000000000014, 0.003999999999999963],
  [-0.02400000000000002, 0.008000000000000007]]]