:nosearch:

.. _op_ai_onnx_Loop-11:

Loop - version 11
=================

This page documents version **11** of operator **Loop**. See :doc:`Loop` for the latest version (since version 13).

- **Domain**: ``ai.onnx``
- **Since version**: 11

Generic Looping construct. This loop has multiple termination conditions:

1) Trip count. Iteration count specified at runtime. Set by
   specifying the input M. Optional. Set to empty string to omit.
   Note that a static trip count (specified at graph construction time) can be
   specified by passing in a constant node for input M.
2) Loop termination condition. This is an input to the op that determines
   whether to run the first iteration and also a loop-carried dependency for
   the body graph. The body graph must yield a value for the condition variable,
   whether this input is provided or not.

Note that the semantics of this op support "diagonal" or "wavefront" execution.
Frontends should emit multi-layer RNNs as a series of While operators (with
time being the inner looping dimension), with each successive layer consuming
the scan_outputs from the previous layer, possibly going through several
point-wise operators (e.g. dropout, residual connections, linear layer).

**Inputs**

- **M** (*I*): A maximum trip-count for the loop specified at runtime. Optional. Pass empty string to skip.
- **cond** (*B*): A boolean termination condition. Optional. Pass empty string to skip.
- **v_initial** (*V*): The initial values of any loop-carried dependencies (values that change across loop iterations)

**Outputs**

- **v_final_and_scan_outputs** (*V*): Final N loop carried dependency values then K scan_outputs

**Attributes**

- **body** (*graph*): The graph run each iteration. It has 2+N inputs: (iteration_num, condition, loop carried dependencies...). It has 1+N+K outputs: (condition, loop carried dependencies..., scan_outputs...). Each scan_output is created by concatenating the value of the specified output value at the end of each iteration of the loop. It is an error if the dimensions or data type of these scan_outputs change across loop iterations.

**Type Constraints**

- **V**: All Tensor types
  Allowed types: tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8).
- **I**: tensor of int64, which should be a scalar.
  Allowed types: tensor(int64).
- **B**: tensor of bool, which should be a scalar.
  Allowed types: tensor(bool).

Examples
--------

**test_cc_loop11_carried_state**

.. code-block:: text

    Node:
      Loop(trip_count, cond, y) -> (res_y, res_scan)
      Attributes:
        body = <subgraph>

.. code-block:: text

    Inputs:
      trip_count: shape=(), dtype=int64
        5
      cond: shape=(), dtype=bool
        True
      y: shape=(1,), dtype=float32
        [-2.]

    Outputs:
      res_y: shape=(1,), dtype=float32
        [13.]
      res_scan: shape=(5, 1), dtype=float32
        [[-1.],
         [ 1.],
         [ 4.],
         [ 8.],
         [13.]]

Differences with previous version (1)
-------------------------------------

**SchemaDiff**: ``Loop`` (domain ``'ai.onnx'``)

* old version: 1
* new version: 11
* breaking: no