> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flow

#### 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.
  * **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`.
* **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[bitstring, quasi-probability]`), 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]`.
  <br />
  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:**
  HybridJobModel

#### Examples

Single circuit, no parameters, no observables:

```python theme={null}
>>> 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:

```python theme={null}
>>> 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:

```python theme={null}
>>> 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:

```python theme={null}
>>> 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:

```python theme={null}
>>> 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:

```python theme={null}
>>> 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:

```python theme={null}
>>> 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:

```python theme={null}
>>> 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]]]
```