[Spec][Opset13] BitwiseAnd-13, BitwiseNot-13, BitwiseOr-13, BitwiseXor-13 specifications (#19798)

* [Spec] BitwiseNot-13 specification * Improvements * add other specifications * Doc improvements * Fix typos * add opset13 * Fix typo * add opset13 * Fix * Improve example? * Fix step formatting * Apply suggestions from code review Co-authored-by: Katarzyna Mitrus <katarzyna.mitrus@intel.com> * Add suggested changes * Fix missing the --------- Co-authored-by: Katarzyna Mitrus <katarzyna.mitrus@intel.com>
2023-09-22 13:14:46 +02:00 · 2023-09-22 13:14:46 +02:00 · 7a2ac27f09
commit 7a2ac27f09
parent fb41324141
6 changed files with 505 additions and 0 deletions
--- a/docs/OV_Runtime_UG/Operations_specifications.md
+++ b/docs/OV_Runtime_UG/Operations_specifications.md
@ -24,6 +24,10 @@
   BatchNormInference-5 <openvino_docs_ops_normalization_BatchNormInference_5>
   BatchToSpace-2 <openvino_docs_ops_movement_BatchToSpace_2>
   BinaryConvolution-1 <openvino_docs_ops_convolution_BinaryConvolution_1>
+   BitwiseAnd-13 <openvino_docs_ops_bitwise_BitwiseAnd_13>
+   BitwiseNot-13 <openvino_docs_ops_bitwise_BitwiseNot_13>
+   BitwiseOr-13 <openvino_docs_ops_bitwise_BitwiseOr_13>
+   BitwiseXor-13 <openvino_docs_ops_bitwise_BitwiseXor_13>
   Broadcast-1 <openvino_docs_ops_movement_Broadcast_1>
   Broadcast-3 <openvino_docs_ops_movement_Broadcast_3>
   Bucketize-3 <openvino_docs_ops_condition_Bucketize_3>
--- a/docs/ops/bitwise/BitwiseAnd_13.md
+++ b/docs/ops/bitwise/BitwiseAnd_13.md
@ -0,0 +1,138 @@
+# BitwiseAnd {#openvino_docs_ops_bitwise_BitwiseAnd_13}
+
+@sphinxdirective
+
+.. meta::
+  :description: Learn about BitwiseAnd-13 - an element-wise, bitwise AND operation, which can be performed on two required input tensors.
+
+**Versioned name**: *BitwiseAnd-13*
+
+**Category**: *Bitwise binary*
+
+**Short description**: *BitwiseAnd* performs a bitwise logical AND operation with two given tensors element-wise, applying multi-directional broadcast rules.
+
+**Detailed description**: Before performing the operation, input tensors *a* and *b* are broadcasted if their shapes are different and the ``auto_broadcast`` attribute is not ``none``. Broadcasting is performed according to the ``auto_broadcast`` value.
+
+After broadcasting input tensors *a* and *b*, *BitwiseAnd* performs a bitwise logical AND operation for each corresponding element in the given tensors, based on the following algorithm.
+
+For ``boolean`` type tensors, BitwiseAnd is equivalent to :doc:`LogicalAnd <openvino_docs_ops_logical_LogicalAnd_1>`.
+
+If tensor is of ``any supported integer`` type, for each element of the tensor:
+
+1.  Convert values from input tensors to their binary representation according to the input tensor datatype.
+2.  Perform a logical AND on each bit in the binary representation of values from *a* and *b*, where value ``0`` represents ``false`` and value ``1`` represents ``true``.
+3.  Convert the results of AND in binary representation to the input datatype.
+
+Example 1 - *BitwiseAnd* output for boolean tensor:
+
+.. code-block:: py
+    :force:
+
+    # For given boolean inputs:
+    a = [True, False, False]
+    b = [True, True, False]
+    # Perform logical AND operation same as in LogicalAnd operator:
+    output = [True, False, False]
+
+Example 2 - *BitwiseAnd* output for uint8 tensor:
+
+.. code-block:: py
+    :force:
+
+    # For given uint8 inputs:
+    a = [21, 120]
+    b = [3, 37]
+    # Create a binary representation of uint8:
+    # binary a: [00010101, 01111000]
+    # binary b: [00000011, 00100101]
+    # Perform bitwise AND of corresponding elements in a and b:
+    # [00000001, 00100000]
+    # Convert binary values to uint8:
+    output = [1, 32]
+
+**Attributes**:
+
+* *auto_broadcast*
+
+  * **Description**: specifies the rules used for auto-broadcasting of input tensors.
+  * **Range of values**:
+
+    * *none* - no auto-broadcasting is allowed, all input shapes must match,
+    * *numpy* - numpy broadcasting rules, description is available in :doc:`Broadcast Rules For Elementwise Operations <openvino_docs_ops_broadcast_rules>`,
+    * *pdpd* - PaddlePaddle-style implicit broadcasting, description is available in :doc:`Broadcast Rules For Elementwise Operations <openvino_docs_ops_broadcast_rules>`.
+
+  * **Type**: string
+  * **Default value**: "numpy"
+  * **Required**: *no*
+
+**Inputs**
+
+* **1**: A tensor of type *T* and arbitrary shape. **Required.**
+* **2**: A tensor of type *T* and arbitrary shape. **Required.**
+
+**Outputs**
+
+* **1**: The result of element-wise *BitwiseAnd* operation. A tensor of type *T* and the same shape equal to the broadcasted shape of two inputs.
+
+**Types**
+
+* *T*: ``any supported integer or boolean type``.
+
+**Examples**
+
+*Example 1: no broadcast*
+
+.. code-block:: xml
+    :force:
+
+    <layer ... type="BitwiseAnd">
+        <input>
+            <port id="0">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+            <port id="1">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+        </input>
+        <output>
+            <port id="2">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+        </output>
+    </layer>
+
+
+*Example 2: numpy broadcast*
+
+.. code-block:: xml
+    :force:
+
+    <layer ... type="BitwiseAnd">
+        <input>
+            <port id="0">
+                <dim>8</dim>
+                <dim>1</dim>
+                <dim>6</dim>
+                <dim>1</dim>
+            </port>
+            <port id="1">
+                <dim>7</dim>
+                <dim>1</dim>
+                <dim>5</dim>
+            </port>
+        </input>
+        <output>
+            <port id="2">
+                <dim>8</dim>
+                <dim>7</dim>
+                <dim>6</dim>
+                <dim>5</dim>
+            </port>
+        </output>
+    </layer>
+
+
+@endsphinxdirective
--- a/docs/ops/bitwise/BitwiseNot_13.md
+++ b/docs/ops/bitwise/BitwiseNot_13.md
@ -0,0 +1,83 @@
+# BitwiseNot {#openvino_docs_ops_bitwise_BitwiseNot_13}
+
+@sphinxdirective
+
+.. meta::
+  :description: Learn about BitwiseNot-13 - an element-wise, bitwise negation operation, which can be performed on a single input tensor.
+
+**Versioned name**: *BitwiseNot-13*
+
+**Category**: *Bitwise unary*
+
+**Short description**: *BitwiseNot* performs a bitwise logical negation operation with given tensor element-wise.
+
+**Detailed description**: *BitwiseNot* performs a bitwise logical negation operation for each element in the given tensor, based on the following algorithm.
+
+For ``boolean`` type tensors, BitwiseNot is equivalent to :doc:`LogicalNot <openvino_docs_ops_logical_LogicalNot_1>`.
+
+If tensor is of ``any supported integer`` type, for each element of the tensor:
+
+1.  Convert the value from the input tensor to binary representation according to the input tensor datatype.
+2.  Perform a logical negation on each bit in the binary representation, where value ``0`` represents ``false`` and value ``1`` represents ``true``.
+3.  Convert back the binary representation to the input datatype.
+
+Example 1 - *BitwiseNot* output for boolean tensor:
+
+.. code-block:: py
+    :force:
+
+    # For given boolean input:
+    input = [True, False]
+    # Perform logical negation operation same as in LogicalNot operator:
+    output = [False, True]
+
+Example 2 - *BitwiseNot* output for uint8 tensor:
+
+.. code-block:: py
+    :force:
+
+    # For given uint8 input:
+    input = [1, 3]
+    # Create a binary representation of uint8:
+    # [00000001, 00000011]
+    # Perform bitwise negation:
+    # [11111110, 11111100]
+    # Convert back binary values to uint8:
+    output = [254, 252]
+
+**Attributes**: *BitwiseNot* operation has no attributes.
+
+**Inputs**
+
+* **1**: A tensor of type *T* and arbitrary shape. **Required.**
+
+**Outputs**
+
+* **1**: The result of bitwise logical negation operation. A tensor of type *T* and the same shape as the input tensor.
+
+**Types**
+
+* *T*: ``any supported integer or boolean type``.
+
+**Example**
+
+.. code-block:: xml
+    :force:
+
+    <layer ... type="BitwiseNot">
+        <input>
+            <port id="0">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+        </input>
+        <output>
+            <port id="1">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+        </output>
+    </layer>
+
+
+@endsphinxdirective
--- a/docs/ops/bitwise/BitwiseOr_13.md
+++ b/docs/ops/bitwise/BitwiseOr_13.md
@ -0,0 +1,138 @@
+# BitwiseOr {#openvino_docs_ops_bitwise_BitwiseOr_13}
+
+@sphinxdirective
+
+.. meta::
+  :description: Learn about BitwiseOr-13 - an element-wise, bitwise OR operation, which can be performed on two required input tensors.
+
+**Versioned name**: *BitwiseOr-13*
+
+**Category**: *Bitwise binary*
+
+**Short description**: *BitwiseOr* performs a bitwise logical OR operation with two given tensors element-wise, applying multi-directional broadcast rules.
+
+**Detailed description**: Before performing the operation, input tensors *a* and *b* are broadcasted if their shapes are different and the ``auto_broadcast`` attribute is not ``none``. Broadcasting is performed according to the ``auto_broadcast`` value.
+
+After broadcasting input tensors *a* and *b*, *BitwiseOr* performs a bitwise logical OR operation for each corresponding element in the given tensors, based on the following algorithm.
+
+For ``boolean`` type tensors, BitwiseOr is equivalent to :doc:`LogicalOr <openvino_docs_ops_logical_LogicalOr_1>`.
+
+If tensor is of ``any supported integer`` type, for each element of the tensor:
+
+1.  Convert values from input tensors to their binary representation according to the input tensor datatype.
+2.  Perform a logical OR on each bit in the binary representation of values from *a* and *b*, where value ``0`` represents ``false`` and value ``1`` represents ``true``.
+3.  Convert the results of OR in binary representation to the input datatype.
+
+Example 1 - *BitwiseOr* output for boolean tensor:
+
+.. code-block:: py
+    :force:
+
+    # For given boolean inputs:
+    a = [True, False, False]
+    b = [True, True, False]
+    # Perform logical OR operation same as in LogicalOr operator:
+    output = [True, True, False]
+
+Example 2 - *BitwiseOr* output for uint8 tensor:
+
+.. code-block:: py
+    :force:
+
+    # For given uint8 inputs:
+    a = [21, 120]
+    b = [3, 37]
+    # Create a binary representation of uint8:
+    # binary a: [00010101, 01111000]
+    # binary b: [00000011, 00100101]
+    # Perform bitwise OR of corresponding elements in a and b:
+    # [00010111, 01111101]
+    # Convert binary values to uint8:
+    output = [23, 125]
+
+**Attributes**:
+
+* *auto_broadcast*
+
+  * **Description**: specifies the rules used for auto-broadcasting of input tensors.
+  * **Range of values**:
+
+    * *none* - no auto-broadcasting is allowed, all input shapes must match,
+    * *numpy* - numpy broadcasting rules, description is available in :doc:`Broadcast Rules For Elementwise Operations <openvino_docs_ops_broadcast_rules>`,
+    * *pdpd* - PaddlePaddle-style implicit broadcasting, description is available in :doc:`Broadcast Rules For Elementwise Operations <openvino_docs_ops_broadcast_rules>`.
+
+  * **Type**: string
+  * **Default value**: "numpy"
+  * **Required**: *no*
+
+**Inputs**
+
+* **1**: A tensor of type *T* and arbitrary shape. **Required.**
+* **2**: A tensor of type *T* and arbitrary shape. **Required.**
+
+**Outputs**
+
+* **1**: The result of element-wise *BitwiseOr* operation. A tensor of type *T* and the same shape equal to the broadcasted shape of two inputs.
+
+**Types**
+
+* *T*: ``any supported integer or boolean type``.
+
+**Examples**
+
+*Example 1: no broadcast*
+
+.. code-block:: xml
+    :force:
+
+    <layer ... type="BitwiseOr">
+        <input>
+            <port id="0">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+            <port id="1">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+        </input>
+        <output>
+            <port id="2">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+        </output>
+    </layer>
+
+
+*Example 2: numpy broadcast*
+
+.. code-block:: xml
+    :force:
+
+    <layer ... type="BitwiseOr">
+        <input>
+            <port id="0">
+                <dim>8</dim>
+                <dim>1</dim>
+                <dim>6</dim>
+                <dim>1</dim>
+            </port>
+            <port id="1">
+                <dim>7</dim>
+                <dim>1</dim>
+                <dim>5</dim>
+            </port>
+        </input>
+        <output>
+            <port id="2">
+                <dim>8</dim>
+                <dim>7</dim>
+                <dim>6</dim>
+                <dim>5</dim>
+            </port>
+        </output>
+    </layer>
+
+
+@endsphinxdirective
--- a/docs/ops/bitwise/BitwiseXor_13.md
+++ b/docs/ops/bitwise/BitwiseXor_13.md
@ -0,0 +1,138 @@
+# BitwiseXor {#openvino_docs_ops_bitwise_BitwiseXor_13}
+
+@sphinxdirective
+
+.. meta::
+  :description: Learn about BitwiseXor-13 - an element-wise, bitwise XOR operation, which can be performed on two required input tensors.
+
+**Versioned name**: *BitwiseXor-13*
+
+**Category**: *Bitwise binary*
+
+**Short description**: *BitwiseXor* performs a bitwise logical XOR operation with two given tensors element-wise, applying multi-directional broadcast rules.
+
+**Detailed description**: Before performing the operation, input tensors *a* and *b* are broadcasted if their shapes are different and the ``auto_broadcast`` attribute is not ``none``. Broadcasting is performed according to the ``auto_broadcast`` value.
+
+After broadcasting input tensors *a* and *b*, *BitwiseXor* performs a bitwise logical XOR operation for each corresponding element in the given tensors, based on the following algorithm.
+
+For ``boolean`` type tensors, BitwiseXor is equivalent to :doc:`LogicalXor <openvino_docs_ops_logical_LogicalXor_1>`.
+
+If tensor is of ``any supported integer`` type, for each element of the tensor:
+
+1.  Convert values from input tensors to their binary representation according to the input tensor datatype.
+2.  Perform a logical XOR on each bit in the binary representation of values from *a* and *b*, where value ``0`` represents ``false`` and value ``1`` represents ``true``.
+3.  Convert the results of XOR in binary representation to the input datatype.
+
+Example 1 - *BitwiseXor* output for boolean tensor:
+
+.. code-block:: py
+    :force:
+
+    # For given boolean inputs:
+    a = [True, False, False]
+    b = [True, True, False]
+    # Perform logical XOR operation same as in LogicalXor operator:
+    output = [False, True, False]
+
+Example 2 - *BitwiseXor* output for uint8 tensor:
+
+.. code-block:: py
+    :force:
+
+    # For given uint8 inputs:
+    a = [21, 120]
+    b = [3, 37]
+    # Create a binary representation of uint8:
+    # binary a: [00010101, 01111000]
+    # binary b: [00000011, 00100101]
+    # Perform bitwise XOR of corresponding elements in a and b:
+    # [00010110, 01011101]
+    # Convert binary values to uint8:
+    output = [22, 93]
+
+**Attributes**:
+
+* *auto_broadcast*
+
+  * **Description**: specifies the rules used for auto-broadcasting of input tensors.
+  * **Range of values**:
+
+    * *none* - no auto-broadcasting is allowed, all input shapes must match,
+    * *numpy* - numpy broadcasting rules, description is available in :doc:`Broadcast Rules For Elementwise Operations <openvino_docs_ops_broadcast_rules>`,
+    * *pdpd* - PaddlePaddle-style implicit broadcasting, description is available in :doc:`Broadcast Rules For Elementwise Operations <openvino_docs_ops_broadcast_rules>`.
+
+  * **Type**: string
+  * **Default value**: "numpy"
+  * **Required**: *no*
+
+**Inputs**
+
+* **1**: A tensor of type *T* and arbitrary shape. **Required.**
+* **2**: A tensor of type *T* and arbitrary shape. **Required.**
+
+**Outputs**
+
+* **1**: The result of element-wise *BitwiseXor* operation. A tensor of type *T* and the same shape equal to the broadcasted shape of two inputs.
+
+**Types**
+
+* *T*: ``any supported integer or boolean type``.
+
+**Examples**
+
+*Example 1: no broadcast*
+
+.. code-block:: xml
+    :force:
+
+    <layer ... type="BitwiseXor">
+        <input>
+            <port id="0">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+            <port id="1">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+        </input>
+        <output>
+            <port id="2">
+                <dim>256</dim>
+                <dim>56</dim>
+            </port>
+        </output>
+    </layer>
+
+
+*Example 2: numpy broadcast*
+
+.. code-block:: xml
+    :force:
+
+    <layer ... type="BitwiseXor">
+        <input>
+            <port id="0">
+                <dim>8</dim>
+                <dim>1</dim>
+                <dim>6</dim>
+                <dim>1</dim>
+            </port>
+            <port id="1">
+                <dim>7</dim>
+                <dim>1</dim>
+                <dim>5</dim>
+            </port>
+        </input>
+        <output>
+            <port id="2">
+                <dim>8</dim>
+                <dim>7</dim>
+                <dim>6</dim>
+                <dim>5</dim>
+            </port>
+        </output>
+    </layer>
+
+
+@endsphinxdirective
--- a/docs/ops/opset13.md
+++ b/docs/ops/opset13.md
@ -32,6 +32,10 @@ Table of Contents
 * :doc:`BatchNormInference <openvino_docs_ops_normalization_BatchNormInference_5>`
 * :doc:`BatchToSpace <openvino_docs_ops_movement_BatchToSpace_2>`
 * :doc:`BinaryConvolution <openvino_docs_ops_convolution_BinaryConvolution_1>`
+* :doc:`BitwiseAnd <openvino_docs_ops_bitwise_BitwiseAnd_13>`
+* :doc:`BitwiseOr <openvino_docs_ops_bitwise_BitwiseOr_13>`
+* :doc:`BitwiseXor <openvino_docs_ops_bitwise_BitwiseXor_13>`
+* :doc:`BitwiseNot <openvino_docs_ops_bitwise_BitwiseNot_13>`
 * :doc:`Broadcast <openvino_docs_ops_movement_Broadcast_3>`
 * :doc:`Bucketize <openvino_docs_ops_condition_Bucketize_3>`
 * :doc:`CTCGreedyDecoder <openvino_docs_ops_sequence_CTCGreedyDecoder_1>`