InceptionV3 Models
==================

Overview
--------

Inception V3, a convolutional neural network (CNN) from Google's Inception family, is designed for deep networks with fewer than 25 million parameters. It excels in image analysis and object detection, with applications ranging from computer vision to life sciences like leukemia research. Often, it’s used pre-trained on ImageNet.

Model Conversion Flow
---------------------

Precondition
^^^^^^^^^^^^

.. note::
   For better compatibility, it is recommended to use **Python 3.7** when working with these models, as it has higher compatibility with certain libraries and frameworks.

1. **Install Required Libraries:**

   Ensure you have the necessary libraries installed:

   .. code-block:: bash

       pip install torch torchvision

Get Source Model
^^^^^^^^^^^^^^^^

Follow these steps to use and convert GoogLeNet models using PyTorch and TorchVision.
1. **Load and Convert GoogLeNet Model:**

   Load a pretrained Inception v3 model using PyTorch and TorchVision, create a dummy input tensor for tracing, trace the model to convert it to TorchScript, and finally save the traced model.

   Run the following Python script:

   .. code-block:: bash

       python generate_inception_v3_float.py

   .. code-block:: python

       import torch
       import torchvision

       model = torchvision.models.inception_v3(pretrained=True)
       trace_data = torch.randn(1, 3, 224, 224)
       trace_model = torch.jit.trace(model.cpu().eval(), trace_data)
       torch.jit.save(trace_model, 'Inception_v3.pt')

Converting Model for Deployment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Before you begin, ensure that the :doc:`NeuroPilot Converter Tool </sw/yocto/ml-guide/neuron-dev-flow/model_converter/neuropilot_converter_tool>` is installed. If you haven't installed it yet, please follow the instructions in the "Install and Verify NeuroPilot Converter Tool" section of the same guide.

Quant8 Conversion Process
*************************

1. **Generate Calibration Data:**

   The following script creates a directory named `data` and generates 100 batches of random input data, each saved as a `.npy` file. This data is used for calibration during the quantization process.

   .. code-block:: bash

       python generate_data_batches.py

   .. code-block:: python

       import os
       import numpy as np

       os.mkdir('data')
       for i in range(100):
           data = np.random.randn(1, 3, 224, 224).astype(np.float32)
           np.save('data/batch_{}.npy'.format(i), data)

2. **Convert to Quantized TFLite Format:**

   Use the following command to convert the model to a quantized TFLite format using the generated calibration data:

   .. code-block:: bash

       mtk_pytorch_converter                                 \
           --input_script_module_file=Inception_v3.pt        \
           --output_file=Inception_v3_ptq_quant.tflite       \
           --input_shapes=1,3,224,224                        \
           --quantize=True                                   \
           --input_value_ranges=-1,1                         \
           --calibration_data_dir=data/                      \
           --calibration_data_regexp=batch_.*\.npy

3. **Convert to Quantized DLA Format**

.. warning::
   The process of converting this model to DLA format may encounter unsupported operations. 
   Before converting, you need to prune the model using the provided script to ensure compatibility 
   with the DLA converter.

   Here is an example of how to prune the `Inception_v3_ptq_quant.tflite` model using the 
   `export_quant_support_op.py` script:

   .. code-block:: python

      import mtk_converter

      editor = mtk_converter.TFLiteEditor("Inception_v3_ptq_quant.tflite")
      output_file = "Inception_v3_ptq_quant_15-181_sdkv6.tflite"
      input_names = ["input.4"]
      output_names = ["1707"]
      _ = editor.export(output_file=output_file, input_names=input_names, output_names=output_names)

.. note::
   The `input_names` and `output_names` specified in this script are based on the example model structure. 
   You need to modify these names according to the input and output tensor names specific to your model. 
   You can inspect the model structure using tools like `Netron` or TensorFlow utilities to identify 
   the correct tensor names for your model.

.. tip::
   For more detailed information and steps on handling unsupported operations in DLA conversion, please see 
   :ref:`Unsupported Operations in DLA Conversion (Optional)`.

