Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Loop-5 operation specification #2291

Merged
merged 19 commits into from
Oct 14, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
e890e79
Draft version of the Loop-5 operation specification
lazarevevgeny Sep 16, 2020
174d9f2
Draft version of the Loop-5 operation specification
lazarevevgeny Sep 16, 2020
5105cb1
Merge remote-tracking branch 'upstream/master' into loop_specification
lazarevevgeny Sep 16, 2020
3402577
Example modification
lazarevevgeny Sep 16, 2020
c6d6880
Update for the Loop-5 specification
lazarevevgeny Sep 17, 2020
c5bcca9
Specification update
lazarevevgeny Sep 17, 2020
4b91b50
Resolve review remarks
itikhono Sep 29, 2020
cf5c3f8
Renaming from termination condition to condition
itikhono Sep 29, 2020
4daa7d1
Merge remote-tracking branch 'upstream/master' into loop_specification
itikhono Sep 29, 2020
9f890c0
Updated Loop specification
lazarevevgeny Oct 8, 2020
7278329
Updated necessary documents for Loop specification
lazarevevgeny Oct 8, 2020
8877db1
Updated Loop specification
lazarevevgeny Oct 8, 2020
94ae4ff
Merge remote-tracking branch 'upstream/master' into loop_specification
lazarevevgeny Oct 8, 2020
3ff03fe
Merge remote-tracking branch 'upstream/master' into loop_specification
lazarevevgeny Oct 12, 2020
0293f69
Updated Loop-5 specification
lazarevevgeny Oct 12, 2020
f5c50b5
Merge remote-tracking branch 'upstream/master' into loop_specification
lazarevevgeny Oct 12, 2020
867b01b
Merge remote-tracking branch 'upstream/master' into loop_specification
lazarevevgeny Oct 12, 2020
8ea1856
Merge remote-tracking branch 'upstream/master' into loop_specification
lazarevevgeny Oct 13, 2020
ea42545
Merge remote-tracking branch 'upstream/master' into loop_specification
lazarevevgeny Oct 14, 2020
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/doxygen/ie_docs.xml
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,7 @@
<tab type="user" title="LogicalOr-1" url="@ref openvino_docs_ops_logical_LogicalOr_1"/>
<tab type="user" title="LogicalXor-1" url="@ref openvino_docs_ops_logical_LogicalXor_1"/>
<tab type="user" title="LogSoftmax-5" url="@ref openvino_docs_ops_activation_LogSoftmax_5"/>
<tab type="user" title="Loop-5" url="@ref openvino_docs_ops_infrastructure_Loop_5"/>
<tab type="user" title="MVN-1" url="@ref openvino_docs_ops_normalization_MVN_1"/>
<tab type="user" title="MatMul-1" url="@ref openvino_docs_ops_matrix_MatMul_1"/>
<tab type="user" title="MaxPool-1" url="@ref openvino_docs_ops_pooling_MaxPool_1"/>
Expand Down
181 changes: 181 additions & 0 deletions docs/ops/infrastructure/Loop_5.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
## Loop <a name="Loop"></a> {#openvino_docs_ops_infrastructure_Loop_5}

**Versioned name**: *Loop-5*

**Category**: Infrastructure

