Added documentation for release 1.33.0

Signed-off-by: Bharath Ramaswamy <[email protected]>

releases/1.33.0/Examples/tensorflow/quantization/keras/autoquant.ipynb

@@ -0,0 +1,380 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "# AutoQuant\n",
+    "\n",
+    "This notebook shows a working code example of how to use AIMET AutoQuant feature.\n",
+    "\n",
+    "AIMET offers a suite of neural network post-training quantization techniques. Often, applying these techniques in a specific sequence, results in better accuracy and performance. Without the AutoQuant feature, the AIMET user needs to manually try out various combinations of AIMET quantization features. This manual process is error-prone and often time-consuming.\n",
+    "\n",
+    "The AutoQuant feature, analyzes the model, determines the sequence of AIMET quantization techniques and applies these techniques. In addition, the user can specify the amount of accuracy drop that can be tolerated, in the AutoQuant API. As soon as this threshold accuracy is reached, AutoQuant stops applying any additional quantization technique. In summary, the AutoQuant feature saves time and automates the quantization of the neural networks.\n",
+    "\n",
+    "\n",
+    "#### Overall flow\n",
+    "This notebook covers the following\n",
+    "1. Instantiate the example evaluation and training pipeline\n",
+    "2. Load a pretrained FP32 model\n",
+    "3. Determine the baseline FP32 accuracy\n",
+    "4. Define constants and helper functions\n",
+    "5. Apply AutoQuant\n",
+    "\n",
+    "#### What this notebook is not\n",
+    "* This notebook is not designed to show state-of-the-art AutoQuant results. For example, it uses a relatively quantization-friendly model like Resnet50. Also, some optimization parameters are deliberately chosen to have the notebook execute more quickly."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "---\n",
+    "## Dataset\n",
+    "\n",
+    "This notebook relies on the ImageNet dataset for the task of image classification. If you already have a version of the dataset readily available, please use that. Else, please download the dataset from appropriate location (e.g. [https://image-net.org/challenges/LSVRC/2012/index.php#](https://image-net.org/challenges/LSVRC/2012/index.php#))\n",
+    "\n",
+    "**Note**: To speed up the execution of this notebook, you may use a reduced subset of the ImageNet dataset. E.g. the entire ILSVRC2012 dataset has 1000 classes, 1000 training samples per class and 50 validation samples per class. But for the purpose of running this notebook, you could perhaps reduce the dataset to say 2 samples per class. This exercise is left upto the reader and is not necessary.\n",
+    "\n",
+    "Edit the cell below and specify the directory where the downloaded ImageNet dataset is saved."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "DATASET_DIR = '/path/to/dir/'       # Please replace this with a real directory"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "os.environ['TF_CPP_MIN_LOG_LEVEL'] = '2'\n",
+    "\n",
+    "import tensorflow as tf\n",
+    "from aimet_tensorflow.keras.auto_quant import AutoQuant"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "---\n",
+    "\n",
+    "## 1. Example evaluation and training pipeline\n",
+    "\n",
+    "The following is an example training and validation loop for this image classification task.\n",
+    "\n",
+    "- **Does AIMET have any limitations on how the training, validation pipeline is written?** Not really. We will see later that AIMET will modify the user's model to create a QuantizationSim model which is still a TensorFlow model. This QuantizationSim model can be used in place of the original model when doing inference or training.\n",
+    "- **Does AIMET put any limitation on the interface of evaluate() or train() methods?** Not really. You should be able to use your existing evaluate and train routines as-is."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "from typing import Optional\n",
+    "from Examples.common import image_net_config\n",
+    "from Examples.tensorflow.utils.keras.image_net_dataset import ImageNetDataset\n",
+    "from Examples.tensorflow.utils.keras.image_net_evaluator import ImageNetEvaluator\n",
+    "\n",
+    "\n",
+    "class ImageNetDataPipeline:\n",
+    "    \"\"\"\n",
+    "    Provides APIs for model evaluation and finetuning using ImageNet Dataset.\n",
+    "    \"\"\"\n",
+    "\n",
+    "    @staticmethod\n",
+    "    def get_val_dataset(batch_size: Optional[int] = None) -> tf.data.Dataset:\n",
+    "        \"\"\"\n",
+    "        Instantiates a validation dataloader for ImageNet dataset and returns it\n",
+    "        :return: A tensorflow dataset\n",
+    "        \"\"\"\n",
+    "        if batch_size is None:\n",
+    "            batch_size = image_net_config.evaluation['batch_size']\n",
+    "\n",
+    "        data_loader = ImageNetDataset(DATASET_DIR,\n",
+    "                                      image_size=image_net_config.dataset['image_size'],\n",
+    "                                      batch_size=batch_size)\n",
+    "\n",
+    "        return data_loader\n",
+    "\n",
+    "    @staticmethod\n",
+    "    def evaluate(model, iterations=None) -> float:\n",
+    "        \"\"\"\n",
+    "        Given a Keras model, evaluates its Top-1 accuracy on the validation dataset\n",
+    "        :param model: The Keras model to be evaluated.\n",
+    "        :param iterations: The number of iterations to run. If None, all the data will be used\n",
+    "        :return: The accuracy for the sample with the maximum accuracy.\n",
+    "        \"\"\"\n",
+    "        evaluator = ImageNetEvaluator(DATASET_DIR,\n",
+    "                                      image_size=image_net_config.dataset[\"image_size\"],\n",
+    "                                      batch_size=image_net_config.evaluation[\"batch_size\"])\n",
+    "\n",
+    "        return evaluator.evaluate(model=model, iterations=iterations)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "## 2. Load a pretrained FP32 model\n",
+    "\n",
+    "For this example notebook, we are going to load a pretrained ResNet50 model from Keras. Similarly, you can load any pretrained Keras model instead."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "from tensorflow.keras.applications.resnet import ResNet50\n",
+    "\n",
+    "model = ResNet50(weights='imagenet')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "## 3.  Determine the baseline FP32 accuracy\n",
+    "Let's determine the FP32 (floating point 32-bit) accuracy of this model using evaluate() routine"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "ImageNetDataPipeline.evaluate(model=model)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "## 4. Define Constants and Helper functions\n",
+    "\n",
+    "In this section the constants and helper functions needed to run this example are defined.\n",
+    "\n",
+    "- **EVAL_DATASET_SIZE** A typical value is 5000. To execute this example faster this value has been set to 50\n",
+    "- **CALIBRATION_DATASET_SIZE** A typical value is 2000. To execute this example faster this value has been set to 20\n",
+    "- **BATCH_SIZE** User sets the batch size. As an example, set to 10\n",
+    "\n",
+    "\n",
+    "The helper function **_create_sampled_data_loader()** returns a DataLoader based on the dataset and the number of samples provided."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "EVAL_DATASET_SIZE = 50\n",
+    "CALIBRATION_DATASET_SIZE = 20\n",
+    "BATCH_SIZE = 10"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "eval_dataset = ImageNetDataPipeline.get_val_dataset(BATCH_SIZE).dataset\n",
+    "unlabeled_dataset = eval_dataset.map(lambda images, labels: images)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "## Prepare the evaluation callback function\n",
+    "\n",
+    "The **eval_callback()** function takes the model object to evaluate and compile option dictionary and the number of samples to use as arguments. If the **num_samples** argument is None, the whole evaluation dataset is used to evaluate the model."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "from typing import Optional\n",
+    "\n",
+    "\n",
+    "def eval_callback(model: tf.keras.Model,\n",
+    "                  num_samples: Optional[int] = None) -> float:\n",
+    "    if num_samples is None:\n",
+    "        num_samples = EVAL_DATASET_SIZE\n",
+    "\n",
+    "    sampled_dataset = eval_dataset.take(num_samples)\n",
+    "\n",
+    "    # Model should be compiled before evaluation\n",
+    "    model.compile(optimizer=tf.keras.optimizers.Adam(),\n",
+    "                  loss=tf.keras.losses.CategoricalCrossentropy(),\n",
+    "                  metrics=tf.keras.metrics.CategoricalAccuracy())\n",
+    "    _, acc = model.evaluate(sampled_dataset)\n",
+    "\n",
+    "    return acc"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "## 5. Apply AutoQuant\n",
+    "\n",
+    "As a first step, the AutoQuant object is created.\n",
+    "\n",
+    "The **allowed_accuracy_drop** parameter is set by the user to convey to the AutoQuant feature, how much accuracy drop is tolerated by the user. AutoQuant applies a series of quantization features. When the allowed accuracy is reached, AutoQuant stops applying any subsequent quantization feature. Please refer AutoQuant User Guide and API documentation for complete details."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "auto_quant = AutoQuant(allowed_accuracy_drop=0.01,\n",
+    "                       unlabeled_dataset=unlabeled_dataset,\n",
+    "                       eval_callback=eval_callback)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "## Optionally set AdaRound Parameters\n",
+    "The AutoQuant feature internally uses default parameters to execute the AdaRound step.\n",
+    "If and only if necessary, the default AdaRound Parameters should be modified using the API shown below.\n",
+    "\n",
+    "**Note:**\n",
+    "To execute this example faster, the default value of the **num_iterations** parameter has been reduced from 10000 to 2000"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "from aimet_tensorflow.adaround.adaround_weight import AdaroundParameters\n",
+    "\n",
+    "ADAROUND_DATASET_SIZE = 2000\n",
+    "adaround_dataset = unlabeled_dataset.take(ADAROUND_DATASET_SIZE)\n",
+    "adaround_params = AdaroundParameters(adaround_dataset,\n",
+    "                                     num_batches=ADAROUND_DATASET_SIZE // BATCH_SIZE)\n",
+    "auto_quant.set_adaround_params(adaround_params)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "## Run AutoQuant\n",
+    "\n",
+    "This step applies the AutoQuant feature. The best possible quantized model, the associated eval_score and the path to the AdaRound encoding files are returned."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [],
+   "source": [
+    "model, accuracy, encoding_path = auto_quant.apply(model)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "---\n",
+    "## Summary\n",
+    "\n",
+    "Hope this notebook was useful for you to understand how to use AIMET AutoQuant feature.\n",
+    "\n",
+    "Few additional resources\n",
+    "- Refer to the AIMET API docs to know more details of the APIs and parameters\n",
+    "- Refer to the other example notebooks to understand how to use AIMET CLE and AdaRound features in a standalone fashion."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}