- **NeuroPilot SDK tools Download and Convert to DLA**:

  1. **Download the NeuroPilot SDK All-In-One Bundle:**

     Visit the following download page and download the necessary bundle: `NeuroPilot Downloads <https://neuropilot.mediatek.com/sphinx/neuropilot-6-basic-customer/html/l1_downloads/downloads_external.html#neuropilot-downloads>`_

  2. **Extract the Bundle:**

     After downloading, extract the bundle using the following command:

     .. code-block:: bash

        tar zxvf neuropilot-sdk-basic-<version>.tar.gz

  3. **Set the Environment Variables:**

     Set the environment variables to point to the SDK:

     .. code-block:: bash

        export LD_LIBRARY_PATH=/path/to/neuropilot-sdk-basic-<version>/neuron_sdk/host/lib

  4. **Convert INT8 TFLite Model to DLA Format:**

     Use the NeuroPilot Converter Tool to convert your TFLite model into the DLA format. The following example shows how to convert an INT8 TFLite model to DLA format using the specified architecture (`mdla3.0`).

     .. code-block:: bash

        /path/to/neuropilot-sdk-basic-<version>/neuron_sdk/host/bin/ncc-tflite --arch=mdla3.0 Inception_v3_ptq_quant_15-181_sdkv6.tflite

.. note::
   To ensure compatibility with your device, please download and use **NeuroPilot SDK version 6**. Other versions might not be fully supported.

FP32 Conversion Process
***********************

1. **Convert to FP32 TFLite Format:**

   To convert the model to a non-quantized (FP32) TFLite format, use the following command:

.. code-block:: bash

       mtk_pytorch_converter                                 \
           --input_script_module_file=Inception_v3.pt        \
           --output_file=Inception_v3.tflite                 \
           --input_shapes=1,3,224,224

2. **Convert to FP32 DLA Format**

.. warning::
   The process of converting this model to DLA format may encounter unsupported operations. 
   Before converting, you need to prune the model using the provided script to ensure compatibility 
   with the DLA converter.

   Here is an example of how to prune the `Inception_v3.tflite` model using the `export_float_support_op.py` script:

.. code-block:: python

    import mtk_converter
    editor = mtk_converter.TFLiteEditor("Inception_v3.tflite")

    output_file = "Inception_v3_15-181_sdkv6.tflite"
    input_names = ["input.4"]
    output_names = ["1707"]

    _ = editor.export(output_file=output_file, input_names=input_names, output_names=output_names)


.. note::

   The `input_names` and `output_names` specified in this script are based on the example model structure. 
   You need to modify these names according to the input and output tensor names specific to your model. 
   You can inspect the model structure using tools like `Netron` or TensorFlow utilities to identify 
   the correct tensor names for your model.

- **Set the Environment and Convert to DLA:**

  1. **Set the Environment Variables:**

     Set the environment variables to point to the SDK:

     .. code-block:: bash

         export LD_LIBRARY_PATH=/path/to/neuropilot-sdk-basic-<version>/neuron_sdk/host/lib

  2. **Convert FP32 TFLite Model to DLA Format:**

     Use the NeuroPilot Converter Tool to convert your FP32 TFLite model into the DLA format. The following example shows how to convert an FP32 TFLite model to DLA format using the specified architecture (`mdla3.0`) and enabling relaxed FP32 operations:

     .. code-block:: bash

         /path/to/neuropilot-sdk-basic-<version>/neuron_sdk/host/bin/ncc-tflite --arch=mdla3.0 --relax-fp32 Inception_v3_15-181_sdkv6.tflite


Model Information
-----------------

.. note::
   The models and benchmark data mentioned below have been processed using the **mtk_converter**.

General Information
^^^^^^^^^^^^^^^^^^^

The following table contains general information about the model. The details, such as input size, GFLOPS, and number of parameters, are sourced from the official PyTorch documentation at: 
`Inception_V3 Model <https://pytorch.org/vision/main/models/generated/torchvision.models.inception_v3.html#torchvision.models.inception_v3>`_.