**Short description**: *Loop* operation performs recurrent execution of the network, which is described in the `body`, iterating through the data.
The operation has similar semantic to the ONNX* Loop [operation](https://github.com/onnx/onnx/blob/master/docs/Changelog.md#Loop-13).

**Detailed description**

The body of the Loop can be executed 0 or more times depending on the values passed to the Loop operation inputs called "trip count", "execution condition" and input of the Loop body called "current iteration".

These Loop operation inputs have the following meaning:
1. Trip count is an integer scalar or 1D tensor with 1 element input specifying maximum number of iterations. To simulate infinite loop Constant `-1` can be provided as input.
2. Loop execution condition input is a boolean scalar or 1D tensor with 1 element input specifying whether to run the first loop iteration or not. Note, that the body of the Loop must yield the condition value for the consecutive iterations.

There are several combinations of these two inputs `(trip_count, execution condition)` which are described in the following code snippet:

```
input (-1, true) // infinite loop
bool cond = true;
for (int i = 0; cond; ++i)
{
cond = true; // sub-graph calculating condition must always return "true"!
}

input (-1, cond) // while loop
bool cond = ...;
for (int i = 0; cond; ++i)
{
cond = ...;
}

input (-1, true) // do-while loop
bool cond = true;
for (int i = 0; cond; ++i)
{
cond = ...;
}

input (trip_count, true) // for loop
int trip_count = ...;
bool cond = true;
for (int i = 0; i < trip_count; ++i)
{
cond = true; // sub-graph calculating condition must always return "true"!
}

input (trip_count, cond) // for with condition
int trip_count = ...;
bool cond = ...;
for (int i = 0; i < trip_count && cond; ++i)
{
cond = ...;
}
```

1. One of the body graph inputs called "current iteration" is an integer scalar or 1D integer tensor with 1 number specifying current iteration number. The iteration number starts from 0 and incremented by one for each iteration. This input is optional and may not exist if the iteration number value is not used in the body.
2. One of the body graph outputs is called "condition" is a boolean scalar or 1D tensor with 1 element. This value is used to decide whenever to perform the next iteration or not.
lazarevevgeny marked this conversation as resolved.
Show resolved Hide resolved

Loop operation description in the IR has regular sections: `input` and `output`. They connect Loop body to the outer graph and specify condition(s).
Loop operation description in the IR also has several special sections: `body`, `port_map` and `back_edges` similar to the ones from the TensorIterator operation but having some important features described below.

1. The body operation getting an input from the main graph should have an entry in the `port_map` section of the Loop operation. These edges connect input ports of the Loop with the body `Parameter`s.
lazarevevgeny marked this conversation as resolved.
Show resolved Hide resolved
2. The body operation producing tensor to be used in the subsequent iterations (like in RNN models) should have a back edge described in the `back_edges` section of the operation. The back edge connects the respective body `Parameter` and `Result` operations. For such a case the Loop operation node provides input for the first iteration, while corresponding Loop operation output produces the tensor computed during the last iteration.
3. Output tensors produced by a particular body operation across all iterations can be concatenated and returned as a Loop operation output (this is a "scan output" according to the ONNX* Loop operation [specification](https://github.com/onnx/onnx/blob/master/docs/Changelog.md#Loop-13)). The corresponding `output` entry in the `port_map` should have `axis` attribute specifying the axis to concatenate. Therefore, outputs from operations corresponding to `output` entries in the `port_map` without `axis` attribute are returned "as is" (without concatenation).
lazarevevgeny marked this conversation as resolved.
Show resolved Hide resolved
4. There is one body `Parameter` operation not connected through the `port_map`. This is a "current iteration" input. The Loop operation is responsible for providing the appropriate value for each iteration.
5. Connection of nodes inside the Loop body with the main graph should be done through `Parameter` and `Result` body operations. No other ways to connect graphs are allowed.

itikhono marked this conversation as resolved.
Show resolved Hide resolved
**Loop attributes**:

* **Body**:

`body` is a network that will be recurrently executed. The network is described operation by operation as a typical IR network.

* **Body attributes**:

No attributes available.

* **Port map**:

*port_map* is a set of rules to map input or output data tensors of `Loop` operation onto `body` data tensors. The `port_map` entries can be` input` and `output`. Each entry describes a corresponding mapping rule.

* **Port map attributes**:

* *external_port_id*
* **Description**: *external_port_id* is a port ID of the `Loop` operation.
* **Range of values**: IDs of the *Loop* outputs
* **Type**: `int`
* **Default value**: None
* **Required**: *yes*

* *internal_layer_id*

* **Description**: *internal_layer_id* is a `Parameter` or `Result` operation ID inside the `body` network to map to.
* **Range of values**: IDs of the `Parameter` operations inside in the *Loop* operation
* **Type**: `int`
* **Default value**: None
* **Required**: *yes*

* *axis*

* **Description**: *axis* is an axis to concatenate the body `Result` output across all iterations. Can be specified for `output` entry only.
lazarevevgeny marked this conversation as resolved.
Show resolved Hide resolved
* **Range of values**: an integer. Negative value means counting dimension from the end.
* **Type**: `int`
* **Default value**: None
* **Required**: *no*

* **Back edges**:

*back_edges* is a set of rules to transfer tensor values from `body` outputs at one iteration to `body` parameters at the next iteration. Back edge connects some `Result` operation in the `body` to `Parameter` operation in the same `body`.

* **Back edge attributes**:

* *from-layer*

* **Description**: *from-layer* is a `Result` operation ID inside the `body` network.
* **Range of values**: IDs of the `Result` operations inside the *Loop*
* **Type**: `int`
* **Default value**: None
* **Required**: *yes*

* *to-layer*

* **Description**: *to-layer* is a `Parameter` operation ID inside the `body` network to end mapping.
* **Range of values**: IDs of the `Parameter` operations inside the *Loop*
* **Type**: `int`
* **Default value**: None
* **Required**: *yes*

**Loop Inputs**

* **Trip count**: A scalar or 1D tensor with 1 element of `int64` or `int32` type specifying maximum number of iterations. *Required*.

* **ExecutionCondition**: A scalar or 1D tensor with 1 element of `boolean` type specifying whether to execute the first iteration or not. `True` value means to execute the 1st iteration. *Required*.

* **Multiple other inputs**: tensors of different types and shapes. *Optional*.

**Loop Outputs**

* **Multiple outputs**: Results of execution of the `body`. Tensors of any type and shape.


**Body Inputs**

* **Multiple inputs**: tensors of different types and shapes except the one corresponding to the current iteration number. This input is marked in the port_map with attribute `purpose = "current_iteration"` and produces a scalar or 1D tensor with 1 element of `int64` or `int32` type. *Optional*.


**Body Outputs**

* **Multiple outputs**: Results of execution of the `body`. Tensors of any type and shape except the one corresponding to the output with execution condition. This output is marked in the port_map with attribute `purpose = "execution_condition"` and is mandatory and produces a scalar or 1D tensor with 1 element of `boolean` type. Other outputs are optional.


**Examples**

*Example 1: a typical Loop structure*
```xml
<layer type="Loop" ... >
<input> ... </input>
<output> ... </output>
<port_map>
<input external_port_id="0" internal_layer_id="0"/>
<input external_port_id="1" internal_layer_id="1"/>
<input external_port_id="-1" internal_layer_id="2" purpose="current_iteration"/>
...
<output external_port_id="3" internal_layer_id="4"/>
<output external_port_id="4" internal_layer_id="10" axis="1"/>
<output external_port_id="-1" internal_layer_id="22" purpose="execution_condition"/>
...
</port_map>
<back_edges>
<edge from-layer="1" to-layer="5"/>
...
</back_edges>
<body>
<layers> ... </layers>
<edges> ... </edges>
</body>
</layer>
```
1 change: 1 addition & 0 deletions docs/ops/opset5.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ declared in `namespace opset5`.
* [LogicalOr](logical/LogicalOr_1.md)
* [LogicalXor](logical/LogicalXor_1.md)
* [LogSoftmax](activation/LogSoftmax_5.md)
* [Loop](infrastructure/Loop_5.md)
* [LRN](normalization/LRN_1.md)
* [LSTMCell](sequence/LSTMCell_1.md)
* [LSTMSequence](sequence/LSTMSequence_1.md)
Expand Down