Merge pull request #145 from shippingwang/add_tutorial_en_doc

add tutorial en doc

docs/en/tutorials/config.md

+#Configuration
+
+---
+
+## Introduction
+
+This document introduces the configuration(filed in config/*.yaml) of PaddleClas.
+
+## Filed in config/*.yaml
+
+### Basic
+
+| name | detail | default value | optional value |
+|:---:|:---:|:---:|:---:|
+| mode | mode | "train" | ["train"," valid"] |
+| architecture | model name | "ResNet50_vd" | one of 23 architectures |
+| pretrained_model | pretrained model path | "" | Str |
+| model_save_dir | model stored path | "" | Str |
+| classes_num | class number | 1000 | int |
+| total_images | total images | 1281167 | int |
+| save_interval | save interval | 1 | int |
+| validate | whether to validate when training | TRUE | bool |
+| valid_interval | valid interval | 1 | int |
+| epochs | epoch |  | int |
+| topk | K value | 5 | int |
+| image_shape | image size | [3，224，224] | list, shape: (3,) |
+| use_mix | whether to use mixup | False | ['True', 'False'] |
+| ls_epsilon | label_smoothing epsilon value| 0 | float |
+
+### Optimizer & Learning rate
+
+learning rate
+
+| name | detail | default value |Optional value |
+|:---:|:---:|:---:|:---:|
+| function | decay type | "Linear" | ["Linear", "Cosine", <br> "Piecewise", "CosineWarmup"] |
+| params.lr | initial learning rate | 0.1 | float |
+| params.decay_epochs | milestone in piecewisedecay |  | list |
+| params.gamma | gamma in piecewisedecay | 0.1 | float |
+| params.warmup_epoch | warmup epoch | 5 | int |
+| parmas.steps | decay steps in lineardecay | 100 | int |
+| params.end_lr | end lr in lineardecay | 0 | float |
+
+optimizer
+
+| name | detail | default value | optional value |
+|:---:|:---:|:---:|:---:|
+| function | optimizer name | "Momentum" | ["Momentum", "RmsProp"] |
+| params.momentum | momentum value | 0.9 | float |
+| regularizer.function | regularizer method name | "L2" | ["L1", "L2"] |
+| regularizer.factor | regularizer factor | 0.0001 | float |
+
+### reader
+
+| name | detail |
+|:---:|:---:|
+| batch_size | batch size |
+| num_workers | worker number |
+| file_list | train list path |
+| data_dir | train  dataset path |
+| shuffle_seed | seed |
+
+processing
+
+| function name | attribute name | detail |
+|:---:|:---:|:---:|
+| DecodeImage | to_rgb | decode to RGB |
+|  | to_np | to numpy |
+|  | channel_first | Channel first |
+| RandCropImage | size | random crop |
+| RandFlipImage | | random flip |
+| NormalizeImage | scale | normalize image |
+|  | mean | mean |
+|  | std | std |
+|  | order | order |
+| ToCHWImage |  | to CHW |
+| CropImage | size | crop size |
+| ResizeImage | resize_short | resize according to short size |
+
+mix preprocessing
+
+| name| detail|
+|:---:|:---:|
+| MixupOperator.alpha | alpha value in mixup|

docs/en/tutorials/data.md

+# Data
+
+---
+
+## 1. Introducation
+This document introduces the preparation of ImageNet1k and flowers102
+
+## 2. Dataset
+
+Dataset | train dataset size | valid dataset size | category |
+:------:|:---------------:|:---------------------:|:--------:|
+[flowers102](https://www.robots.ox.ac.uk/~vgg/data/flowers/102/)|1k | 6k | 102 |
+[ImageNet1k](http://www.image-net.org/challenges/LSVRC/2012/)|1.2M| 50k | 1000 |
+
+* Data format
+
+Please follow the steps mentioned below to organize data, include train_list.txt and val_list.txt
+
+```shell
+# delimiter: "space"
+
+ILSVRC2012_val_00000001.JPEG 65
+...
+
+```
+### ImageNet1k
+After downloading data, please organize the data dir as below
+
+```bash
+PaddleClas/dataset/imagenet/
+|_ train/
+|  |_ n01440764
+|  |  |_ n01440764_10026.JPEG
+|  |  |_ ...
+|  |_ ...
+|  |
+|  |_ n15075141
+|     |_ ...
+|     |_ n15075141_9993.JPEG
+|_ val/
+|  |_ ILSVRC2012_val_00000001.JPEG
+|  |_ ...
+|  |_ ILSVRC2012_val_00050000.JPEG
+|_ train_list.txt
+|_ val_list.txt
+```
+### Flowers102 Dataset
+
+Download [Data](https://www.robots.ox.ac.uk/~vgg/data/flowers/102/) then decompress:
+
+```shell
+jpg/
+setid.mat
+imagelabels.mat
+```
+
+Please put all the files under ```PaddleClas/dataset/flowers102```
+
+generate generate_flowers102_list.py and train_list.txt和val_list.txt
+
+```bash
+python generate_flowers102_list.py jpg train > train_list.txt
+python generate_flowers102_list.py jpg valid > val_list.txt
+
+```
+
+Please organize data dir as below
+
+```bash
+PaddleClas/dataset/flowers102/
+|_ jpg/
+|  |_ image_03601.jpg
+|  |_ ...
+|  |_ image_02355.jpg
+|_ train_list.txt
+|_ val_list.txt
+```

docs/en/tutorials/getting_started.md

+# Getting Started
+---
+Please refer to [Installation](install.md) to setup environment at first, and prepare ImageNet1K data by following the instruction mentioned in the [data](data.md)
+
+## Setup
+
+**Setup PYTHONPATH：**
+
+```bash
+export PYTHONPATH=path_to_PaddleClas:$PYTHONPATH
+```
+
+## Training and validating
+
+PaddleClas support `tools/train.py` and `tools/eval.py` to start training and validating.
+
+### Training
+
+```bash
+# PaddleClas use paddle.distributed.launch to start multi-cards and multiprocess training.
+# Set FLAGS_selected_gpus to indicate GPU cards
+
+python -m paddle.distributed.launch \
+    --selected_gpus="0,1,2,3" \
+    tools/train.py \
+        -c ./configs/ResNet/ResNet50_vd.yaml
+```
+
+- log:
+
+```
+epoch:0    train    step:13    loss:7.9561    top1:0.0156    top5:0.1094    lr:0.100000    elapse:0.193
+```
+
+add -o params to update configuration
+
+```bash
+python -m paddle.distributed.launch \
+    --selected_gpus="0,1,2,3" \
+    tools/train.py \
+        -c ./configs/ResNet/ResNet50_vd.yaml \
+        -o use_mix=1 \
+    --vdl_dir=./scalar/
+
+```
+
+- log:
+
+```
+epoch:0    train    step:522    loss:1.6330    lr:0.100000    elapse:0.210
+```
+
+or modify configuration directly to config fileds, please refer to [config](config.md) for more details.
+
+use visuldl to visulize training loss in the real time
+
+```bash
+visualdl --logdir ./scalar --host <host_IP> --port <port_num>
+
+```
+
+
+### finetune
+
+* please refer to [Trial](./quick_start.md) for more details.
+
+### validating
+
+```bash
+python tools/eval.py \
+    -c ./configs/eval.yaml \
+    -o ARCHITECTURE.name="ResNet50_vd" \
+    -o pretrained_model=path_to_pretrained_models
+
+modify `configs/eval.yaml filed: `ARCHITECTURE.name` and filed: `pretrained_model` to config valid model or add -o params to update config directly.
+
+
+**NOTE: ** when loading the pretrained model, should ignore the suffix ```.pdparams```
+
+## Predict
+
+PaddlePaddle supprot three predict interfaces
+Use predicator interface to predict
+First, export inference model
+
+```bash
+python tools/export_model.py \
+    --model=model_name \
+    --pretrained_model=pretrained_model_dir \
+    --output_path=save_inference_dir
+
+```
+Second, start predicator enginee：
+
+```bash
+python tools/infer/predict.py \
+    -m model_path \
+    -p params_path \
+    -i image path \
+    --use_gpu=1 \
+    --use_tensorrt=True
+```
+please refer to [inference](../extension/paddle_inference.md) for more details.

docs/en/tutorials/index.rst

@@ -5,5 +5,7 @@ tutorials
    :maxdepth: 1
    
    install.md
+   quick_start.md
+   data.md
    getting_started.md
    config.md

docs/en/tutorials/install.md

+# Installation
+
+---
+
+## Introducation
+
+This document introduces how to install PaddleClas and its requirements.
+
+## Install PaddlePaddle
+
+Python 3.5, CUDA 9.0, CUDNN7.0 nccl2.1.2 and later version are required at first, For now, PaddleClas only support training on the GPU device. Please follow the instructions in the [Installation](http://www.paddlepaddle.org.cn/install/quick) if the PaddlePaddle on the device is lower than v1.7
+
+Install PaddlePaddle
+
+```bash
+pip install paddlepaddle-gpu --upgrade
+```
+
+or compile from source code, please refer to [Installation](http://www.paddlepaddle.org.cn/install/quick).
+
+Verify Installation
+
+```python
+import paddle.fluid as fluid
+fluid.install_check.run_check()
+```
+
+Check PaddlePaddle version：
+
+```bash
+python -c "import paddle; print(paddle.__version__)"
+```
+
+Note:
+- Make sure the compiled version is later than v1.7
+- Indicate **WITH_DISTRIBUTE=ON** when compiling, Please refer to [Instruction](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/install/Tables.html#id3) for more details.
+
+
+## Install PaddleClas
+
+**Clone PaddleClas: **
+
+```
+cd path_to_clone_PaddleClas
+git clone https://github.com/PaddlePaddle/PaddleClas.git
+```
+
+**Install requirements**
+
+
+```
+pip install --upgrade -r requirements.txt
+```

docs/en/tutorials/quick_start.md

+# Trial in 30mins
+
+Based on the flowers102 dataset, it takes only 30 mins to experience PaddleClas, include training varieties of backbone and pretrained model, SSLD distillation, and multiple data augmentation, Please refer to [Installation](install.md) to install at first.
+
+
+## Preparation
+
+* enter insatallation dir
+
+```
+cd path_to_PaddleClas
+```
+
+* enter `dataset/flowers102`, download and decompress flowers102 dataset.
+
+```shell
+cd dataset/flowers102
+wget https://www.robots.ox.ac.uk/~vgg/data/flowers/102/102flowers.tgz
+wget https://www.robots.ox.ac.uk/~vgg/data/flowers/102/imagelabels.mat
+wget https://www.robots.ox.ac.uk/~vgg/data/flowers/102/setid.mat
+tar -xf 102flowers.tgz
+```
+
+* create train/val/test label files
+
+```shell
+python generate_flowers102_list.py jpg train > train_list.txt
+python generate_flowers102_list.py jpg valid > val_list.txt
+python generate_flowers102_list.py jpg test > extra_list.txt
+cat train_list.txt extra_list.txt > train_extra_list.txt
+```
+
+**Note:** In order to offer more data to SSLD training task, train_list.txt and extra_list.txt will merge into train_extra_list.txft
+
+* return `PaddleClas` dir
+
+```
+cd ../../
+```
+
+## Environment
+
+### Set PYTHONPATH
+
+```bash
+export PYTHONPATH=./:$PYTHONPATH
+```
+
+### Download pretrained model
+
+
+```bash
+python tools/download.py -a ResNet50_vd -p ./pretrained -d True
+python tools/download.py -a ResNet50_vd_ssld -p ./pretrained -d True
+python tools/download.py -a MobileNetV3_large_x1_0 -p ./pretrained -d True
+```
+
+Paramters：
++ `architecture`(shortname: a): model name.
++ `path`(shortname: p) download path.
++ `decompress`(shortname: d) whether to decompress.
+
+
+
+* All experiments are running on the NVIDIA® Tesla® V100 sigle card.
+
+
+## Training
+
+### Train from scratch
+
+* Train ResNet50_vd
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/ResNet50_vd.yaml
+
+```
+
+The validation `Top1 Acc` curve is showmn below.
+
+![](../../images/quick_start/r50_vd_acc.png)
+
+
+### Finetune - ResNet50_vd pretrained model (Acc 79.12\%)
+
+* finetune ResNet50_vd_ model pretrained on the 1000-class Imagenet dataset
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/ResNet50_vd_finetune.yaml
+
+```
+
+The validation `Top1 Acc` curve is shown below
+
+![](../../images/quick_start/r50_vd_pretrained_acc.png)
+
+Compare with training from scratch, it improve by 65\% to 94.02\%
+
+
+### SSLD finetune - ResNet50_vd_ssld pretrained model (Acc 82.39\%)
+
+Note: when finetuning model, which has been trained by SSLD, please use smaller learning rate in the middle of net.
+
+```yaml
+ARCHITECTURE:
+    name: 'ResNet50_vd'
+    params:
+        lr_mult_list: [0.1, 0.1, 0.2, 0.2, 0.3]
+pretrained_model: "./pretrained/ResNet50_vd_ssld_pretrained"
+```
+
+Tringing script
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/ResNet50_vd_ssld_finetune.yaml
+```
+
+Compare with finetune on the 79.12% pretrained model, it improve by 0.9% to 95%.
+
+
+### More architecture - MobileNetV3
+
+Training script
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/MobileNetV3_large_x1_0_finetune.yaml
+```
+
+Compare with ResNet50_vd pretrained model, it decrease by 5% to 90%. Different architecture generates different performance, actually it is a task-oriented decision to apply the best performance model, should consider the inference time, storage, heterogeneous device, etc.
+
+
+### RandomErasing
+
+Data augmentation works when training data is small.
+
+Training script
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/ResNet50_vd_ssld_random_erasing_finetune.yaml
+```
+
+It improves by 1.27\% to 96.27\%
+
+* Save ResNet50_vd pretrained model to experience next chapter.
+
+```shell
+cp -r output/ResNet50_vd/19/  ./pretrained/flowers102_R50_vd_final/
+```
+
+### Distillation
+
+* Use extra_list.txt as unlabeled data, Note:
+    * Samples in the `extra_list.txt` and `val_list.txt` don't have intersection
+    * Because of in the source code, label information is unused, This is still unlabeled distillation
+    * Teacher model use the pretrained_model trained on the flowers102 dataset, and student model use the MobileNetV3_large_x1_0 pretrained model(Acc 75.32\%) trained on the ImageNet1K dataset
+
+
+```yaml
+total_images: 7169
+ARCHITECTURE:
+    name: 'ResNet50_vd_distill_MobileNetV3_large_x1_0'
+pretrained_model:
+    - "./pretrained/flowers102_R50_vd_final/ppcls"
+    - "./pretrained/MobileNetV3_large_x1_0_pretrained/”
+TRAIN:
+    file_list: "./dataset/flowers102/train_extra_list.txt"
+```
+
+Final training script
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/R50_vd_distill_MV3_large_x1_0.yaml
+```
+
+It significantly imporve by 6.47% to 96.47% with more unlabeled data and teacher model.
+
+### All accuracy
+
+
+|Configuration | Top1 Acc |
+|- |:-: |
+| ResNet50_vd.yaml | 0.2735 |
+| MobileNetV3_large_x1_0_finetune.yaml | 0.9000 |
+| ResNet50_vd_finetune.yaml | 0.9402 |
+| ResNet50_vd_ssld_finetune.yaml | 0.9500 |
+| ResNet50_vd_ssld_random_erasing_finetune.yaml | 0.9627 |
+| R50_vd_distill_MV3_large_x1_0.yaml | 0.9647 |
+
+
+The whole accuracy curves are shown below
+
+
+![](../../images/quick_start/all_acc.png)
+
+
+
+* **NOTE**: As flowers102 is a small dataset, validatation accuracy maybe float 1%.
+
+* Please refer to [Getting_started](./getting_started) for more details