+-----------------------+-------------------------------------------------------------------------------------------------------------------+
| Property              | Value                                                                                                             |
+=======================+===================================================================================================================+
| Category              | Classification                                                                                                    |
+-----------------------+-------------------------------------------------------------------------------------------------------------------+
| Input Size            | 224x224                                                                                                           |
+-----------------------+-------------------------------------------------------------------------------------------------------------------+
| GFLOPS                | 1.50                                                                                                              |
+-----------------------+-------------------------------------------------------------------------------------------------------------------+
| #Params (M)           | 6.62                                                                                                              |
+-----------------------+-------------------------------------------------------------------------------------------------------------------+
| Training Framework    | PyTorch                                                                                                           |
+-----------------------+-------------------------------------------------------------------------------------------------------------------+
| Inference Framework   | TFLite                                                                                                            |
+-----------------------+-------------------------------------------------------------------------------------------------------------------+


Pre-converted Model
^^^^^^^^^^^^^^^^^^^

Deployable Model
****************

+-----------------------+--------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+
| Model Type            | Download Link                                                                                                            | Supported Backend                                      |
+=======================+==========================================================================================================================+========================================================+
| Quant8  Model package | `Download: Quant8 <https://mediatek-aiot.s3.ap-southeast-1.amazonaws.com/aiot/download/model-zoo/inception_v3-int8.zip>`_| NeuronSDK                                              |
+-----------------------+--------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+
| Float32 Model package | `Download: Fp32 <https://mediatek-aiot.s3.ap-southeast-1.amazonaws.com/aiot/download/model-zoo/inception_v3-fp32.zip>`_  | CPU,GPU,ArmNN,Neuron Stable Delegate,NeuronSDK         |
+-----------------------+--------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+

Model Properties
****************

- **InceptionV3-quant8**

**Inputs**

+-----------------------+------------------------------------------+
| **Property**          | **Value**                                |
+=======================+==========================================+
| Name                  | x.2                                      |
+-----------------------+------------------------------------------+
| Tensor                | int8[1,3,224,224]                        |
+-----------------------+------------------------------------------+
| Identifier            | 154                                      |
+-----------------------+------------------------------------------+
| Quantization          | Linear                                   |
+-----------------------+------------------------------------------+
| Quantization Range    | -1.0039 ≤ 0.0078 * q ≤ 0.9961            |
+-----------------------+------------------------------------------+

**Outputs**

+-----------------------+------------------------------------------+
| **Property**          | **Value**                                |
+=======================+==========================================+
| Name                  | 1707                                     |
+-----------------------+------------------------------------------+
| Tensor                | int8[1,1000]                             |
+-----------------------+------------------------------------------+
| Identifier            | 73                                       |
+-----------------------+------------------------------------------+
| Quantization          | Linear                                   |
+-----------------------+------------------------------------------+
| Quantization Range    | -2.0561 ≤ 0.0196 * (q + 23) ≤ 2.9372     |
+-----------------------+------------------------------------------+


- **InceptionV3-fp32**

**Inputs**

+-----------------------+------------------------------------------+
| **Property**          | **Value**                                |
+=======================+==========================================+
| Name                  | x.2                                      |
+-----------------------+------------------------------------------+
| Tensor                | float32[1,3,224,224]                     |
+-----------------------+------------------------------------------+
| Identifier            | 157                                      |
+-----------------------+------------------------------------------+


**Outputs**

+-----------------------+------------------------------------------+
| **Property**          | **Value**                                |
+=======================+==========================================+
| Name                  | 1707                                     |
+-----------------------+------------------------------------------+
| Tensor                | float32[1,1000]                          |
+-----------------------+------------------------------------------+
| Identifier            | 8                                        |
+-----------------------+------------------------------------------+

Benchmark Results
^^^^^^^^^^^^^^^^^

.. note::
   The benchmark results shown below were measured with performance mode enabled. These numbers are for reference only, as actual performance may vary depending on the hardware and platform used.

   Please note the following limitations:

   1. The G350 does not support Neuron Stable Delegate and NeuronSDK because the hardware does not yet support these features.
   2. The model may not run on certain backends due to custom operators generated by the MTK converter. These custom operators are not recognized or supported by the TensorFlow Lite interpreter, which may lead to incompatibility issues during inference.
   3. Running models on the G350 using ArmNN inference may result in a crash due to the model size being too large for the platform to handle.
   
- **InceptionV3-quant8**

.. csv-table::
   :file: /_asset/tables/Model_Benchmark_tables/int8_InceptionV3.csv
   :width: 100%
   :widths: 10 15 15 15 15 15 15

- **InceptionV3-fp32**

