Specification for RNN/GRU sequences (#1426)

* Specification for RNN/GRU sequences

* update opset4 list
This commit is contained in:
Ivan Tikhonov 2020-07-27 09:22:46 +03:00 committed by GitHub
parent fc3f9af923
commit 98ad4ac869
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 361 additions and 31 deletions

View File

@ -62,6 +62,7 @@ declared in `namespace opset4`.
* [GroupConvolution](convolution/GroupConvolution_1.md)
* [GroupConvolutionBackpropData](convolution/GroupConvolutionBackpropData_1.md)
* [GRUCell](sequence/GRUCell_3.md)
* [GRUSequence](sequence/GRUSequence_4.md)
* [HardSigmoid](activation/HardSigmoid_1.md)
* [Interpolate](image/Interpolate_4.md)
* [Less](comparison/Less_1.md)
@ -114,6 +115,7 @@ declared in `namespace opset4`.
* [Reverse](movement/Reverse_1.md)
* [ReverseSequence](movement/ReverseSequence_1.md)
* [RNNCell](sequence/RNNCell_3.md)
* [RNNSequence](sequence/RNNSequence_4.md)
* [ROIAlign](detection/ROIAlign_3.md)
* [ROIPooling](detection/ROIPooling_1.md)
* [ScatterElementsUpdate](movement/ScatterElementsUpdate_3.md)

View File

@ -50,19 +50,19 @@
**Inputs**
* **1**: `X` - 2D tensor of type *T* `[batch_size, input_size]`, input data. Required.
* **1**: `X` - 2D tensor of type *T* `[batch_size, input_size]`, input data. **Required.**
* **2**: `initial_hidden_state` - 2D tensor of type *T* `[batch_size, hidden_size]`. Required.
* **2**: `initial_hidden_state` - 2D tensor of type *T* `[batch_size, hidden_size]`. **Required.**
* **3**: `W` - 2D tensor of type *T* `[3 * hidden_size, input_size]`, the weights for matrix multiplication, gate order: zrh. Required.
* **3**: `W` - 2D tensor of type *T* `[3 * hidden_size, input_size]`, the weights for matrix multiplication, gate order: zrh. **Required.**
* **4**: `R` - 2D tensor of type *T* `[3 * hidden_size, hidden_size]`, the recurrence weights for matrix multiplication, gate order: zrh. Required.
* **4**: `R` - 2D tensor of type *T* `[3 * hidden_size, hidden_size]`, the recurrence weights for matrix multiplication, gate order: zrh. **Required.**
* **5**: `B` - 1D tensor of type *T*. If *linear_before_reset* is set to 1, then the shape is `[4 * hidden_size]` - the sum of biases for z and r gates (weights and recurrence weights), the biases for h gate are placed separately. Otherwise the shape is `[3 * hidden_size]`, the sum of biases (weights and recurrence weights). Required.
* **5**: `B` - 1D tensor of type *T*. If *linear_before_reset* is set to 1, then the shape is `[4 * hidden_size]` - the sum of biases for z and r gates (weights and recurrence weights), the biases for h gate are placed separately. Otherwise the shape is `[3 * hidden_size]`, the sum of biases (weights and recurrence weights). **Required.**
**Outputs**
* **1**: `Ho` - 2D tensor of type *T* `[batch_size, hidden_size]`, hidden state output.
* **1**: `Ho` - 2D tensor of type *T* `[batch_size, hidden_size]`, the last output value of hidden state.
**Types**

View File

@ -0,0 +1,136 @@
## GRUSequence <a name="GRUSequence"></a> {#openvino_docs_ops_sequence_GRUSequence_4}
**Versioned name**: *GRUSequence-4*
**Category**: *Sequence processing*
**Short description**: *GRUSequence* operation represents a series of GRU cells. Each cell is implemented as <a href="#GRUCell">GRUCell</a> operation.
**Detailed description**
A single cell in the sequence is implemented in the same way as in <a href="#GRUCell">GRUCell</a> operation. *GRUSequence* represents a sequence of GRU cells. The sequence can be connected differently depending on `direction` attribute that specifies the direction of traversing of input data along sequence dimension or specifies whether it should be a bidirectional sequence. The most of the attributes are in sync with the specification of ONNX GRU operator defined <a href="https://github.com/onnx/onnx/blob/master/docs/Operators.md#gru">GRUCell</a>.
**Attributes**
* *hidden_size*
* **Description**: *hidden_size* specifies hidden state size.
* **Range of values**: a positive integer
* **Type**: `int`
* **Default value**: None
* **Required**: *yes*
* *activations*
* **Description**: *activations* specifies activation functions for gates, there are two gates, so two activation functions should be specified as a value for this attributes
* **Range of values**: any combination of *relu*, *sigmoid*, *tanh*
* **Type**: a list of strings
* **Default value**: *sigmoid,tanh*
* **Required**: *no*
* *activations_alpha, activations_beta*
* **Description**: *activations_alpha, activations_beta* attributes of functions; applicability and meaning of these attributes depends on choosen activation functions
* **Range of values**: a list of floating-point numbers
* **Type**: `float[]`
* **Default value**: None
* **Required**: *no*
* *clip*
* **Description**: *clip* specifies bound values *[-C, C]* for tensor clipping. Clipping is performed before activations.
* **Range of values**: a positive floating-point number
* **Type**: `float`
* **Default value**: *infinity* that means that the clipping is not applied
* **Required**: *no*
* *direction*
* **Description**: Specify if the RNN is forward, reverse, or bidirectional. If it is one of *forward* or *reverse* then `num_directions = 1`, if it is *bidirectional*, then `num_directions = 2`. This `num_directions` value specifies input/output shape requirements.
* **Range of values**: *forward*, *reverse*, *bidirectional*
* **Type**: `string`
* **Default value**: None
* **Required**: *Yes*
* *linear_before_reset*
* **Description**: *linear_before_reset* flag denotes if the layer behaves according to the modification of *GRUCell* described in the formula in the [ONNX documentation](https://github.com/onnx/onnx/blob/master/docs/Operators.md#GRU).
* **Range of values**: True or False
* **Type**: `boolean`
* **Default value**: False
* **Required**: *no*
**Inputs**
* **1**: `X` - 3D tensor of type *T1* `[batch_size, seq_length, input_size]`, input data. It differs from GRUCell 1st input only by additional axis with size `seq_length`. **Required.**
* **2**: `initial_hidden_state` - 3D tensor of type *T1* `[batch_size, num_directions, hidden_size]`, input hidden state data. **Required.**
* **3**: `sequence_lengths` - 1D tensor of type *T2* `[batch_size]`, specifies real sequence lengths for each batch element. **Required.**
* **4**: `W` - 3D tensor of type *T1* `[num_directions, 3 * hidden_size, input_size]`, the weights for matrix multiplication, gate order: zrh. **Required.**
* **5**: `R` - 3D tensor of type *T1* `[num_directions, 3 * hidden_size, hidden_size]`, the recurrence weights for matrix multiplication, gate order: zrh. **Required.**
* **6**: `B` - 2D tensor of type *T*. If *linear_before_reset* is set to 1, then the shape is `[num_directions, 4 * hidden_size]` - the sum of biases for z and r gates (weights and recurrence weights), the biases for h gate are placed separately. Otherwise the shape is `[num_directions, 3 * hidden_size]`, the sum of biases (weights and recurrence weights). **Required.**
**Outputs**
* **1**: `Y` 3D tensor of type *T1* `[batch_size, num_directions, seq_len, hidden_size]`, concatenation of all the intermediate output values of the hidden.
* **2**: `Ho` - 3D tensor of type *T1* `[batch_size, num_directions, hidden_size]`, the last output value of hidden state.
**Types**
* *T1*: any supported floating point type.
* *T2*: any supported integer type.
**Example**
```xml
<layer ... type="GRUSequence" ...>
<data hidden_size="128"/>
<input>
<port id="0">
<dim>1</dim>
<dim>4</dim>
<dim>16</dim>
</port>
<port id="1">
<dim>1</dim>
<dim>1</dim>
<dim>128</dim>
</port>
<port id="2">
<dim>1</dim>
</port>
<port id="3">
<dim>1</dim>
<dim>384</dim>
<dim>16</dim>
</port>
<port id="4">
<dim>1</dim>
<dim>384</dim>
<dim>128</dim>
</port>
<port id="5">
<dim>1</dim>
<dim>384</dim>
</port>
</input>
<output>
<port id="6">
<dim>1</dim>
<dim>1</dim>
<dim>4</dim>
<dim>128</dim>
</port>
<port id="7">
<dim>1</dim>
<dim>1</dim>
<dim>128</dim>
</port>
</output>
</layer>
```

View File

@ -59,24 +59,24 @@ tanh - (e^{2x} - 1)/(e^{2x} + 1)
**Inputs**
* **1**: `X` - 2D tensor of type *T* `[batch_size, input_size]`, input data. Required.
* **1**: `X` - 2D tensor of type *T* `[batch_size, input_size]`, input data. **Required.**
* **2**: `initial_hidden_state` - 2D ([batch_size, hidden_size]) tensor of type *T*. Required.
* **2**: `initial_hidden_state` - 2D tensor of type *T* `[batch_size, hidden_size]`. **Required.**
* **3**: `initial_cell_state` - 2D ([batch_size, hidden_size]) tensor of type *T*. Required.
* **3**: `initial_cell_state` - 2D tensor of type *T* `[batch_size, hidden_size]`. **Required.**
* **4**: `W` - 2D tensor of type *T* `[4 * hidden_size, input_size]`, the weights for matrix multiplication, gate order: fico. Required.
* **4**: `W` - 2D tensor of type *T* `[4 * hidden_size, input_size]`, the weights for matrix multiplication, gate order: fico. **Required.**
* **5**: `R` - 2D tensor of type *T* `[4 * hidden_size, hidden_size]`, the recurrence weights for matrix multiplication, gate order: fico. Required.
* **5**: `R` - 2D tensor of type *T* `[4 * hidden_size, hidden_size]`, the recurrence weights for matrix multiplication, gate order: fico. **Required.**
* **6**: `B` 1D tensor of type *T* `[4 * hidden_size]`, the sum of biases (weights and recurrence weights). Required.
* **6**: `B` 1D tensor of type *T* `[4 * hidden_size]`, the sum of biases (weights and recurrence weights). **Required.**
**Outputs**
* **1**: `Ho` - 2D tensor of type *T* `[batch_size, hidden_size]`, output hidden state, .
* **1**: `Ho` - 2D tensor of type *T* `[batch_size, hidden_size]`, the last output value of hidden state.
* **2**: `Co` - 2D tensor of type *T* `[batch_size, hidden_size]`, output cell state.
* **2**: `Co` - 2D tensor of type *T* `[batch_size, hidden_size]`, the last output value of cell state.
**Types**

View File

@ -55,24 +55,88 @@ A single cell in the sequence is implemented in the same way as in <a href="#LST
**Inputs**
* **1**: `X` - 3D ([batch_size, seq_length, input_size]) input data. It differs from LSTMCell 1st input only by additional axis with size `seq_length`. Floating point type. Required.
* **1**: `X` - 3D tensor of type *T1* `[batch_size, seq_length, input_size]`, input data. It differs from LSTMCell 1st input only by additional axis with size `seq_length`. **Required.**
* **2**: `initial_hidden_state` - 3D ([batch_size, num_directions, hidden_size]) input hidden state data. Floating point type. Required.
* **2**: `initial_hidden_state` - 3D tensor of type *T1* `[batch_size, num_directions, hidden_size]`, input hidden state data. **Required.**
* **3**: `initial_cell_state` - 3D ([batch_size, num_directions, hidden_size]) input cell state data. Floating point type. Required.
* **3**: `initial_cell_state` - 3D tensor of type *T1* `[batch_size, num_directions, hidden_size]`, input cell state data. **Required.**
* **4**: `sequence_lengths` - 1D ([batch_size]) specifies real sequence lengths for each batch element. Integer type. Required.
* **4**: `sequence_lengths` - 1D tensor of type *T2* `[batch_size]`, specifies real sequence lengths for each batch element. **Required.**
* **5**: `W` - 3D tensor with weights for matrix multiplication operation with input portion of data, shape is `[num_directions, 4 * hidden_size, input_size]`, output gate order: fico. Floating point type. Required.
* **5**: `W` - 3D tensor of type *T1* `[num_directions, 4 * hidden_size, input_size]`, the weights for matrix multiplication, gate order: fico. **Required.**
* **6**: `R` - 3D tensor with weights for matrix multiplication operation with hidden state, shape is `[num_directions, 4 * hidden_size, hidden_size]`, output gate order: fico. Floating point type. Required.
* **6**: `R` - 3D tensor of type *T1* `[num_directions, 4 * hidden_size, hidden_size]`, the recurrence weights for matrix multiplication, gate order: fico. **Required.**
* **7**: `B` - 2D tensor with biases, shape is `[num_directions, 4 * hidden_size]`. Floating point type. Required.
* **7**: `B` - 2D tensor of type *T1* `[num_directions, 4 * hidden_size]`, the sum of biases (weights and recurrence weights). **Required.**
**Outputs**
* **1**: `Y` 3D output, shape [batch_size, num_directions, seq_len, hidden_size]
* **1**: `Y` 3D tensor of type *T1* `[batch_size, num_directions, seq_len, hidden_size]`, concatenation of all the intermediate output values of the hidden.
* **2**: `Ho` - 3D ([batch_size, num_directions, hidden_size]) output hidden state.
* **2**: `Ho` - 3D tensor of type *T1* `[batch_size, num_directions, hidden_size]`, the last output value of hidden state.
* **3**: `Co` - 3D ([batch_size, num_directions, hidden_size]) output cell state.
* **3**: `Co` - 3D tensor of type *T1* `[batch_size, num_directions, hidden_size]`, the last output value of cell state.
**Types**
* *T1*: any supported floating point type.
* *T2*: any supported integer type.
**Example**
```xml
<layer ... type="LSTMSequence" ...>
<data hidden_size="128"/>
<input>
<port id="0">
<dim>1</dim>
<dim>4</dim>
<dim>16</dim>
</port>
<port id="1">
<dim>1</dim>
<dim>1</dim>
<dim>128</dim>
</port>
<port id="2">
<dim>1</dim>
<dim>1</dim>
<dim>128</dim>
</port>
<port id="3">
<dim>1</dim>
</port>
<port id="4">
<dim>1</dim>
<dim>512</dim>
<dim>16</dim>
</port>
<port id="5">
<dim>1</dim>
<dim>512</dim>
<dim>128</dim>
</port>
<port id="6">
<dim>1</dim>
<dim>512</dim>
</port>
</input>
<output>
<port id="7">
<dim>1</dim>
<dim>1</dim>
<dim>4</dim>
<dim>128</dim>
</port>
<port id="8">
<dim>1</dim>
<dim>1</dim>
<dim>128</dim>
</port>
<port id="9">
<dim>1</dim>
<dim>1</dim>
<dim>128</dim>
</port>
</output>
</layer>
```

View File

@ -21,7 +21,7 @@
* **Description**: activation functions for gates
* **Range of values**: any combination of *relu*, *sigmoid*, *tanh*
* **Type**: a list of strings
* **Default value**: *sigmoid,tanh*
* **Default value**: *tanh*
* **Required**: *no*
* *activations_alpha, activations_beta*
@ -42,19 +42,19 @@
**Inputs**
* **1**: `X` - 2D tensor of type *T* `[batch_size, input_size]`, input data. Required.
* **1**: `X` - 2D tensor of type *T* `[batch_size, input_size]`, input data. **Required.**
* **2**: `initial_hidden_state` - 2D tensor of type *T* `[batch_size, hidden_size]`. Required.
* **2**: `initial_hidden_state` - 2D tensor of type *T* `[batch_size, hidden_size]`. **Required.**
* **3**: `W` - 2D tensor tensor of type *T* `[hidden_size, input_size]`, the weights for matrix multiplication. Required.
* **3**: `W` - 2D tensor tensor of type *T* `[hidden_size, input_size]`, the weights for matrix multiplication. **Required.**
* **4**: `R` - 2D tensor tensor of type *T* `[hidden_size, hidden_size]`, the recurrence weights for matrix multiplication. Required.
* **4**: `R` - 2D tensor tensor of type *T* `[hidden_size, hidden_size]`, the recurrence weights for matrix multiplication. **Required.**
* **5**: `B` 1D tensor tensor of type *T* `[hidden_size]`, the sum of biases (weights and recurrence weights). Required.
* **5**: `B` 1D tensor tensor of type *T* `[hidden_size]`, the sum of biases (weights and recurrence weights). **Required.**
**Outputs**
* **1**: `Ho` - 2D tensor of type *T* `[batch_size, hidden_size]`, output hidden state.
* **1**: `Ho` - 2D tensor of type *T* `[batch_size, hidden_size]`, the last output value of hidden state.
**Types**

View File

@ -0,0 +1,128 @@
## RNNSequence <a name="RNNSequence"></a> {#openvino_docs_ops_sequence_RNNSequence_4}
**Versioned name**: *RNNSequence-4*
**Category**: *Sequence processing*
**Short description**: *RNNSequence* operation represents a series of RNN cells. Each cell is implemented as <a href="#RNNCell">RNNCell</a> operation.
**Detailed description**
A single cell in the sequence is implemented in the same way as in <a href="#RNNCell">RNNCell</a> operation. *RNNSequence* represents a sequence of RNN cells. The sequence can be connected differently depending on `direction` attribute that specifies the direction of traversing of input data along sequence dimension or specifies whether it should be a bidirectional sequence. The most of the attributes are in sync with the specification of ONNX RNN operator defined <a href="https://github.com/onnx/onnx/blob/master/docs/Operators.md#rnn">RNNCell</a>.
**Attributes**
* *hidden_size*
* **Description**: *hidden_size* specifies hidden state size.
* **Range of values**: a positive integer
* **Type**: `int`
* **Default value**: None
* **Required**: *yes*
* *activations*
* **Description**: activation functions for gates
* **Range of values**: any combination of *relu*, *sigmoid*, *tanh*
* **Type**: a list of strings
* **Default value**: *tanh*
* **Required**: *no*
* *activations_alpha, activations_beta*
* **Description**: *activations_alpha, activations_beta* attributes of functions; applicability and meaning of these attributes depends on choosen activation functions
* **Range of values**: a list of floating-point numbers
* **Type**: `float[]`
* **Default value**: None
* **Required**: *no*
* *clip*
* **Description**: *clip* specifies bound values *[-C, C]* for tensor clipping. Clipping is performed before activations.
* **Range of values**: a positive floating-point number
* **Type**: `float`
* **Default value**: *infinity* that means that the clipping is not applied
* **Required**: *no*
* *direction*
* **Description**: Specify if the RNN is forward, reverse, or bidirectional. If it is one of *forward* or *reverse* then `num_directions = 1`, if it is *bidirectional*, then `num_directions = 2`. This `num_directions` value specifies input/output shape requirements.
* **Range of values**: *forward*, *reverse*, *bidirectional*
* **Type**: `string`
* **Default value**: None
* **Required**: *Yes*
**Inputs**
* **1**: `X` - 3D tensor of type *T1* `[batch_size, seq_length, input_size]`, input data. It differs from RNNCell 1st input only by additional axis with size `seq_length`. **Required.**
* **2**: `initial_hidden_state` - 3D tensor of type *T1* `[batch_size, num_directions, hidden_size]`, input hidden state data. **Required.**
* **3**: `sequence_lengths` - 1D tensor of type *T2* `[batch_size]`, specifies real sequence lengths for each batch element. **Required.**
* **4**: `W` - 3D tensor of type *T1* `[num_directions, hidden_size, input_size]`, the weights for matrix multiplication. **Required.**
* **5**: `R` - 3D tensor of type *T1* `[num_directions, hidden_size, hidden_size]`, the recurrence weights for matrix multiplication. **Required.**
* **6**: `B` - 2D tensor of type *T1* `[num_directions, hidden_size]`, the sum of biases (weights and recurrence weights). **Required.**
**Outputs**
* **1**: `Y` 3D tensor of type *T1* `[batch_size, num_directions, seq_len, hidden_size]`, concatenation of all the intermediate output values of the hidden.
* **2**: `Ho` - 3D tensor of type *T1* `[batch_size, num_directions, hidden_size]`, the last output value of hidden state.
**Types**
* *T1*: any supported floating point type.
* *T2*: any supported integer type.
**Example**
```xml
<layer ... type="RNNSequence" ...>
<data hidden_size="128"/>
<input>
<port id="0">
<dim>1</dim>
<dim>4</dim>
<dim>16</dim>
</port>
<port id="1">
<dim>1</dim>
<dim>1</dim>
<dim>128</dim>
</port>
<port id="2">
<dim>1</dim>
</port>
<port id="3">
<dim>1</dim>
<dim>128</dim>
<dim>16</dim>
</port>
<port id="4">
<dim>1</dim>
<dim>128</dim>
<dim>128</dim>
</port>
<port id="5">
<dim>1</dim>
<dim>128</dim>
</port>
</input>
<output>
<port id="6">
<dim>1</dim>
<dim>1</dim>
<dim>4</dim>
<dim>128</dim>
</port>
<port id="7">
<dim>1</dim>
<dim>1</dim>
<dim>128</dim>
</port>
</output>
</layer>
```