Haiqu.flow(program, circuits, shots=1000, parameters=None, observables=None, job_name=None, job_description=None, device_credentials=None, dry_run=False)

Run a flow (hybrid program). 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:
- program (HybridProgram) — The hybrid program to execute.
- circuits (QuantumCircuit | list *[*QuantumCircuit ] | CircuitModel | list *[*CircuitModel ]) — The quantum circuit(s) to pass to the hybrid program. Can be a single circuit or a list of circuits.
- shots (int) — The number of shots for each circuit execution. Defaults to 1000.
- 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.
- 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.
- 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.
- device_credentials (dict | None) — Credentials for device access.
- 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. Wall-clock time to run hybrid program layers up to (but not including) the device layer is available via job.pre_device_pipeline_time (also on full runs).
Returns: The Hybrid job that will execute the hybrid program. : 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].
Dry runs (dry_run=True): result() is empty. Use job.estimated_qpu_cost for the QPU cost estimate and job.pre_device_pipeline_time for classical hybrid time before the device layer. job.time is 0 because the device phase does not run.
Full runs (dry_run=False): job.time is the device-phase wall clock (from when device execution starts to job completion). job.pre_device_pipeline_time reports classical hybrid time before the device layer. job.info also exposes auxiliary metadata (uncertainty when observables are supplied, qpu_cost on full runs). Run help(job.result) for the full description of result and info contents.
Return type: HybridJobModel

Examples

Single circuit, no parameters, no observables:

>>> from qiskit import QuantumCircuit
>>> from haiqu.sdk.hybrid import HybridProgram, layers
>>> program = HybridProgram(layers=[
...     layers.InputLayer(),
...     layers.DeviceLayer(device_id="aer_simulator"),
... ])
>>> qc = QuantumCircuit(2)
>>> qc.h(0)
>>> qc.cx(0, 1)
>>> qc.measure_all()
>>> job = haiqu.flow(program, circuits=qc)
>>> 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
>>> from haiqu.sdk.hybrid import HybridProgram, layers
>>> program = HybridProgram(layers=[
...     layers.InputLayer(),
...     layers.DeviceLayer(device_id="aer_simulator"),
... ])
>>> theta = Parameter('θ')
>>> qc = QuantumCircuit(2)
>>> qc.ry(theta, 0)
>>> qc.cx(0, 1)
>>> qc.measure_all()
>>> job = haiqu.flow(
...     program,
...     circuits=qc,
...     parameters=[[0.5], [1.0]],
... )
>>> 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
>>> from haiqu.sdk.hybrid import HybridProgram, layers
>>> program = HybridProgram(layers=[
...     layers.InputLayer(),
...     layers.EstimatorLayer(),
...     layers.DeviceLayer(device_id="aer_simulator"),
... ])
>>> qc = QuantumCircuit(2)
>>> qc.h(0)
>>> qc.cx(0, 1)
>>> obs = [SparsePauliOp("ZZ"), SparsePauliOp("XY")]
>>> job = haiqu.flow(
...     program,
...     circuits=qc,
...     observables=obs,
... )
>>> 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
>>> from haiqu.sdk.hybrid import HybridProgram, layers
>>> program = HybridProgram(layers=[
...     layers.InputLayer(),
...     layers.EstimatorLayer(),
...     layers.DeviceLayer(device_id="aer_simulator"),
... ])
>>> 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.flow(
...     program,
...     circuits=qc,
...     parameters=params,
...     observables=obs,
... )
>>> 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
>>> from haiqu.sdk.hybrid import HybridProgram, layers
>>> program = HybridProgram(layers=[
...     layers.InputLayer(),
...     layers.DeviceLayer(device_id="aer_simulator"),
... ])
>>> 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.flow(program, circuits=circuits)
>>> 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
>>> from haiqu.sdk.hybrid import HybridProgram, layers
>>> program = HybridProgram(layers=[
...     layers.InputLayer(),
...     layers.DeviceLayer(device_id="aer_simulator"),
... ])
>>> 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.flow(
...     program,
...     circuits=circuits,
...     parameters=params,
... )
>>> 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
>>> from haiqu.sdk.hybrid import HybridProgram, layers
>>> program = HybridProgram(layers=[
...     layers.InputLayer(),
...     layers.EstimatorLayer(),
...     layers.DeviceLayer(device_id="aer_simulator"),
... ])
>>> 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.flow(
...     program,
...     circuits=circuits,
...     observables=obs,
... )
>>> 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
>>> from haiqu.sdk.hybrid import HybridProgram, layers
>>> program = HybridProgram(layers=[
...     layers.InputLayer(),
...     layers.EstimatorLayer(),
...     layers.DeviceLayer(device_id="aer_simulator"),
... ])
>>> 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.flow(
...     program,
...     circuits=circuits,
...     parameters=params,
...     observables=obs,
... )
>>> 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]]]

Hybrid program layers

A HybridProgram is an ordered list of layers. Grouped error mitigation is handled by EstimatorLayer (observable expectation values) or DistributionMitigationLayer (raw measurement distributions). For hand-built pipelines, compose explicit processing steps instead. Advanced mitigation uses separate wire types for each mitigation path:

AdvancedObsMitigationLayer — observable-based advanced mitigation (for example after ObservableSplitLayer)
AdvancedDistMitigationLayer — distribution-based advanced mitigation

Layers that make up a hybrid program. A program is an ordered list of layers describing how your circuits are processed and run. It starts with an InputLayer and ends with a DeviceLayer. Use EstimatorLayer or DistributionMitigationLayer for grouped error mitigation, or compose finer processing steps by hand. For advanced mitigation in manual pipelines, pick the layer for the mitigation path: AdvancedObsMitigationLayer for observable-based mitigation and AdvancedDistMitigationLayer for distribution-based mitigation.

class haiqu.sdk.hybrid.layers.AdvancedDistMitigationLayer(*, type=‘advanced_dist_mitigation’)

Advanced distribution-based error mitigation for hand-built pipelines. Use this in place of the advanced_mitigation flag on grouped mitigation layers when manually enabling distribution-based advanced mitigation.

Parameters: type (Literal [ ‘advanced_dist_mitigation’ ])