FillEmptyRows-16 operator specification

docs/articles_en/documentation/openvino-ir-format/operation-sets/operation-specs/sparse/fill-empty-rows-16.rst

@@ -0,0 +1,107 @@
+FillEmptyRows
+======================
+
+
+.. meta::
+  :description: Learn about FillEmptyRows-16 - a sparse operation, which
+                can be performed on four required input tensors.
+
+**Versioned name**: *FillEmptyRows-16*
+
+**Category**: *Sparse*
+
+**Short description**: Fills empty rows of an input sparse tensor with a default value.
+
+**Detailed description**:
+
+Operation FillEmptyRows is an implementation of ``tf.sparse.fill_empty_rows``.
+
+The input sparse tensor is represented by the three inputs: 
+
+* ``indices``
+* ``values``
+* ``dense_shape``
+
+For each row in the input sparse tensor, this operator checks if the row is empty. If the row is empty, the operator adds an entry with the specified default value at index `[row, 0, ..., 0]`. The input may have empty columns at the end, which will not be affected by this operation.
+
+The output sparse tensor will be in row-major order and will have the same shape as the input, but with updated `output_indices` and `output_values`.
+
+This operator also returns a boolean vector indicating which rows were filled with the default value: ``empty_row_indicator[i] = True`` if row ``i`` was an empty row.
+
+**Attributes**: FillEmptyRows-16 operation has no attributes.
+
+**Inputs**:
+
+* **1**: ``default_value`` a scalar of type *T* to be inserted into the empty rows. **Required.**
+* **2**: ``values`` 1D tensor containing the values of type *T* to be inserted at the specified indices. **Required.**
+* **3**: ``dense_shape`` 1D tensor of type *T_IDX* indicating the shape of the dense tensor. **Required.**
+* **4**: ``indices`` 2D tensor of type *T_IDX* indicating the positions at which ``values`` are placed in the sparse tensor. **Required.**
+    It is of shape ``[M, N]``, where:
+
+    * ``M`` is the same as the length of the ``values`` input.
+    * ``N`` is equal to the rank of ``dense_shape``.
+
+**Outputs**:
+
+* **1**: ``output_indices`` 2D tensor of type *T_IDX* indicating the positions at which ``output_values`` are placed in the sparse tensor.
+    It is of shape ``[M', N]``, where:
+
+    * ``M'`` is the length of the updated ``output_values``.
+    * ``N`` is equal to the rank of ``dense_shape``.
+* **2**: ``output_values`` 1D tensor containing the values of type *T* to be inserted at the specified indices.
+* **3**: ``empty_row_indicator`` 1D tensor of type ``boolean`` indicating True for rows which were empty before executing the operation.
+
+**Types**
+
+* *T*: any numeric type.
+* *T_IDX*: ``int32`` or ``int64``.
+
+**Example**
+
+*Example 1: sparse tensor input with shape [5, 6].*
+
+Input sparse tensor:
+
+* ``indices = [[0, 1], [0, 3], [2, 0], [3, 1]]``
+* ``values = [a, b, c, d]``
+* ``dense_shape = [5, 6]``
+
+Rows 1 and 4 are empty. The output sparse tensor will be:
+
+* ``output_indices = [[0, 1], [0, 3], [1, 0], [2, 0], [3, 1], [4, 0]]``
+* ``output_values = [a, b, default_value, c, d, default_value]``
+* ``empty_row_indicator = [False, True, False, False, True]``
+
+The output sparse tensor will be in row-major order and will have the same shape as the input.
+
+.. code-block:: xml
+
+    <layer ... type="FillEmptyRows" ... >
+        <input>
+            <port id="0" precision="FP32">      <!-- default_value is: 42 -->
+                <dim>0</dim>
+            </port>
+            <port id="1" precision="FP32">      <!-- values are: [1, 3] -->
+                <dim>2</dim>
+            </port>
+            <port id="2" precision="I32">       <!-- dense_shape value is: [3, 3] -->
+                <dim>2</dim>
+            </port>
+            <port id="3" precision="I32">       <!-- indices value is: [[0, 0], [2, 2]] -->
+                <dim>2</dim>
+                <dim>2</dim>
+            </port>
+        </input>
+        <output>
+            <port id="4" precision="I32">       <!-- output_indices -->
+                <dim>3</dim>
+                <dim>2</dim>
+            </port>
+            <port id="5" precision="FP32">      <!-- output_values -->
+                <dim>3</dim>
+            </port>
+            <port id="6" precision="BOOL">      <!-- empty_row_indicator -->
+                <dim>3</dim>
+            </port>
+        </output>
+    </layer>