.. csv-table::
   :file: /_asset/tables/Model_Benchmark_tables/fp32_InceptionV3.csv
   :width: 100%
   :widths: 10 15 15 15 15 15 15

Run Benchmark Tools
^^^^^^^^^^^^^^^^^^^

This section will guide you on how to execute the benchmark tool with different delegates and hardware configurations.

1. First, push your TFLite model to the target device:

.. code-block:: bash

   adb push <your_tflite_model> /usr/share/label_image/

Make sure to replace `<your_tflite_model>` with the actual path of your TFLite model.

2. Next, open an ADB shell to the target device:

.. code-block:: bash

   adb shell

After this, you can execute the following commands directly from the shell.

Execute on CPU (8 threads)
**************************

To execute the benchmark on the CPU using 8 threads, run the following command:

.. code-block:: bash

   benchmark_model --graph=/usr/share/label_image/<your_tflite_model> --num_threads=8 --num_runs=10

Execute on GPU, with GPU delegate
*********************************

To execute the benchmark on the GPU using the TensorFlow Lite GPU delegate, run the following command:

.. code-block:: bash

   benchmark_model --graph=/usr/share/label_image/<your_tflite_model> --use_gpu=1 --gpu_precision_loss_allowed=1 --num_runs=10

Execute on GPU, with Arm NN delegate
************************************

To execute the benchmark on the GPU using the Arm NN delegate, use the following command:

.. code-block:: bash

   benchmark_model --graph=/usr/share/label_image/<your_tflite_model> --external_delegate_path=/usr/lib/libarmnnDelegate.so.29 --external_delegate_options="backends:GpuAcc" --num_runs=10

Execute on CPU, with Arm NN delegate
************************************

To run the benchmark on the CPU using the Arm NN delegate, use the following command:

.. code-block:: bash

   benchmark_model --graph=/usr/share/label_image/<your_tflite_model> --external_delegate_path=/usr/lib/libarmnnDelegate.so.29 --external_delegate_options="backends:CpuAcc" --num_runs=10

Execute on APU, with Neuron Delegate
************************************

For executing on the APU using the Neuron delegate, run the following command:

.. code-block:: bash

   benchmark_model --stable_delegate_settings_file=/usr/share/label_image/stable_delegate_settings.json --use_nnapi=false --use_xnnpack=false --use_gpu=false --min_secs=20 --graph=/usr/share/label_image/<your_tflite_model>

.. note::
   If you are using the G350 platform, please make the following adjustments:
   
   - For CPU-based benchmarks, change the `--num_threads` parameter to 4:
   
     .. code-block:: bash

        benchmark_model --graph=/usr/share/label_image/<your_tflite_model> --num_threads=4 --use_xnnpack=0 --num_runs=10
   
   - For all benchmarks (CPU, GPU, Arm NN), add the parameter `--use_xnnpack=0` to disable the XNNPACK delegate

Neuron SDK
^^^^^^^^^^

Follow these steps to benchmark your TensorFlow Lite model using the Neuron SDK with MDLA 3.0:

1. **Transfer the Model to the Device:**

   Use `adb` to push your TFLite model to the device:

   .. code-block:: bash

       adb push <your_tflite_model> /user/share/benchmark_dla/

.. note::
   Make sure to push the **pruned** model (after using the pruning script) to the device to ensure compatibility with the DLA converter. The pruned model should be used instead of the original model for accurate benchmarking.

2. **Access the Device Shell:**

   Connect to your device's shell:

   .. code-block:: bash

       adb shell

3. **Navigate to the Benchmark Directory:**

   Change to the directory where the model is stored:

   .. code-block:: bash

       cd /user/share/benchmark_dla/

4. **Run the Benchmark:**

   Execute the benchmarking script with the following command:

   .. code-block:: bash

       python3 benchmark.py --file <your_tflite_model> --target mdla3.0 --profile --options='--relax-fp32'

**Description:**

- The `benchmark.py` script runs a performance evaluation on your model using MDLA 3.0.
- The `--file` parameter specifies the path to your TFLite model.
- The `--target mdla3.0` option sets the target hardware to MDLA 3.0.
- The `--profile` flag enables profiling to provide detailed performance metrics.
- The `--options='--relax-fp32'` option allows relaxation of floating-point precision to improve compatibility with MDLA.