DOCS shift to rst - Troubleshooting Reshape and NoDynamicShapes (#16304)

docs/MO_DG/prepare_model/convert_model/Converting_Model.md

@@ -64,9 +64,15 @@ For example, launch Model Optimizer for the ONNX OCR model and specify a boundar
 mo --input_model ocr.onnx --input data,seq_len --input_shape [1..3,150,200,1],[1..3]
 ```
 
+@sphinxdirective
+
 Practically, some models are not ready for input shapes change.
 In this case, a new input shape cannot be set via Model Optimizer.
-For more information about shape follow the [inference troubleshooting](@ref troubleshooting_reshape_errors) and [ways to relax shape inference flow](@ref how-to-fix-non-reshape-able-model) guides. 
+For more information about shape follow the :doc:`inference troubleshooting <troubleshooting_reshape_errors>` 
+and :ref:`ways to relax shape inference flow <how-to-fix-non-reshape-able-model>` guides.
+
+@endsphinxdirective
+
 
 ## Specifying --static_shape Command-line Parameter
 Model Optimizer provides the `--static_shape` parameter that allows evaluating shapes of all operations in the model for fixed input shapes

docs/MO_DG/prepare_model/convert_model/tf_specific/Convert_Object_Detection_API_Models.md

@@ -12,39 +12,46 @@ You can download TensorFlow Object Detection API models from the <a href="https:
 
 > **NOTE**: Before converting, make sure you have configured Model Optimizer. For configuration steps, refer to the [Configuring Model Optimizer](../../../Deep_Learning_Model_Optimizer_DevGuide.md).
 
-To convert a TensorFlow Object Detection API model, run the `mo` command with the following required parameters:
+@sphinxdirective
+
+To convert a TensorFlow Object Detection API model, run the ``mo`` command with the following required parameters:
+
+* ``--input_model <path_to_frozen.pb>`` - File with a pretrained model (binary or text .pb file after freezing) OR ``--saved_model_dir <path_to_saved_model>`` for the TensorFlow 2 models
+* ``--transformations_config <path_to_subgraph_replacement_configuration_file.json>`` - A subgraph replacement configuration file with transformations description. For the models downloaded from the TensorFlow Object Detection API zoo, you can find the configuration files in the ``<PYTHON_SITE_PACKAGES>/openvino/tools/mo/front/tf`` directory. Use:
+
+  * ``ssd_v2_support.json`` - for frozen SSD topologies from the models zoo version up to 1.13.X inclusively
+  * ``ssd_support_api_v.1.14.json`` - for SSD topologies trained using the TensorFlow Object Detection API version 1.14 up to 1.14.X inclusively
+  * ``ssd_support_api_v.1.15.json`` - for SSD topologies trained using the TensorFlow Object Detection API version 1.15 up to 2.0
+  * ``ssd_support_api_v.2.0.json`` - for SSD topologies trained using the TensorFlow Object Detection API version 2.0 up to 2.3.X inclusively
+  * ``ssd_support_api_v.2.4.json`` - for SSD topologies trained using the TensorFlow Object Detection API version 2.4 or higher
+  * ``efficient_det_support_api_v.2.0.json`` - for EfficientDet topologies trained using the TensorFlow Object Detection API version 2.0 up to 2.3.X inclusively
+  * ``efficient_det_support_api_v.2.4.json`` - for EfficientDet topologies trained using the TensorFlow Object Detection API version 2.4 or higher
+  * ``faster_rcnn_support.json`` - for Faster R-CNN topologies from the TF 1.X models zoo trained with TensorFlow version up to 1.6.X inclusively
+  * ``faster_rcnn_support_api_v1.7.json`` - for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 1.7.0 up to 1.9.X inclusively
+  * ``faster_rcnn_support_api_v1.10.json`` - for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 1.10.0 up to 1.12.X inclusively
+  * ``faster_rcnn_support_api_v1.13.json`` - for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 1.13.X
+  * ``faster_rcnn_support_api_v1.14.json`` - for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 1.14.0 up to 1.14.X inclusively
+  * ``faster_rcnn_support_api_v1.15.json`` - for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 1.15.0 up to 2.0
+  * ``faster_rcnn_support_api_v2.0.json`` - for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 2.0 up to 2.3.X inclusively
+  * ``faster_rcnn_support_api_v2.4.json`` - for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 2.4 or higher
+  * ``mask_rcnn_support.json`` - for Mask R-CNN topologies from the TF 1.X models zoo trained with TensorFlow version 1.9.0 or lower.
+  * ``mask_rcnn_support_api_v1.7.json`` - for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 1.7.0 up to 1.9.X inclusively
+  * ``mask_rcnn_support_api_v1.11.json`` - for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 1.11.0 up to 1.12.X inclusively
+  * ``mask_rcnn_support_api_v1.13.json`` - for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 1.13.0 up to 1.13.X inclusively
+  * ``mask_rcnn_support_api_v1.14.json`` - for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 1.14.0 up to 1.14.X inclusively
+  * ``mask_rcnn_support_api_v1.15.json`` - for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 1.15.0 up to 2.0
+  * ``mask_rcnn_support_api_v2.0.json`` - for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 2.0 up to 2.3.X inclusively
+  * ``mask_rcnn_support_api_v2.4.json`` - for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 2.4 or higher
+  * ``rfcn_support.json`` - for RFCN topology from the models zoo trained with TensorFlow version up to 1.9.X inclusively
+  * ``rfcn_support_api_v1.10.json`` - for RFCN topology from the models zoo frozen with TensorFlow version 1.10.0 up to 1.12.X inclusively
+  * ``rfcn_support_api_v1.13.json`` - for RFCN topology from the models zoo frozen with TensorFlow version 1.13.X
+  * ``rfcn_support_api_v1.14.json`` - for RFCN topology from the models zoo frozen with TensorFlow version 1.14.0 or higher
+
+* ``--tensorflow_object_detection_api_pipeline_config <path_to_pipeline.config>`` - A special configuration file that describes the topology hyper-parameters and structure of the TensorFlow Object Detection API model. For the models downloaded from the TensorFlow Object Detection API zoo, the configuration file is named ``pipeline.config``. If you plan to train a model yourself, you can find templates for these files in the `models repository <https://github.com/tensorflow/models/tree/master/research/object_detection/samples/configs>`__.
+* ``--input_shape`` (optional) - A custom input image shape. For more information how the ``--input_shape`` parameter is handled for the TensorFlow Object Detection API models, refer to the :ref:`Custom Input Shape <custom-input-shape>` guide.
+
+@endsphinxdirective
 
-* `--input_model <path_to_frozen.pb>` --- File with a pretrained model (binary or text .pb file after freezing) OR `--saved_model_dir <path_to_saved_model>` for the TensorFlow 2 models
-* `--transformations_config <path_to_subgraph_replacement_configuration_file.json>` --- A subgraph replacement configuration file with transformations description. For the models downloaded from the TensorFlow Object Detection API zoo, you can find the configuration files in the `<PYTHON_SITE_PACKAGES>/openvino/tools/mo/front/tf` directory. Use:
-    * `ssd_v2_support.json` --- for frozen SSD topologies from the models zoo version up to 1.13.X inclusively
-    * `ssd_support_api_v.1.14.json` --- for SSD topologies trained using the TensorFlow Object Detection API version 1.14 up to 1.14.X inclusively
-    * `ssd_support_api_v.1.15.json` --- for SSD topologies trained using the TensorFlow Object Detection API version 1.15 up to 2.0
-    * `ssd_support_api_v.2.0.json` --- for SSD topologies trained using the TensorFlow Object Detection API version 2.0 up to 2.3.X inclusively
-    * `ssd_support_api_v.2.4.json` --- for SSD topologies trained using the TensorFlow Object Detection API version 2.4 or higher
-    * `efficient_det_support_api_v.2.0.json` --- for EfficientDet topologies trained using the TensorFlow Object Detection API version 2.0 up to 2.3.X inclusively
-    * `efficient_det_support_api_v.2.4.json` --- for EfficientDet topologies trained using the TensorFlow Object Detection API version 2.4 or higher
-    * `faster_rcnn_support.json` --- for Faster R-CNN topologies from the TF 1.X models zoo trained with TensorFlow version up to 1.6.X inclusively
-    * `faster_rcnn_support_api_v1.7.json` --- for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 1.7.0 up to 1.9.X inclusively
-    * `faster_rcnn_support_api_v1.10.json` --- for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 1.10.0 up to 1.12.X inclusively
-    * `faster_rcnn_support_api_v1.13.json` --- for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 1.13.X
-    * `faster_rcnn_support_api_v1.14.json` --- for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 1.14.0 up to 1.14.X inclusively
-    * `faster_rcnn_support_api_v1.15.json` --- for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 1.15.0 up to 2.0
-    * `faster_rcnn_support_api_v2.0.json` --- for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 2.0 up to 2.3.X inclusively
-    * `faster_rcnn_support_api_v2.4.json` --- for Faster R-CNN topologies trained using the TensorFlow Object Detection API version 2.4 or higher
-    * `mask_rcnn_support.json` --- for Mask R-CNN topologies from the TF 1.X models zoo trained with TensorFlow version 1.9.0 or lower.
-    * `mask_rcnn_support_api_v1.7.json` --- for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 1.7.0 up to 1.9.X inclusively
-    * `mask_rcnn_support_api_v1.11.json` --- for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 1.11.0 up to 1.12.X inclusively
-    * `mask_rcnn_support_api_v1.13.json` --- for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 1.13.0 up to 1.13.X inclusively
-    * `mask_rcnn_support_api_v1.14.json` --- for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 1.14.0 up to 1.14.X inclusively
-    * `mask_rcnn_support_api_v1.15.json` --- for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 1.15.0 up to 2.0
-    * `mask_rcnn_support_api_v2.0.json` --- for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 2.0 up to 2.3.X inclusively
-    * `mask_rcnn_support_api_v2.4.json` --- for Mask R-CNN topologies trained using the TensorFlow Object Detection API version 2.4 or higher
-    * `rfcn_support.json` --- for RFCN topology from the models zoo trained with TensorFlow version up to 1.9.X inclusively
-    * `rfcn_support_api_v1.10.json` --- for RFCN topology from the models zoo frozen with TensorFlow version 1.10.0 up to 1.12.X inclusively
-    * `rfcn_support_api_v1.13.json` --- for RFCN topology from the models zoo frozen with TensorFlow version 1.13.X
-    * `rfcn_support_api_v1.14.json` --- for RFCN topology from the models zoo frozen with TensorFlow version 1.14.0 or higher
-* `--tensorflow_object_detection_api_pipeline_config <path_to_pipeline.config>` --- A special configuration file that describes the topology hyper-parameters and structure of the TensorFlow Object Detection API model. For the models downloaded from the TensorFlow Object Detection API zoo, the configuration file is named `pipeline.config`. If you plan to train a model yourself, you can find templates for these files in the [models repository](https://github.com/tensorflow/models/tree/master/research/object_detection/samples/configs).
-* `--input_shape` (optional) --- A custom input image shape. For more information how the `--input_shape` parameter is handled for the TensorFlow Object Detection API models, refer to the [Custom Input Shape](#custom-input-shape) guide.
 
 > **NOTE**: The color channel order (RGB or BGR) of an input data should match the channel order of the model training dataset. If they are different, perform the `RGB<->BGR` conversion specifying the command-line parameter: `--reverse_input_channels`. Otherwise, inference results may be incorrect. If you convert a TensorFlow Object Detection API model to use with the OpenVINO sample applications, you must specify the `--reverse_input_channels` parameter. For more information about the parameter, refer to the **When to Reverse Input Channels** section of the [Converting a Model to Intermediate Representation (IR)](../Converting_Model.md) guide.
 
@@ -78,7 +85,13 @@ There are several important notes about feeding input images to the samples:
 
 4. Read carefully the messages printed by Model Optimizer during a model conversion. They contain important instructions on how to prepare input data before running the inference and how to interpret the output.
 
-@anchor custom-input-shape
+@sphinxdirective
+
+.. _custom-input-shape:
+
+@endsphinxdirective
+
+
 ## Custom Input Shape
 Model Optimizer handles the command line parameter `--input_shape` for TensorFlow Object Detection API models in a special way depending on the image resizer type defined in the `pipeline.config` file. TensorFlow Object Detection API generates different `Preprocessor` sub-graph based on the image resizer type. Model Optimizer supports two types of image resizer:
 * `fixed_shape_resizer` --- *Stretches* input image to the specific height and width. The `pipeline.config` snippet below shows a `fixed_shape_resizer` sample definition:

docs/OV_Runtime_UG/Troubleshooting_ReshapeMethod.md

@@ -1,45 +1,45 @@
 # Troubleshooting Reshape Errors {#troubleshooting_reshape_errors}
 
-### How To Avoid Shape Collision
+@sphinxdirective
+
+How To Avoid Shape Collision
+############################
 
 Operation semantics may impose restrictions on input shapes of the operation.
 Shape collision during shape propagation may be a sign that new shape does not satisfy the restrictions.
 Changing the model input shape may result in intermediate operations shape collision. For example, in the following:
 
-* The [Reshape](@ref openvino_docs_ops_shape_Reshape_1) operation with a hard-coded output shape value,
-* The [MatMul](@ref openvino_docs_ops_matrix_MatMul_1) operation with the `Const` second input and this input cannot be resized by spatial dimensions due to operation semantics.
+* The :doc:`Reshape <openvino_docs_ops_shape_Reshape_1>` operation with a hard-coded output shape value,
+* The :doc:`MatMul <openvino_docs_ops_matrix_MatMul_1>` operation with the ``Const`` second input and this input cannot be resized by spatial dimensions due to operation semantics.
 
 Model structure and logic should not change significantly after model reshaping.
-- The Global Pooling operation is commonly used to reduce output feature map of classification models output.
-Having the input of the shape *[N, C, H, W]*, Global Pooling returns the output of the shape *[N, C, 1, 1]*.
-Model architects usually express Global Pooling with the help of the `Pooling` operation with the fixed kernel size *[H, W]*.
-During spatial reshape, having the input of the shape *[N, C, H1, W1]*, `Pooling` with the fixed kernel size *[H, W]* returns the output of the shape *[N, C, H2, W2]*, where *H2* and *W2* are commonly not equal to *1*.
-It breaks the classification model structure.
-For example, the public [Inception family models from TensorFlow](https://github.com/tensorflow/models/tree/master/research/slim#pre-trained-models) have this issue.
 
-- Changing the model input shape may significantly affect its accuracy.
-For example, Object Detection models from TensorFlow have resizing restrictions by design.
-To keep the model valid after the reshape, choose a new input shape that satisfies conditions listed in the `pipeline.config` file.
-For details, refer to the [Tensorflow Object Detection API models resizing techniques](@ref custom-input-shape).
+* The Global Pooling operation is commonly used to reduce output feature map of classification models output. Having the input of the shape *[N, C, H, W]*, Global Pooling returns the output of the shape *[N, C, 1, 1]*. Model architects usually express Global Pooling with the help of the ``Pooling`` operation with the fixed kernel size *[H, W]*. During spatial reshape, having the input of the shape *[N, C, H1, W1]*, ``Pooling`` with the fixed kernel size *[H, W]* returns the output of the shape *[N, C, H2, W2]*, where *H2* and *W2* are commonly not equal to *1*. It breaks the classification model structure. For example, the public `Inception family models from TensorFlow <https://github.com/tensorflow/models/tree/master/research/slim#pre-trained-models>`__ have this issue.
 
-@anchor how-to-fix-non-reshape-able-model
+* Changing the model input shape may significantly affect its accuracy. For example, Object Detection models from TensorFlow have resizing restrictions by design. To keep the model valid after the reshape, choose a new input shape that satisfies conditions listed in the ``pipeline.config`` file. For details, refer to the :ref:`Tensorflow Object Detection API models resizing techniques <custom-input-shape>`.
 
-### How To Fix Non-Reshape-able Model
+.. _how-to-fix-non-reshape-able-model:
+
+How To Fix Non-Reshape-able Model
+#################################
 
 To fix some operators which prevent normal shape propagation:
-* see if the issue can be fixed via changing the values of some operators' input.
-For example, the most common problem of non-reshape-able models is a `Reshape` operator with a hard-coded output shape.
-You can cut-off the hard-coded second input of `Reshape` and fill it in with relaxed values.
-For the following example in the diagram below, the Model Optimizer CLI should read:
-```sh
-mo --input_model path/to/model --input data[8,3,224,224],1:reshaped[2]->[0,-1]`
-```
 
-  With `1:reshaped[2]`, it is required to cut the second input (counting from zero, so `1:` means the second input) of the operation named `reshaped` and   replace it with a `Parameter` with shape `[2]`.
-  With `->[0 -1]`, this new `Parameter` is replaced by a `Constant` operator which has the `[0, -1]` value.
-  Since the `Reshape` operator has `0` and `-1` as specific values, it allows propagating shapes freely without losing the intended meaning of `Reshape`.   For more information, see [the specification](@ref openvino_docs_ops_shape_Reshape_1).
-  ![batch_relaxed](./img/batch_relaxation.png)
+* see if the issue can be fixed via changing the values of some operators' input. For example, the most common problem of non-reshape-able models is a ``Reshape`` operator with a hard-coded output shape. You can cut-off the hard-coded second input of ``Reshape`` and fill it in with relaxed values. For the following example in the diagram below, the Model Optimizer CLI should read:
 
-* transform the model during Model Optimizer conversion on the back phase. For more information, see the [Model Optimizer extension](@ref openvino_docs_MO_DG_prepare_model_customize_model_optimizer_Customize_Model_Optimizer),
-* transform OpenVINO Model during the runtime. For more information, see [OpenVINO Runtime Transformations](@ref openvino_docs_transformations),
+  .. code-block:: sh
+
+     mo --input_model path/to/model --input data[8,3,224,224],1:reshaped[2]->[0,-1]`
+
+
+  With ``1:reshaped[2]``, it is required to cut the second input (counting from zero, so ``1:`` means the second input) of the operation named ``reshaped`` and replace it with a ``Parameter`` with shape ``[2]``.
+  With ``->[0 -1]``, this new ``Parameter`` is replaced by a ``Constant`` operator which has the ``[0, -1]`` value.
+  Since the ``Reshape`` operator has ``0`` and ``-1`` as specific values, it allows propagating shapes freely without losing the intended meaning of ``Reshape``.   For more information, see :doc:`the specification <openvino_docs_ops_shape_Reshape_1>`.
+
+  .. image:: _static/images/batch_relaxation.png
+
+* transform the model during Model Optimizer conversion on the back phase. For more information, see the :doc:`Model Optimizer extension <openvino_docs_MO_DG_prepare_model_customize_model_optimizer_Customize_Model_Optimizer>`,
+* transform OpenVINO Model during the runtime. For more information, see :doc:`OpenVINO Runtime Transformations <openvino_docs_transformations>`,
 * modify the original model with the help of the original framework.
+
+@endsphinxdirective

docs/OV_Runtime_UG/ov_without_dynamic_shapes.md

@@ -1,9 +1,12 @@
 # When Dynamic Shapes API is Not Applicable  {#openvino_docs_OV_UG_NoDynamicShapes}
 
-Several approaches to emulate dynamic shapes are considered in this article.
-Apply the following methods only if the [native dynamic shape API](ov_dynamic_shapes.md) does not work or does not perform as expected.
+@sphinxdirective
 
-## Padding
+Several approaches to emulate dynamic shapes are considered in this article.
+Apply the following methods only if the :doc:`native dynamic shape API <openvino_docs_OV_UG_DynamicShapes>` does not work or does not perform as expected.
+
+Padding
+####################
 
 The model can be designed in a way that supports partially filled tensors.
 For the BERT model, use a special input to the model to mask out unused elements.
@@ -16,7 +19,8 @@ The model can even crash during inference.
 
 The main disadvantage of padding, apart from impacting developer experience, is poor performance. Even if the model is properly designed for padding, it is often designed in such a way that the time-consuming processing of dummy elements in the padded area still occurs, not affecting the end result but decreasing inference speed.
 
-## Multiple Pre-compiled Models
+Multiple Pre-compiled Models
+############################
 
 Another approach to handle arbitrary sized inputs is to pre-compile several models reshaped for different input shapes.
 This method works well if the number of different shapes is small enough to afford increased time for multiple reshapes and compilations
@@ -25,7 +29,8 @@ As this method cannot be scaled well, it is used in combination with padding.
 Hence, the model with the most suitable input shape among pre-reshaped models is chosen.
 It gives a smaller padding area in comparison to a single model.
 
-## Dimension Partitioning
+Dimension Partitioning
+######################
 
 Another practical but still complicated approach is to divide the input tensor into multiple chunks along the dynamic dimension.
 For example, if there is a batch of independent inputs as a single tensor.
@@ -33,7 +38,9 @@ If arbitrary division along batch dimension is possible, and it should be possib
 run multiple inferences. Use the approach with several pre-compiled models, choosing sized inputs to have the minimum number of inferences,
 having a particular batch size in the input tensor.
 
-For example, if there are models pre-compiled for batch sizes `1`, `2`, `4` and `8`,
-the input tensor with batch `5` can be processed with two inference calls with batch size `1` and `4`.
+For example, if there are models pre-compiled for batch sizes ``1``, ``2``, ``4`` and ``8``,
+the input tensor with batch ``5`` can be processed with two inference calls with batch size ``1`` and ``4``.
 (At this point, it is assumed that the batch processing is required for performance reasons. In other cases, just loop over images in a batch
 and process image by image with a single compiled model.)
+
+@endsphinxdirective