Restructing demos - aot (#556)

Summary:
Pull Request resolved: #556

## Proposed code structure (dir only):
```
executorch/examples/
├── README.md  # top-level description for demos and folder structures
├── models
│   ├── deeplab_v3
│   |   ...
│   └── wav2letter
├── quantization
│   ├── quant_flow
│   └── toy_quantizer
├── backend
│   ├── toy_partitioner
│   └── xnnpack
├── export
│   ├── portable
│   └── xnnpack
├── recipes  # where detailed description (README.md) for each demo should go
│   ├── arm_tosa_delegate
│   ├── export_and_delegate
│   ├── export_bundled_program
│   ├── toy_quantizer_and_partitioner  # for vendor
│   └── xnnpack
├── runtime
│   ├── bundled
│   │   ├── bundled_executor_runner
│   ├── portable
│   │   ├── executor_runner
│   └── xnnpack
│       └── xnn_executor_runner
├── third-party
├── ios_demo_apps
├── android_demo_apps
├── custom_ops   # non-e2e demo
└── selective_build  # non-e2e demo
```

Reference to old code structure: https://github.com/pytorch/executorch/tree/main/examples

## This Diff
Focus on restructing AOT, e.g. `quantization/`, `backend/`, `export/`, `recipes/`

Differential Revision: D49799049

fbshipit-source-id: fee7f964b0e8f2de17164e4f3a44d7e6d67a43da

Author: guangy10

.ci/scripts/gather_test_models.py

@@ -10,7 +10,7 @@
 from typing import Any
 
 from examples.models import MODEL_NAME_TO_MODEL
-from examples.recipes.xnnpack_optimization import MODEL_NAME_TO_OPTIONS
+from examples.recipes.xnnpack import MODEL_NAME_TO_OPTIONS
 
 BUILD_TOOLS = [
     "buck2",
@@ -51,7 +51,8 @@ def export_models_for_ci() -> None:
     for name in MODEL_NAME_TO_MODEL.keys():
         quantization_configs = {
             False,
-            name in MODEL_NAME_TO_OPTIONS and MODEL_NAME_TO_OPTIONS[name].quantization,
+            name in MODEL_NAME_TO_OPTIONS
+            and MODEL_NAME_TO_OPTIONS[name].xnnpack_quantization,
         }
         delegation_configs = {
             False,

.ci/scripts/test.sh

@@ -53,7 +53,7 @@ build_cmake_executor_runner() {
 }
 
 test_model() {
-  "${PYTHON_EXECUTABLE}" -m examples.export.export_example --model_name="${MODEL_NAME}"
+  "${PYTHON_EXECUTABLE}" -m examples.export.portable --model_name="${MODEL_NAME}"
 
   # Run test model
   if [[ "${BUILD_TOOL}" == "buck2" ]]; then
@@ -92,17 +92,17 @@ test_model_with_xnnpack() {
 
   # Quantization-only
   if [[ ${WITH_QUANTIZATION} == true ]] && [[ ${WITH_DELEGATION} == false ]]; then
-    bash examples/quantization/test_quantize.sh "${BUILD_TOOL}" "${MODEL_NAME}"
+    bash examples/quantization/quant_flow/test_quantize.sh "${BUILD_TOOL}" "${MODEL_NAME}"
     exit 0
   fi
 
   # Delegation
   if [[ ${WITH_QUANTIZATION} == true ]]; then
     SUFFIX="q8"
-    "${PYTHON_EXECUTABLE}" -m examples.backend.xnnpack_examples --model_name="${MODEL_NAME}" --delegate --quantize
+    "${PYTHON_EXECUTABLE}" -m examples.recipes.xnnpack.aot_compiler --model_name="${MODEL_NAME}" --delegate --quantize
   else
     SUFFIX="fp32"
-    "${PYTHON_EXECUTABLE}" -m examples.backend.xnnpack_examples --model_name="${MODEL_NAME}" --delegate
+    "${PYTHON_EXECUTABLE}" -m examples.recipes.xnnpack.aot_compiler --model_name="${MODEL_NAME}" --delegate
   fi
 
   OUTPUT_MODEL_PATH="${MODEL_NAME}_xnnpack_${SUFFIX}.pte"
@@ -123,9 +123,9 @@ test_model_with_xnnpack() {
 
 test_demo_backend_delegation() {
   echo "Testing demo backend delegation on AddMul"
-  "${PYTHON_EXECUTABLE}" -m examples.export.export_and_delegate  --option "composite"
-  "${PYTHON_EXECUTABLE}" -m examples.export.export_and_delegate  --option "partition"
-  "${PYTHON_EXECUTABLE}" -m examples.export.export_and_delegate  --option "whole"
+  "${PYTHON_EXECUTABLE}" -m examples.recipes.export_and_delegate  --option "composite"
+  "${PYTHON_EXECUTABLE}" -m examples.recipes.export_and_delegate  --option "partition"
+  "${PYTHON_EXECUTABLE}" -m examples.recipes.export_and_delegate  --option "whole"
 
   # Run test model
   if [[ "${BUILD_TOOL}" == "buck2" ]]; then

docs/source/getting-started-setup.md

@@ -105,17 +105,17 @@ how to do it, we will generate an ExecuTorch program file from an `nn.Module`.
 You can generate an ExecuTorch program by using a sample script or by using
 the Python interpreter.
 
-We have created the `export_example.py` script that demonstrates a simple model
+We have created the `portable.py` script that demonstrates a simple model
 export to flatbuffer. This script is available
 in the [pytorch/executorch](https://github.com/pytorch/executorch/tree/main/examples/export)
 repository.
 
 To generate a sample program, complete the following steps:
 
-1. Run the `export_example.py` script:
+1. Run the `portable.py` script:
 
   ```bash
-  python3 -m examples.export.export_example --model_name="add"
+  python3 -m examples.export.portable --model_name="add"
   ```
 
   :::{dropdown} Output

docs/website/docs/tutorials/00_setting_up_executorch.md

@@ -58,10 +58,10 @@ corresponsing version of the repo.
 Via python script:
 ```bash
 # Creates the file `add.pte`
-python3 -m examples.export.export_example --model_name="add"
+python3 -m examples.export.portable --model_name="add"
 
 # Creates the delegated program `composite_model.pte`, other options are "whole" and "partition"
-python3 -m examples.export.export_and_delegate --option "composite"
+python3 -m examples.recipes.export_and_delegate --option "composite"
 ```
 
 Or via python interpreter:

examples/README.md

@@ -8,9 +8,9 @@ It also includes a list of modules, from a simple `Add` to a full model like `Mo
 ```bash
 examples
 |── backend                           # Contains examples for exporting delegate models and running them using custom executor runners
-├── custom_ops                        # Contains examples to register custom operators into PyTorch as well as register its kernels into Executorch runtime
+├── custom_ops                        # Contains examples to register custom operators into PyTorch as well as register its kernels into ExecuTorch runtime
 ├── example_quantizer_and_delegate    # Contains examples to to fully lowered a MobileNetV2 model to the example backend with an example quantizer
-├── export                            # Python helper scripts to illustrate export workflow
+├── export                            # Contains scripts to illustrate export workflow in portable mode
 ├── ios_demo_apps                     # Contains iOS demo apps
 ├── models                            # Contains a set of out-of-box PyTorch models
 ├── quantization                      # Contains examples of quantization workflow
@@ -23,33 +23,33 @@ examples
 
 We will walk through an example model to generate a binary file from a python torch.nn.module
 from the `models` dir using scripts from the `export` dir. Then we will run on these binary
-model files on the Executorch (ET) runtime. For that we will use `executor_runner`. It is a simple
-wrapper for the Executorch runtime to serve as an example. Although simple, it is capable of loading
+model files on the ExecuTorch (ET) runtime. For that we will use `executor_runner`. It is a simple
+wrapper for the ExecuTorch runtime to serve as an example. Although simple, it is capable of loading
 and executing previously exported binary file(s).
 
 
 1. Following the setup guide in [Setting up ExecuTorch from GitHub](/docs/website/docs/tutorials/00_setting_up_executorch.md)
-you should be able to get the basic development environment for Executorch working.
+you should be able to get the basic development environment for ExecuTorch working.
 
-2. Using the script `export/export_example.py` generate a model binary file by selecting a
+2. Using the example script `portable/aot_compiler.py` generate a model binary file by selecting a
 model name from the list of available models in the `models` dir.
 
 
 ```bash
 cd executorch # To the top level dir
 
 # To get a list of example models
-python3 -m examples.export.export_example -h
+python3 -m examples.export.portable -h
 
 # To generate a specific pte model
-python3 -m examples.export.export_example --model_name="mv2" # for MobileNetv2
+python3 -m examples.export.portable --model_name="mv2" # for MobileNetv2
 
 # This should generate ./mv2.pte file, if successful.
 ```
 
 Use `-h` (or `--help`) to see all the supported models.
 
-3. Once we have the model binary (pte) file, then let's run it with Executorch runtime using the `executor_runner`.
+3. Once we have the model binary (pte) file, then let's run it with ExecuTorch runtime using the `executor_runner`.
 
 ```bash
 buck2 run examples/runtime/portable:executor_runner -- --model_path mv2.pte

examples/custom_ops/custom_ops_1.py

@@ -6,7 +6,7 @@
 
 """Example of showcasing registering custom operator through torch library API."""
 import torch
-from examples.export.export_example import export_to_exec_prog, save_pte_program
+from examples.export.utils import export_to_exec_prog, save_pte_program
 
 from executorch.exir import EdgeCompileConfig
 from torch.library import impl, Library

examples/custom_ops/custom_ops_2.py

@@ -11,7 +11,7 @@
 import argparse
 
 import torch
-from examples.export.export_example import export_to_exec_prog, save_pte_program
+from examples.export.utils import export_to_exec_prog, save_pte_program
 from executorch.exir import EdgeCompileConfig
 
 

examples/export/export_example.py renamed to examples/export/portable.py

@@ -11,6 +11,7 @@
 
 from ..models import MODEL_NAME_TO_MODEL
 from ..models.model_factory import EagerModelFactory
+
 from .utils import export_to_exec_prog, save_pte_program
 
 

examples/ios_demo_apps/README.md

@@ -20,7 +20,7 @@ and UI looks like
 
 ![](./executorch_mobilenet_ui.png)
 
-Step 1. Export a MobileNetV2 model following example follwing executorch/examples/export/export_example.py. Instead of export mv2 directly, add a softmax at the end
+Step 1. Export a MobileNetV2 model following example follwing executorch/examples/export/portable.py. Instead of export mv2 directly, add a softmax at the end
 ```python
 class MobileNetV2Wrapper(torch.nn.Module):
     def __init__(self):

examples/quantization/quant_flow/TARGETS

@@ -0,0 +1,26 @@
+load("@fbsource//xplat/executorch/build:runtime_wrapper.bzl", "runtime")
+
+runtime.python_binary(
+    name = "example",
+    main_src = "example.py",
+    preload_deps = ["//executorch/kernels/quantized:aot_lib"],
+    deps = [
+        ":quant_utils",
+        "//caffe2:torch",
+        "//executorch/examples/export:lib",
+        "//executorch/examples/recipes/xnnpack:models",
+    ],
+)
+
+runtime.python_library(
+    name = "quant_utils",
+    srcs = [
+        "utils.py",
+    ],
+    visibility = [
+        "//executorch/examples/...",
+    ],
+    deps = [
+        "//caffe2:torch",
+    ],
+)

examples/quantization/example.py renamed to examples/quantization/quant_flow/example.py

@@ -28,10 +28,10 @@
     XNNPACKQuantizer,
 )
 
-from ..export.utils import export_to_edge, save_pte_program
-from ..models import MODEL_NAME_TO_MODEL
-from ..models.model_factory import EagerModelFactory
-from ..recipes.xnnpack_optimization import MODEL_NAME_TO_OPTIONS
+from ...export.utils import export_to_edge, save_pte_program
+from ...models import MODEL_NAME_TO_MODEL
+from ...models.model_factory import EagerModelFactory
+from ...recipes.xnnpack import MODEL_NAME_TO_OPTIONS
 
 from .utils import quantize
 
@@ -176,8 +176,9 @@ def verify_xnnpack_quantizer_matching_fx_quant_model(model_name, model, example_
     model = model.eval()
     # pre-autograd export. eventually this will become torch.export
     model = export.capture_pre_autograd_graph(model, example_inputs)
+    quantizer = XNNPACKQuantizer()
     start = time.perf_counter()
-    quantized_model = quantize(model, example_inputs)
+    quantized_model = quantize(model, example_inputs, quantizer)
     end = time.perf_counter()
     logging.info(f"Quantize time: {end - start}s")
 

examples/quantization/test_quantize.sh renamed to examples/quantization/quant_flow/test_quantize.sh

@@ -10,7 +10,7 @@
 set -e
 
 # shellcheck source=/dev/null
-source "$(dirname "${BASH_SOURCE[0]}")/../../.ci/scripts/utils.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/../../../.ci/scripts/utils.sh"
 
 get_shared_lib_ext() {
   UNAME=$(uname)
@@ -32,7 +32,7 @@ test_buck2_quantization() {
   SO_LIB=$($BUCK build //kernels/quantized:aot_lib --show-output | grep "buck-out" | cut -d" " -f2)
 
   echo "Run example.py"
-  ${PYTHON_EXECUTABLE} -m "examples.quantization.example" --so_library="$SO_LIB" --model_name="$1"
+  ${PYTHON_EXECUTABLE} -m "examples.quantization.quant_flow.example" --so_library="$SO_LIB" --model_name="$1"
 
   echo 'Running executor_runner'
   $BUCK run //examples/runtime/portable:executor_runner -- --model_path="./${1}_quantized.pte"
@@ -62,7 +62,7 @@ test_cmake_quantization() {
   SO_LIB="cmake-out/kernels/quantized/libquantized_ops_aot_lib$EXT"
 
   echo "Run example.py, shared library $SO_LIB"
-  ${PYTHON_EXECUTABLE} -m "examples.quantization.example" --so_library="$SO_LIB" --model_name="$1"
+  ${PYTHON_EXECUTABLE} -m "examples.quantization.quant_flow.example" --so_library="$SO_LIB" --model_name="$1"
 
   echo 'Running executor_runner'
   cmake-out/executor_runner --model_path="./${1}_quantized.pte"

examples/quantization/utils.py renamed to examples/quantization/quant_flow/utils.py

@@ -9,14 +9,14 @@
 from torch.ao.quantization.quantize_pt2e import convert_pt2e, prepare_pt2e
 from torch.ao.quantization.quantizer.xnnpack_quantizer import (
     get_symmetric_quantization_config,
-    XNNPACKQuantizer,
 )
 
 
-def quantize(model, example_inputs):
-    """This is the official recommended flow for quantization in pytorch 2.0 export"""
+def quantize(model, example_inputs, quantizer):
+    """
+    This is the official recommended flow for quantization in pytorch 2.0 export
+    """
     logging.info(f"Original model: {model}")
-    quantizer = XNNPACKQuantizer()
     # if we set is_per_channel to True, we also need to add out_variant of quantize_per_channel/dequantize_per_channel
     operator_config = get_symmetric_quantization_config(is_per_channel=False)
     quantizer.set_global(operator_config)

examples/recipes/TARGETS

@@ -0,0 +1,13 @@
+load("@fbsource//xplat/executorch/build:runtime_wrapper.bzl", "runtime")
+
+runtime.python_binary(
+    name = "export_bundled_program",
+    main_src = "export_bundled_program.py",
+    deps = [
+        "//executorch/bundled_program:config",
+        "//executorch/bundled_program:core",
+        "//executorch/bundled_program/serialize:lib",
+        "//executorch/examples/export:utils",
+        "//executorch/examples/models:models",
+    ],
+)

examples/export/export_and_delegate.py renamed to examples/recipes/export_and_delegate.py

@@ -17,11 +17,11 @@
 )
 from executorch.exir.backend.test.op_partitioner_demo import AddMulPartitionerDemo
 
+from ..export.utils import export_to_edge
+
 from ..models import MODEL_NAME_TO_MODEL
 from ..models.model_factory import EagerModelFactory
 
-from .utils import export_to_edge
-
 
 FORMAT = "[%(levelname)s %(asctime)s %(filename)s:%(lineno)s] %(message)s"
 logging.basicConfig(level=logging.INFO, format=FORMAT)

examples/export/export_bundled_program.py renamed to examples/recipes/export_bundled_program.py

@@ -8,16 +8,21 @@
 
 import argparse
 
+import logging
+
 from executorch.bundled_program.config import BundledConfig
 from executorch.bundled_program.core import create_bundled_program
 from executorch.bundled_program.serialize import (
     serialize_from_bundled_program_to_flatbuffer,
 )
 
+from ..export.utils import export_to_exec_prog, save_pte_program
+
 from ..models import MODEL_NAME_TO_MODEL
 from ..models.model_factory import EagerModelFactory
 
-from .utils import export_to_exec_prog, save_pte_program
+FORMAT = "[%(levelname)s %(asctime)s %(filename)s:%(lineno)s] %(message)s"
+logging.basicConfig(level=logging.INFO, format=FORMAT)
 
 
 def save_bundled_program(
@@ -62,7 +67,7 @@ def export_to_pte(model_name, model, example_inputs):
     # create a list with the example_inputs tuple used twice. Each instance of example_inputs
     # is a Tuple[Union[torch.tenor, int, bool]] which represents one test set for the model.
     bundled_inputs = [example_inputs, example_inputs]
-    print(f"Saving exported program to {model_name}_bundled.pte")
+    logging.info(f"Saving exported program to {model_name}_bundled.pte")
     save_bundled_program(bundled_inputs, exec_prog, model, f"{model_name}_bundled.pte")
 
 

examples/backend/README.md renamed to examples/recipes/xnnpack/README.md

@@ -10,10 +10,10 @@ The following command will produce an floating-point XNNPACK delegated model `mv
 
 ```bash
 # For MobileNet V2
-python3 -m examples.backend.xnnpack_examples --model_name="mv2" --delegate
+python3 -m examples.recipes.xnnpack.aot_compiler --model_name="mv2" --delegate
 ```
 
-Once we have the model binary (pte) file, then let's run it with Executorch runtime using the `xnn_executor_runner`.
+Once we have the model binary (pte) file, then let's run it with ExecuTorch runtime using the `xnn_executor_runner`.
 
 ```bash
 buck2 run examples/runtime/xnnpack:xnn_executor_runner -- --model_path ./mv2_xnnpack_fp32.pte
@@ -23,10 +23,10 @@ buck2 run examples/runtime/xnnpack:xnn_executor_runner -- --model_path ./mv2_xnn
 The following command will produce an XNNPACK quantized and delegated model `mv2_xnnpack_q8.pte` that can be run using XNNPACK's operators. It will also print out the lowered graph, showing what parts of the models have been lowered to XNNPACK via `executorch_call_delegate`.
 
 ```bash
-python3 -m examples.backend.xnnpack_examples --model_name="mv2" --quantize --delegate
+python3 -m examples.recipes.xnnpack.aot_compiler --model_name="mv2" --quantize --delegate
 ```
 
-Once we have the model binary (pte) file, then let's run it with Executorch runtime using the `xnn_executor_runner`.
+Once we have the model binary (pte) file, then let's run it with ExecuTorch runtime using the `xnn_executor_runner`.
 
 ```bash
 buck2 run examples/runtime/xnnpack:xnn_executor_runner -- --model_path ./mv2_xnnpack_q8.pte
@@ -44,7 +44,7 @@ We build the benchmarking binary (will be released in the near future, but it is
 
 ### Methodology
 
-Models are exported with the steps above for XNNPACK delegation, and with `examples/export:export_example` for portable backend without any optimization. Then use `//examples/runtime/xnnpack:xnn_executor_runner` with profiler (command listed below); or  in the future, use the runtime in `//sdk/runners:executor_runner` since it gives more options such as number of iterations after build rules for OSS is added.
+Models are exported with the steps above for XNNPACK delegation, and with `examples/export/portable.py` for portable backend without any optimization. Then use `//examples/runtime/xnnpack:xnn_executor_runner` with profiler (command listed below); or  in the future, use the runtime in `//sdk/runners:executor_runner` since it gives more options such as number of iterations after build rules for OSS is added.
 
 ```
 buck run -c executorch.prof_enabled=true -c executorch.prof_buf_size=8096 -c executorch.num_prof_blocks=61 //examples/runtime/xnnpack:xnn_executor_runner -- --model_path mv3.pte

examples/backend/TARGETS renamed to examples/recipes/xnnpack/TARGETS

@@ -4,12 +4,13 @@
 # This source code is licensed under the BSD-style license found in the
 # LICENSE file in the root directory of this source tree.
 
+
 from dataclasses import dataclass
 
 
 @dataclass
 class OptimizationOptions(object):
-    quantization: bool
+    xnnpack_quantization: bool
     xnnpack_delegation: bool
 
 
@@ -29,3 +30,5 @@ class OptimizationOptions(object):
     "edsr": OptimizationOptions(True, False),
     "mobilebert": OptimizationOptions(True, False),
 }
+
+__all__ = [MODEL_NAME_TO_OPTIONS]