Merge branch 'update_docs' into 'master'

Update docs

See merge request !651

README.md

@@ -4,9 +4,9 @@
 
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Build Status](https://travis-ci.org/travis-ci/travis-web.svg?branch=master)](https://travis-ci.org/travis-ci/travis-web)
 [![pipeline status](https://gitlab.com/llhe/mace/badges/master/pipeline.svg)](https://gitlab.com/llhe/mace/pipelines)
 [![doc build status](https://readthedocs.org/projects/mace/badge/?version=latest)](https://readthedocs.org/projects/mace/badge/?version=latest)
-[![Build Status](https://travis-ci.org/travis-ci/travis-web.svg?branch=master)](https://travis-ci.org/travis-ci/travis-web)
 
 [Documentation](https://mace.readthedocs.io) |
 [FAQ](https://mace.readthedocs.io/en/latest/faq.html) |

docs/conf.py

@@ -6,7 +6,7 @@
 import recommonmark.parser
 import sphinx_rtd_theme
 
-project = u'Mobile AI Compute Engine (MACE)'
+project = u'MACE'
 author = u'%s Developers' % project
 copyright = u'2018, %s' % author
 

docs/installation/env_requirement.rst

-Environment Requirement
+Environment requirement
 ========================
 
 MACE requires the following dependencies:
 
-Necessary Dependencies:
-------------------------
+Required dependencies
+---------------------
 
 .. list-table::
     :header-rows: 1
 
-    * - software
-      - version
-      - install command
-    * - bazel
-      - >= 0.13.0
+    * - Software
+      - Installation command
+      - Tested version
+    * - Python
+      -
+      - 2.7
+    * - Bazel
       - `bazel installation guide <https://docs.bazel.build/versions/master/install.html>`__
-    * - android-ndk
-      - r15c/r16b
-      - `NDK installation guide <https://developer.android.com/ndk/guides/setup#install>`__
-    * - adb
-      - >= 1.0.32
-      - apt-get install android-tools-adb
-    * - cmake
-      - >= 3.11.3
+      - 0.13.0
+    * - CMake
       - apt-get install cmake
-    * - numpy
-      - >= 1.14.0
-      - pip install -I numpy==1.14.0
-    * - scipy
-      - >= 1.0.0
-      - pip install -I scipy==1.0.0
-    * - jinja2
-      - >= 2.10
+      - >= 3.11.3
+    * - Jinja2
       - pip install -I jinja2==2.10
+      - 2.10
     * - PyYaml
-      - >= 3.12.0
       - pip install -I pyyaml==3.12
+      - 3.12.0
     * - sh
-      - >= 1.12.14
       - pip install -I sh==1.12.14
-    * - filelock
-      - >= 3.0.0
-      - pip install -I filelock==3.0.0
-
-.. note::
+      - 1.12.14
 
-    ``export ANDROID_NDK_HOME=/path/to/ndk`` to specify ANDROID_NDK_HOME
-
-Optional Dependencies:
------------------------
+Optional dependencies
+---------------------
 
 .. list-table::
     :header-rows: 1
 
-    * - software
-      - version
-      - install command
-    * - tensorflow
-      - >= 1.6.0
-      - pip install -I tensorflow==1.6.0 (if you use tensorflow model)
-    * - docker (for caffe)
-      - >= 17.09.0-ce
+    * - Software
+      - Installation command
+      - Remark
+    * - Android NDK
+      - `NDK installation guide <https://developer.android.com/ndk/guides/setup#install>`__
+      - Required by Android build, r15b, r15c, r16b
+    * - ADB
+      - apt-get install android-tools-adb
+      - Required by Android run, >= 1.0.32
+    * - TensorFlow
+      - pip install -I tensorflow==1.6.0
+      - Required by TensorFlow model
+    * - Docker
       - `docker installation guide <https://docs.docker.com/install/linux/docker-ce/ubuntu/#set-up-the-repository>`__
+      - Required by docker mode for Caffe model
+    * - Numpy
+      - pip install -I numpy==1.14.0
+      - Required by model validation
+    * - Scipy
+      - pip install -I scipy==1.0.0
+      - Required by model validation
+    * - FileLock
+      - pip install -I filelock==3.0.0
+      - Required by Android run
+
+.. note::
+
+    For Android build, `ANDROID_NDK_HOME` must be confifigured by using ``export ANDROID_NDK_HOME=/path/to/ndk``

docs/installation/manual_setup.rst

 Manual setup
 =============
 
-The setup steps are based on ``Ubuntu``. And dependencies to install can refer to :doc:`env_requirement`.
-
-Install Necessary Dependencies
--------------------------------
+The setup steps are based on ``Ubuntu``, you can change the commands
+correspondingly for other systems.
+For the detailed installation dependencies, please refer to :doc:`env_requirement`.
 
 Install Bazel
-~~~~~~~~~~~~~~
+-------------
 
 Recommend bazel with version larger than ``0.13.0`` (Refer to `Bazel documentation <https://docs.bazel.build/versions/master/install.html>`__).
 
@@ -22,10 +21,11 @@ Recommend bazel with version larger than ``0.13.0`` (Refer to `Bazel documentati
         cd / && \
         rm -f /bazel/bazel-$BAZEL_VERSION-installer-linux-x86_64.sh
 
-Install NDK
-~~~~~~~~~~~~
+Install Android NDK
+--------------------
 
-Recommend NDK with version r15c or r16 (Refer to `NDK installation guide <https://developer.android.com/ndk/guides/setup#install>`__).
+The recommended Android NDK versions includes r15b, r15c and r16b (Refers to
+`NDK installation guide <https://developer.android.com/ndk/guides/setup#install>`__).
 
 .. code:: sh
 
@@ -43,7 +43,7 @@ Recommend NDK with version r15c or r16 (Refer to `NDK installation guide <https:
     export PATH=${PATH}:${ANDROID_NDK_HOME}
 
 Install extra tools
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 .. code:: sh
 
@@ -60,8 +60,8 @@ Install extra tools
         pycodestyle==2.4.0 \
         filelock
 
-Install Optional Dependencies
-------------------------------
+Install TensorFlow (Optional)
+-----------------------------
 
 .. code:: sh
 

docs/installation/using_docker.rst

 Using docker
 =============
 
-Pull or Build docker image
+Pull or build docker image
 ---------------------------
 
-MACE provides docker images with necessary dependencies installed and also Dockerfiles for images building,
+MACE provides docker images with dependencies installed and also Dockerfiles for images building,
 you can pull the existing ones directly or build them from the Dockerfiles.
-In most cases, the ``lite edition`` image can satify developer's basic needs.
+In most cases, the ``lite edition`` image can satisfy developer's basic needs.
 
 .. note::
     It's highly recommended to pull built images.

docs/introduction.rst

 Introduction
 ============
 
-Mobile AI Compute Engine (MACE) is a deep learning inference framework optimized for
-mobile heterogeneous computing platforms. MACE covers common mobile computing devices (CPU, GPU and DSP),
-and supplies tools and document to help users to deploy neural network model to mobile devices.
-MACE has been widely used in Xiaomi and proved with industry leading performance and stability.
+MACE (Mobile AI Compute Engine) is a deep learning inference framework optimized for
+mobile heterogeneous computing platforms. 
+MACE provides tools and documents to help users to deploy deep learning models
+to mobile phones, tablets, personal computers and IoT devices.
 
-Framework
----------
+Architecture
+-------------
 The following figure shows the overall architecture.
 
 .. image:: mace-arch.png
    :scale: 40 %
    :align: center
 
-==========
 MACE Model
-==========
+~~~~~~~~~~
 
 MACE defines a customized model format which is similar to
 Caffe2. The MACE model can be converted from exported models by TensorFlow
 and Caffe.
 
-================
 MACE Interpreter
-================
+~~~~~~~~~~~~~~~~~
 
 Mace Interpreter mainly parses the NN graph and manages the tensors in the graph.
 
-=======
 Runtime
-=======
+~~~~~~~
 
 CPU/GPU/DSP runtime correspond to the Ops for different devices.
 
@@ -42,36 +39,31 @@ The following figure shows the basic work flow of MACE.
    :scale: 60 %
    :align: center
 
-==================================
 1. Configure model deployment file
-==================================
-Model deploy configuration file (.yml) describe the information of the model and library,
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Model deploy configuration file (.yml) describes the information of the model and library,
 MACE will build the library based on the file.
 
-==================
 2. Build libraries
-==================
+~~~~~~~~~~~~~~~~~~
 Build MACE dynamic or static libraries.
 
-==================
 3. Convert model
-==================
+~~~~~~~~~~~~~~~~~~
 Convert TensorFlow or Caffe model to MACE model.
 
-===========
 4.1. Deploy
-===========
-Integrate the MACE library to your application and run with MACE API.
+~~~~~~~~~~~~~~~~~~
+Integrate the MACE library into your application and run with MACE API.
 
-==============
 4.2. Run (CLI)
-==============
-There are command line tools to run models, which could be used for testing time, memory usage and correctness.
+~~~~~~~~~~~~~~~~~~
+MACE provides `mace_run` command line tool, which could be used to run model
+and validate model correctness against original TensorFlow or Caffe results.
 
-==============
 4.3. Benchmark
-==============
-MACE supplies Benchmark tool to look up the run time of every Operation in the model.
+~~~~~~~~~~~~~~~~~~
+MACE provides benchmark tool to get the Op level profiling result of the model.
 
 
 
@@ -84,29 +76,26 @@ MACE覆盖了常见的移动端计算设备（CPU，GPU和DSP），并且提供
 
 框架
 ----
-下图描述了MACE的基本框架.
+下图描述了MACE的基本框架。
 
 .. image:: mace-arch.png
-   :scale: 60 %
+   :scale: 40 %
    :align: center
 
 
-==============
 MACE Model
-==============
+~~~~~~~~~~~~~~~~~~
 
 MACE定义了自有的模型格式（类似于Caffe2），通过MACE提供的工具可以将Caffe和TensorFlow的模型
 转为MACE模型。
 
-=================
 MACE Interpreter
-=================
+~~~~~~~~~~~~~~~~~~
 
 MACE Interpreter主要负责解析运行神经网络图（DAG）并管理网络中的Tensors。
 
-=======
 Runtime
-=======
+~~~~~~~~~~~~~~~~~~
 
 CPU/GPU/DSP Runtime对应于各个计算设备的算子实现。
 
@@ -119,33 +108,27 @@ CPU/GPU/DSP Runtime对应于各个计算设备的算子实现。
    :align: center
 
 
-==================================
 1. 配置模型部署文件(.yml)
-==================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 模型部署文件详细描述了需要部署的模型以及生成库的信息，MACE根据该文件最终生成对应的库文件。
 
-==================================
 2. 编译MACE库
-==================================
+~~~~~~~~~~~~~~~~~~
 编译MACE的静态库或者动态库。
 
-==================
 3. 转换模型
-==================
-将TensorFlow 或者 Caffe的模型转为MACE的模型.
+~~~~~~~~~~~~~~~~~~
+将TensorFlow 或者 Caffe的模型转为MACE的模型。
 
-==================================
 4.1. 部署
-==================================
+~~~~~~~~~~~~~~~~~~
 根据不同使用目的集成Build阶段生成的库文件，然后调用MACE相应的接口执行模型。
 
-==================================
 4.2. 命令行运行
-==================================
+~~~~~~~~~~~~~~~~~~
 MACE提供了命令行工具，可以在命令行运行模型，可以用来测试模型运行时间，内存占用和正确性。
 
-==================================
 4.3. Benchmark
-==================================
+~~~~~~~~~~~~~~~~~~
 MACE提供了命令行benchmark工具，可以细粒度的查看模型中所涉及的所有算子的运行时间。
 

docs/user_guide/advanced_usage.rst

-===============
 Advanced usage
 ===============
 
 This part contains the full usage of MACE.
 
----------
 Overview
 ---------
 
 As mentioned in the previous part, a model deployment file defines a case of model deployment.
-The whole building process is loading a deployment file, converting models, building MACE and packing generated files.
+The building process includes parsing model deployment file, converting models,
+building MACE core library and packing generated model libraries.
 
-----------------
 Deployment file
-----------------
+---------------
 
 
 One deployment file will generate one library normally, but if more than one ABIs are specified,
@@ -24,7 +22,8 @@ in one deployment file.
 
 * **Example**
 
-    Here is an example deployment file with two models.
+    Here is an example deployment file with two models used by
+    `MACE Android demo application <https://github.com/XiaoMi/mace/blob/master/mace/examples/android>`__.
 
     .. literalinclude:: models/demo_app_models.yml
         :language: yaml
@@ -84,8 +83,6 @@ in one deployment file.
       - [optional] The data type used for specified runtime. [fp16_fp32, fp32_fp32] for GPU, default is fp16_fp32, [fp32] for CPU and [uint8] for DSP.
     * - limit_opencl_kernel_time
       - [optional] Whether splitting the OpenCL kernel within 1 ms to keep UI responsiveness, default is 0.
-    * - nnlib_graph_mode
-      - [optional] Control the DSP precision and performance, default to 0 usually works for most cases.
     * - obfuscate
       - [optional] Whether to obfuscate the model operator name, default to 0.
     * - winograd
@@ -105,13 +102,14 @@ in one deployment file.
         sha256sum /path/to/your/file
 
 
----------------
-Advanced Usage
----------------
+Advanced usage
+--------------
 
-There are two common advanced use cases: 1. convert a model to CPP code. 2. tuning for specific SOC if use GPU.
+There are two common advanced use cases:
+  - converting model to C++ code.
+  - tuning GPU kernels for a specific SoC.
 
-* **Convert model(s) to CPP code**
+* **Convert model(s) to C++ code**
 
     .. warning::
 
@@ -119,7 +117,7 @@ There are two common advanced use cases: 1. convert a model to CPP code. 2. tuni
 
     * **1. Change the model deployment file(.yml)**
 
-        If you want to protect your model, you can convert model to CPP code. there are also two cases:
+        If you want to protect your model, you can convert model to C++ code. there are also two cases:
 
         * convert model graph to code and model weight to file with below model configuration.
 
@@ -197,10 +195,10 @@ There are two common advanced use cases: 1. convert a model to CPP code. 2. tuni
             // ... Same with the code in basic usage
 
 
-* **Tuning for specific SOC's GPU**
+* **Tuning for specific SoC's GPU**
 
     If you want to use the GPU of a specific device, you can just specify the ``target_socs`` in your YAML file and
-    then tune the MACE lib for it, which may get 1~10% performance improvement.
+    then tune the MACE lib for it (OpenCL kernels), which may get 1~10% performance improvement.
 
     * **1. Change the model deployment file(.yml)**
 
@@ -253,7 +251,7 @@ There are two common advanced use cases: 1. convert a model to CPP code. 2. tuni
           used for your models, which could accelerate the initialization stage.
           Details please refer to `OpenCL Specification <https://www.khronos.org/registry/OpenCL/sdk/1.0/docs/man/xhtml/clCreateProgramWithBinary.html>`__.
         * **mobilenet-v2-tuned_opencl_parameter.MI6.msm8998.bin** stands for the tuned OpenCL parameters
-          for the SOC.
+          for the SoC.
 
     * **4. Deployment**
         * Change the names of files generated above for not collision and push them to **your own device's directory**.
@@ -274,9 +272,8 @@ There are two common advanced use cases: 1. convert a model to CPP code. 2. tuni
             // ... Same with the code in basic usage.
 
 
-----------------
 Useful Commands
-----------------
+---------------
 * **run the model**
 
 .. code:: sh

docs/user_guide/basic_usage.rst

@@ -7,13 +7,14 @@ Build and run an example model
 
 At first, make sure the environment has been set up correctly already (refer to :doc:`../installation/env_requirement`).
 
-The followings are instructions about  how to quickly build and run a provided model in *MACE Model Zoo*.
+The followings are instructions about how to quickly build and run a provided model in
+`MACE Model Zoo <https://github.com/XiaoMi/mace-models>`__.
 
 Here we use the mobilenet-v2 model as an example.
 
 **Commands**
 
-    1. Pull *MACE* project.
+    1. Pull `MACE <https://github.com/XiaoMi/mace>`__ project.
 
     .. code:: sh
 
@@ -29,14 +30,14 @@ Here we use the mobilenet-v2 model as an example.
         It's highly recommanded to use a release version instead of master branch.
 
 
-    2. Pull *MACE Model Zoo* project.
+    2. Pull `MACE Model Zoo <https://github.com/XiaoMi/mace-models>`__ project.
 
     .. code:: sh
 
         git clone https://github.com/XiaoMi/mace-models.git
 
 
-    3. Build a general MACE library.
+    3. Build a generic MACE library.
 
     .. code:: sh
 
@@ -46,7 +47,7 @@ Here we use the mobilenet-v2 model as an example.
         bash tools/build-standalone-lib.sh
 
 
-    4. Convert the model to MACE format model.
+    4. Convert the pre-trained mobilenet-v2 model to MACE format model.
 
     .. code:: sh
 
@@ -57,7 +58,7 @@ Here we use the mobilenet-v2 model as an example.
 
     5. Run the model.
 
-    .. warning::
+    .. note::
 
         If you want to run on device/phone, please plug in at least one device/phone.
 
@@ -77,13 +78,13 @@ Here we use the mobilenet-v2 model as an example.
 Build your own model
 ---------------------
 
-This part will show you how to use your pre-trained model in MACE.
+This part will show you how to use your own pre-trained model in MACE.
 
 ======================
 1. Prepare your model
 ======================
 
-Mace now supports models from TensorFlow and Caffe (more frameworks will be supported).
+MACE now supports models from TensorFlow and Caffe (more frameworks will be supported).
 
 -  TensorFlow
 
@@ -338,4 +339,4 @@ Please refer to \ ``mace/examples/example.cc``\ for full usage. The following li
     // 6. Run the model
     MaceStatus status = engine.Run(inputs, &outputs);
 
-More details are in :doc:`advanced_usage`.
\ No newline at end of file
+More details are in :doc:`advanced_usage`.

docs/user_guide/models/demo_app_models.yml

@@ -26,7 +26,6 @@ models:
             - https://cnbj1.fds.api.xiaomi.com/mace/inputs/dog.npy
       runtime: cpu+gpu
       limit_opencl_kernel_time: 0
-      nnlib_graph_mode: 0
       obfuscate: 0
       winograd: 0
   squeezenet_v11:
@@ -46,6 +45,5 @@ models:
             - 1,1,1,1000
       runtime: cpu+gpu
       limit_opencl_kernel_time: 0
-      nnlib_graph_mode: 0
       obfuscate: 0
-      winograd: 0
\ No newline at end of file
+      winograd: 0