Run

​

Haiqu.run(circuits, parameters=None, shots=1000, observables=None, readout_bases=None, device=None, device_id=None, options=None, use_mitigation=False, use_packing=False, pack_size=None, job_name=None, job_description=None, dry_run=False)

​

NOTE

• Parameters:
  • circuits (QuantumCircuit | list *[*QuantumCircuit ] | CircuitModel | list *[*CircuitModel ]) — The quantum circuit(s) to execute. Can be a single circuit or a list of circuits.
  • parameters (list | None) — 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. Each inner list must have length circuit.num_parameters. Values are bound positionally in the order of Qiskit’s QuantumCircuit.parameters. When parameters are created one-by-one, that order is typically alphabetical by name (e.g. theta10 before theta2), independent of gate addition order; ParameterVector circuits use vector index order instead (e.g. theta[0], theta[1]). Inspect list(circuit.parameters) for the exact order.
  • shots (int) — The number of shots for each circuit execution. Defaults to 1000.
  • observables (SparsePauliOp | list *[*SparsePauliOp ] | list *[*list *[*SparsePauliOp ] ] | None) — The observable(s) to measure. The order of Pauli terms in a single string follows the Qiskit reversed-order convention (e.g., "IZ" measures qubit 0 in the Z basis). Defaults to None, in which case the circuits must include their own measurements. Accepted shapes:
    • Single circuit: a single SparsePauliOp, the nested form [[op1, op2, ...]], or a bare list [op1, op2, ...].
    • Multiple circuits: a list of length num_circuits, where each element is independently either a single SparsePauliOp (one observable on that circuit) or a list of SparsePauliOp (multiple observables on that circuit). Mixing is allowed — [[op1, op2], op3] for two circuits is valid.
    The fully-nested form is the unambiguous canonical shape and is recommended when the same code path handles both single and multi-circuit submissions.
  • readout_bases (list *[*str ] | None) — Per-qubit Pauli bases to read the circuits out in, e.g. ["XXXX", "ZZZZ", "XZYZ"]. Each string follows the same Qiskit reversed-order convention as observables (basis[-1] applies to qubit 0) and needs one character per qubit, drawn from X, Y and Z (use Z for a qubit that should not be rotated). The circuits keep their own measurements; this rotates the readout before them. One distribution is returned per basis per circuit, so result() gains a basis axis in the same position observables occupy: [circuit][basis], or [circuit][basis][parameter] with a parameter sweep. Use RunJobModel.result_by_basis() to get them keyed by basis string. Mutually exclusive with observables. Combines with use_packing: each packed copy of the circuit is read out in the same basis, so a basis string still has one character per circuit qubit. Note that each basis is a separate execution, so the cost is len(readout_bases) * shots. Defaults to None, which reads out in the computational basis as before.
  • device (DeviceModel | None) — The device to run the circuits on. If specified, device_id is ignored. Devices from get_device() with use_fractional_gates=True use fractional gates.
  • 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. Supports an optional "error_mitigation_options" key with a dictionary of boolean flags to control individual error mitigation components when use_mitigation=True. Supported keys:
    • "dynamical_decoupling" (bool): Toggle dynamical decoupling. Defaults to True.
    • "readout_mitigation" (bool): Toggle readout error mitigation. Defaults to True.
    • "noise_tailoring" (bool): Toggle noise tailoring via Pauli twirling. Defaults to False.
    • "advanced_mitigation" (bool): Toggle advanced mitigation. Defaults to True.
    To use MPS simulation on aer_simulator, pass {"method": "matrix_product_state"}. An optional "noise_model" key runs a noisy simulation. It is only supported when device_id="aer_simulator" or device_id="ionq_simulator", and the accepted value differs by backend:
    • aer_simulator: a dict or a qiskit_aer.noise.NoiseModel object (serialized automatically before submission).
    • ionq_simulator: a str identifier naming a characterized IonQ device (e.g. "aria-1").
    Passing None (or omitting the key) runs a noiseless simulation. Simulator qubit limits (enforced server-side):
    • Statevector (aer_simulator default): up to 24 qubits.
    • MPS (aer_simulator with method="matrix_product_state", including with fake devices): no strict qubit limit.
    • Noisy simulation without MPS (fake devices such as fake_kyiv, or aer_simulator with a noise_model): up to 12 qubits.
    See the run reference for full details.
  • use_mitigation (bool) — Whether to use error mitigation techniques. Defaults to False.
  • use_packing (bool) — Whether to use circuit packing for efficient device utilization. Defaults to False. Warning: Experimental — packing replicates circuits on unused device qubits to run multiple copies in parallel, which may increase errors for deeper input circuits. For example, a 4-qubit circuit with pack_size=2 and 1000 shots runs two copies in parallel with 500 shots each, yielding 1000 shots of results while only paying for 500 shot executions on the QPU — a 2x cost saving.
  • pack_size (int | None) — Number of circuit copies to pack onto the device. Must be >= 2. Only valid when use_packing=True. If None (default), the backend will pack into at most 2/3 of the device qubits.
  • 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.
  • dry_run (bool) — Whether to stop just prior to backend execution for QPU cost estimation. Defaults to False. When True, the job result will be empty since execution on the device is skipped. The estimated QPU cost is then available via job.estimated_qpu_cost.
• Returns: The Run job that will execute the circuit. : Call job.result() to retrieve the execution results as a nested list ordered by circuits → observables → parameters:
  • Without observables: list of measurement distributions (dict[str, float]), one per circuit, in Qiskit bit-order.
  • With observables, no parameter sweep: 2D list of expectation values, indexed [circuit][observable].
  • With observables and a parameter sweep: 3D list of expectation values, indexed [circuit][observable][parameter].
  
  When dry_run=True, result() is empty; use job.estimated_qpu_cost instead. job.info exposes auxiliary metadata (uncertainty when observables are supplied, qpu_cost). Run help(job.result) for the full description of result and info contents.
• Return type: RunJobModel

​

Examples

>>> 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}]

>>> 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}]]

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

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

>>> 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}]

>>> 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}]]

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

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

>>> from qiskit.circuit.random import random_circuit
>>> circuit = random_circuit(num_qubits=20, depth=3, max_operands=3, seed=2025, measure=True)
>>> job = haiqu.run(circuit, device_id="aer_simulator", options={
...                 "method": "matrix_product_state",  # set method to MPS
...                 "matrix_product_state_max_bond_dimension": 16,  # preferably, limit the bonds
...               })