Add tutuorial of config #487

Ezra-Yu · 2021-10-14T11:21:27Z

Motivation

Add tutuorial of config that let user kown the name suler of config, meanning of lines in config, and how to write a config.

Modification

Add tutuorial of config in doc and doc_zh_CN

Checklist

Before PR:

Pre-commit or other linting tools are used to fix the potential lint issues.
Bug fixes are fully covered by unit tests, the case that causes the bug should be added in the unit tests.
The modification is covered by complete unit tests. If not, please add more unit test to ensure the correctness.
The documentation has been modified accordingly, like docstring or example tutorials.

After PR:

If the modification has potential influence on downstream or other related projects, this PR should be tested with those projects, like MMDet or MMSeg.
CLA has been signed and all committers have signed the CLA in this PR.

codecov · 2021-10-14T11:45:26Z

Codecov Report

Merging #487 (47666d8) into master (10e8495) will increase coverage by 0.81%.
The diff coverage is 93.54%.

❗ Current head 47666d8 differs from pull request most recent head 6f3023a. Consider uploading reports for the commit 6f3023a to get more accurate results

@@            Coverage Diff             @@
##           master     #487      +/-   ##
==========================================
+ Coverage   77.96%   78.77%   +0.81%     
==========================================
  Files         102      103       +1     
  Lines        5619     5702      +83     
  Branches      923      927       +4     
==========================================
+ Hits         4381     4492     +111     
+ Misses       1111     1088      -23     
+ Partials      127      122       -5

Flag	Coverage Δ
unittests	`78.77% <93.54%> (+0.81%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
mmcls/apis/train.py	`22.72% <0.00%> (ø)`
mmcls/models/backbones/resnet.py	`100.00% <ø> (ø)`
mmcls/models/backbones/vision_transformer.py	`93.79% <92.03%> (+16.25%)`	⬆️
mmcls/models/utils/attention.py	`98.72% <92.85%> (-1.28%)`	⬇️
mmcls/models/backbones/res2net.py	`95.50% <95.50%> (ø)`
mmcls/models/backbones/__init__.py	`100.00% <100.00%> (ø)`
mmcls/models/heads/vision_transformer_head.py	`93.18% <100.00%> (+1.28%)`	⬆️
mmcls/models/utils/__init__.py	`100.00% <100.00%> (ø)`
mmcls/utils/logger.py	`100.00% <0.00%> (+25.00%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 10e8495...6f3023a. Read the comment docs.

mzr1996 · 2021-10-22T06:54:55Z

docs/tutorials/config.md

@@ -0,0 +1,380 @@
+# Tutorial 1：Learn about Configs
+
+MMCls uses python files as configs. The design of our configuration file system integrates modularity and inheritance, facilitating users to conduct various experiments. All configuration files are placed in the `$MMCls/configs` folder, which mainly contains the original configuration folder of `_base_` and many algorithm folders such as `resnet`, `swin_transformer`, `vision_transformer`, etc.


Best to use MMClassification.
And we support not only python files, but YAML files and JSON files, which refer to mmcv docs, but the most common config format is python files.

$MMcls is confusing and not necessary.

mzr1996 · 2021-10-22T06:57:27Z

docs/tutorials/config.md

+
+## Config File Naming Convention
+
+We follow the below convention to name config files. Contributors are advised to follow the same style。The config file names are divided into four parts: model information, module information, training information and data information. Logically, different parts are concatenated by underscores `'_'`, and words in the same part are concatenated by dashes `'-'`.


。 -> .

docs/tutorials/config.md

mzr1996 · 2021-10-22T07:03:44Z

docs/tutorials/config.md

+- `seresnext101-32x4d`  : `SeResNet101` network structure, `32x4d` means that `groups` and `width_per_group` are 32 and 4 respectively in `Bottleneck`;
+
+### module information
+Refers to some special `neck`, `head` or `pretrain` information, which is commonly used as pretraining information in classification tash:


Suggested change

Refers to some special `neck`, `head` or `pretrain` information, which is commonly used as pretraining information in classification tash:

Some special `neck`, `head` and `pretrain` information. In classification tasks, `pretrain` information is the most commonly used:

mzr1996 · 2021-10-22T07:04:26Z

docs/tutorials/config.md

+- `training info`：Training information, some training schedule, including batch size, lr schedule, data augment and the like;
+- `data info`：Data information, dataset name, input size and so on, such as imagenet, cifar;
+
+### model information


Use upper case

Suggested change

### model information

### Model information

mzr1996 · 2021-10-22T07:25:11Z

docs/tutorials/config.md

+- `ft` : Configuration file for fine-tuning
+- `pt` : Configuration file for pretraining
+
+Training strategy information, the training strategy is based on the recurrence profile, and the basic training strategy does not need to be marked. However, if improvements are made on this basis, the training strategy needs to be indicated and arranged in the order, such as: `{pipeline aug}-{train aug}-{loss trick}-{scheduler}-{epochs}`


Suggested change

Training strategy information, the training strategy is based on the recurrence profile, and the basic training strategy does not need to be marked. However, if improvements are made on this basis, the training strategy needs to be indicated and arranged in the order, such as: `{pipeline aug}-{train aug}-{loss trick}-{scheduler}-{epochs}`

Training recipe. Usually, only the part that is different from the original paper will be marked. These methods will be arranged in the order `{pipeline aug}-{train aug}-{loss trick}-{scheduler}-{epochs}`.

mzr1996 · 2021-10-22T07:39:06Z

docs/tutorials/config.md

+repvgg-D2se_deploy_4xb64-autoaug-lbs-mixup-coslr-200e_in1k.py
+```
+
+Among them, `repvgg-D2se` represents algorithm information, `RepVGG` model, `D2se` is structure information; `deploy` represents module information, and this model is in the inference state; `4xb64-autoaug-lbs-mixup-coslr-200e` represents training information, 4 GPUs, the number of batches per GPU is 64, using the `auto augment`, `label smooth` and `cosine scheduler` techniques to train 200 epoches; `in1k` is the data information, which means using `224x224` input image size to train in `ImageNet1k`.


Suggested change

Among them, `repvgg-D2se` represents algorithm information, `RepVGG` model, `D2se` is structure information; `deploy` represents module information, and this model is in the inference state; `4xb64-autoaug-lbs-mixup-coslr-200e` represents training information, 4 GPUs, the number of batches per GPU is 64, using the `auto augment`, `label smooth` and `cosine scheduler` techniques to train 200 epoches; `in1k` is the data information, which means using `224x224` input image size to train in `ImageNet1k`.

- `repvgg-D2se`: Algorithm information

+ `repvgg`: The main algorithm.

+ `D2se`: The architecture.

- `deploy`: Module information, means the backbone is in the deploy state.

- `4xb64-autoaug-lbs-mixup-coslr-200e`: Training information.

+ `4xb64`: Use 4 GPUs and the size of batches per GPU is 64.

+ `autoaug`: Use `AutoAugment` in training pipeline.

+ `lbs`: Use label smoothing loss.

+ `mixup`: Use `mixup` training augment method.

+ `coslr`: Use cosine learning rate scheduler.

+ `200e`: Train the model for 200 epoches.

- `in1k`: Dataset information. The config is for `ImageNet1k` dataset and the input size is `224x224`.

mzr1996 · 2021-10-22T07:40:16Z

docs/tutorials/config.md

+
+## Config File Structure
+
+There are four kind basic component file in the `configs/_base_` folder, namely：


Suggested change

There are four kind basic component file in the `configs/_base_` folder, namely：

There are four kinds of basic component files in the `configs/_base_` folder, namely：

mzr1996 · 2021-10-22T07:48:31Z

docs/tutorials/config.md

+- [schedules](https://github.com/open-mmlab/mmclassification/tree/master/configs/_base_/schedules)
+- [default_runtime](https://github.com/open-mmlab/mmclassification/blob/master/configs/_base_/default_runtime.py)
+
+Many methods, such as ResNet, Swin_Transformer, ViT, RepVGG and etc, can be easily implemented by combining these components. The configs that are composed by components from `_base_` are called _primitive_.


Use these components to implement ResNet or Swin-Transformer? I think it's a little misleading.

Suggested change

Many methods, such as ResNet, Swin_Transformer, ViT, RepVGG and etc, can be easily implemented by combining these components. The configs that are composed by components from `_base_` are called _primitive_.

You can easily build your own training config file by inherit some base config files. And the configs that are composed by components from `_base_` are called _primitive_.

mzr1996 · 2021-10-22T07:49:33Z

docs/tutorials/config.md

+
+Many methods, such as ResNet, Swin_Transformer, ViT, RepVGG and etc, can be easily implemented by combining these components. The configs that are composed by components from `_base_` are called _primitive_.
+
+For easy understanding, we use [ResNet50 primitive config](https://github.com/open-mmlab/mmclassification/blob/master/configs/resnet/ resnet50_b32x8_imagenet.py) as a example and comment the meaning of each line. For more detaile, please refer to the API documentation.


The link is broken.

mzr1996

Please pay attention to modify the corresponding part of the Chinese documentation

mzr1996 · 2021-10-22T08:21:27Z

docs/tutorials/config.md

+
+### model
+The parameter `"model"` is a python dictionary in the configuration file, which mainly includes information such as network structure and loss function:
+- `type` ： Classifier name, MMCls supports `ImageClassifier`, refer to [API 文档](https://mmclassification.readthedocs.io/zh_CN/latest/api.html#module-mmcls.models.classifiers)。


Do we need to add a note about type? type is not an argument, but the class name. Many fresh users may confuse about it.

Change the link to English version

mzr1996 · 2021-10-22T08:22:56Z

docs/tutorials/config.md

+### model
+The parameter `"model"` is a python dictionary in the configuration file, which mainly includes information such as network structure and loss function:
+- `type` ： Classifier name, MMCls supports `ImageClassifier`, refer to [API 文档](https://mmclassification.readthedocs.io/zh_CN/latest/api.html#module-mmcls.models.classifiers)。
+- `backbone` ： Backbones name, refer to [API document](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/models/backbones) for available options.


Backbones name -> Backbone configs

mzr1996 · 2021-10-22T08:24:59Z

docs/tutorials/config.md

+    type='ImageClassifier',     # Classifier name
+    backbone=dict(
+        type='ResNet',          # Backbones name
+        depth=50,               # depth of backbone， ResNet has optionsof 18, 34, 50, 101, 152.


， -> ,
optionsof -> options of

mzr1996 · 2021-10-22T08:28:00Z

docs/tutorials/config.md

+- `train ｜ val ｜ test` : construct dataset
+  - `type`: Dataset name, MMCls supports `ImageNet`, `Cifar` etc., refer to [API documentation](https://mmclassification.readthedocs.io/zh_CN/latest/api.html#module-mmcls.datasets)
+  - `data_prefix` : Dataset root directory
+  - `pipeline` :  Data processing pipeline, refer to related tutorial documents [如何设计数据处理流水线](https://mmclassification.readthedocs.io/zh_CN/latest/tutorials/data_pipeline.html)


Change to English version

mzr1996 · 2021-10-22T08:29:57Z

docs/tutorials/config.md

+        dict(type='TextLoggerHook'),           # The Tensorboard logger is also supported
+        # dict(type='TensorboardLoggerHook')   # also support Tensorboard logger


Repeated comment

mzr1996 · 2021-10-22T08:32:51Z

docs/tutorials/config.md

+
+### Use some fields in the base configs
+
+Sometimes, you can refer to some fields in the `__base__` config, so as to avoid duplication of definitions. You can refer to [mmcv](https://mmcv.readthedocs.io/en/latest/understand_mmcv/config.html#reference-variables-from-base) for some more instructions.


_base_ instead of __base__

mzr1996 · 2021-10-22T08:36:07Z

docs/tutorials/config.md

+
+Sometimes, you can refer to some fields in the `__base__` config, so as to avoid duplication of definitions. You can refer to [mmcv](https://mmcv.readthedocs.io/en/latest/understand_mmcv/config.html#reference-variables-from-base) for some more instructions.
+
+The following is a example of using `auto augment` in the training data preprocessing pipeline， refer to ["configs/_base_/datasets/imagenet_bs64_autoaug.py"](https://github.com/open-mmlab/mmclassification/blob/master/configs/_base_/datasets/imagenet_bs64_autoaug.py). When defining `train_pipeline`, just add the definition file name of `auto augment` to `__base__`, and then use `{{_base_.auto_increasing_policies}}` to reference the variables:


Suggested change

The following is a example of using `auto augment` in the training data preprocessing pipeline， refer to ["configs/_base_/datasets/imagenet_bs64_autoaug.py"](https://github.com/open-mmlab/mmclassification/blob/master/configs/_base_/datasets/imagenet_bs64_autoaug.py). When defining `train_pipeline`, just add the definition file name of `auto augment` to `__base__`, and then use `{{_base_.auto_increasing_policies}}` to reference the variables:

The following is an example of using `auto augment` in the training data preprocessing pipeline， refer to [`configs/_base_/datasets/imagenet_bs64_autoaug.py`](https://github.com/open-mmlab/mmclassification/blob/master/configs/_base_/datasets/imagenet_bs64_autoaug.py). When defining `train_pipeline`, just add the definition file name of `auto augment` to `_base_`, and then use `{{_base_.auto_increasing_policies}}` to reference the variables:

If use quotes, _base_ will be rendered as base.

mzr1996 · 2021-10-22T09:05:18Z

docs/tutorials/config.md

+- `type` ： Classifier name, MMCls supports `ImageClassifier`, refer to [API 文档](https://mmclassification.readthedocs.io/zh_CN/latest/api.html#module-mmcls.models.classifiers)。
+- `backbone` ： Backbones name, refer to [API document](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/models/backbones) for available options.
+- `neck` ：Neck network name, MMCls supports `GlobalAveragePooling`, please refer to [API documentation](https://mmclassification.readthedocs.io/zh_CN/latest/api.html#module-mmcls.models.necks).
+-`head`: Head network name, MMCls supports single-label and multi-label classification head networks, available options refer to [API 文档](https://github.com/open-mmlab/mmclassification/blob/master/mmcls/models/heads).


Change to English version

mzr1996 · 2021-10-26T05:34:27Z

docs/tutorials/config.md

@@ -0,0 +1,403 @@
+# Tutorial 1：Learn about Configs


Use ':' instead of "："

docs/tutorials/config.md

docs_zh-CN/tutorials/config.md

Co-authored-by: Ma Zerun <[email protected]>

mzr1996

LGTM

* add cn tutorials/config.md * add heads api and doc title link * Update tutorials index * Update tutorials index * Update config.md * add english version * Update config.md * Update docs * Update css * Update docs/tutorials/config.md Co-authored-by: Ma Zerun <[email protected]> * Update docs_zh-CN/tutorials/config.md Co-authored-by: Ma Zerun <[email protected]> * modify according to suggestion * Use GitHub style `code` css * change some mmcv API link to CN version * remove default in default_runtime Co-authored-by: mzr1996 <[email protected]>

Ezra-Yu added 5 commits October 14, 2021 18:05

add cn tutorials/config.md

f1f485f

add heads api and doc title link

a6b0bdb

Merge remote-tracking branch 'mmcls/master' into config

076ad61

Update tutorials index

6e0de56

Update tutorials index

e66e8e7

Ezra-Yu added 3 commits October 14, 2021 20:04

Update config.md

3165223

add english version

eb39620

Update config.md

15e80ad

Ezra-Yu changed the title ~~[WIP] Add tutuorial of config~~ Add tutuorial of config Oct 19, 2021

Ezra-Yu requested a review from mzr1996 October 19, 2021 10:05

mzr1996 requested changes Oct 22, 2021

View reviewed changes

Update docs

fa761e5

mzr1996 requested changes Oct 26, 2021

View reviewed changes

mzr1996 and others added 8 commits October 26, 2021 14:20

Update css

89b19ae

Update docs/tutorials/config.md

96f79dd

Co-authored-by: Ma Zerun <[email protected]>

Update docs_zh-CN/tutorials/config.md

1697cbc

Co-authored-by: Ma Zerun <[email protected]>

modify according to suggestion

0ee46f1

Use GitHub style code css

8cba200

change some mmcv API link to CN version

79dae70

Merge remote-tracking branch 'origin/config' into config

7e01074

remove default in default_runtime

6f3023a

mzr1996 approved these changes Oct 26, 2021

View reviewed changes

mzr1996 merged commit 3a35b6f into open-mmlab:master Oct 26, 2021

Ezra-Yu deleted the config branch October 27, 2021 03:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add tutuorial of config #487

Add tutuorial of config #487

Ezra-Yu commented Oct 14, 2021 •

edited

Loading

codecov bot commented Oct 14, 2021 •

edited

Loading

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 left a comment

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 22, 2021

mzr1996 Oct 26, 2021

Ezra-Yu Oct 26, 2021

mzr1996 left a comment

		@@ -0,0 +1,380 @@
		# Tutorial 1：Learn about Configs

		MMCls uses python files as configs. The design of our configuration file system integrates modularity and inheritance, facilitating users to conduct various experiments. All configuration files are placed in the `$MMCls/configs` folder, which mainly contains the original configuration folder of `_base_` and many algorithm folders such as `resnet`, `swin_transformer`, `vision_transformer`, etc.


		## Config File Naming Convention

		We follow the below convention to name config files. Contributors are advised to follow the same style。The config file names are divided into four parts: model information, module information, training information and data information. Logically, different parts are concatenated by underscores `'_'`, and words in the same part are concatenated by dashes `'-'`.

	Refers to some special `neck`, `head` or `pretrain` information, which is commonly used as pretraining information in classification tash:
	Some special `neck`, `head` and `pretrain` information. In classification tasks, `pretrain` information is the most commonly used:

	Training strategy information, the training strategy is based on the recurrence profile, and the basic training strategy does not need to be marked. However, if improvements are made on this basis, the training strategy needs to be indicated and arranged in the order, such as: `{pipeline aug}-{train aug}-{loss trick}-{scheduler}-{epochs}`
	Training recipe. Usually, only the part that is different from the original paper will be marked. These methods will be arranged in the order `{pipeline aug}-{train aug}-{loss trick}-{scheduler}-{epochs}`.

-Among them, `repvgg-D2se` represents algorithm information, `RepVGG` model, `D2se` is structure information; `deploy` represents module information, and this model is in the inference state; `4xb64-autoaug-lbs-mixup-coslr-200e` represents training information, 4 GPUs, the number of batches per GPU is 64, using the `auto augment`, `label smooth` and `cosine scheduler` techniques to train 200 epoches; `in1k` is the data information, which means using `224x224` input image size to train in `ImageNet1k`.
+- `repvgg-D2se`:  Algorithm information
+  + `repvgg`: The main algorithm.
+  + `D2se`: The architecture.
+- `deploy`: Module information, means the backbone is in the deploy state.
+- `4xb64-autoaug-lbs-mixup-coslr-200e`: Training information.
+  + `4xb64`: Use 4 GPUs and the size of batches per GPU is 64.
+  + `autoaug`: Use `AutoAugment` in training pipeline.
+  + `lbs`: Use label smoothing loss.
+  + `mixup`: Use `mixup` training augment method.
+  + `coslr`: Use cosine learning rate scheduler.
+  + `200e`: Train the model for 200 epoches.
+- `in1k`: Dataset information. The config is for `ImageNet1k` dataset and the input size is `224x224`.


		## Config File Structure

		There are four kind basic component file in the `configs/_base_` folder, namely：

	There are four kind basic component file in the `configs/_base_` folder, namely：
	There are four kinds of basic component files in the `configs/_base_` folder, namely：

	Many methods, such as ResNet, Swin_Transformer, ViT, RepVGG and etc, can be easily implemented by combining these components. The configs that are composed by components from `_base_` are called _primitive_.
	You can easily build your own training config file by inherit some base config files. And the configs that are composed by components from `_base_` are called _primitive_.


		Many methods, such as ResNet, Swin_Transformer, ViT, RepVGG and etc, can be easily implemented by combining these components. The configs that are composed by components from `_base_` are called _primitive_.

		For easy understanding, we use [ResNet50 primitive config](https://github.com/open-mmlab/mmclassification/blob/master/configs/resnet/ resnet50_b32x8_imagenet.py) as a example and comment the meaning of each line. For more detaile, please refer to the API documentation.

		dict(type='TextLoggerHook'), # The Tensorboard logger is also supported
		# dict(type='TensorboardLoggerHook') # also support Tensorboard logger


		### Use some fields in the base configs

		Sometimes, you can refer to some fields in the `__base__` config, so as to avoid duplication of definitions. You can refer to [mmcv](https://mmcv.readthedocs.io/en/latest/understand_mmcv/config.html#reference-variables-from-base) for some more instructions.


		Sometimes, you can refer to some fields in the `__base__` config, so as to avoid duplication of definitions. You can refer to [mmcv](https://mmcv.readthedocs.io/en/latest/understand_mmcv/config.html#reference-variables-from-base) for some more instructions.

		The following is a example of using `auto augment` in the training data preprocessing pipeline， refer to ["configs/_base_/datasets/imagenet_bs64_autoaug.py"](https://github.com/open-mmlab/mmclassification/blob/master/configs/_base_/datasets/imagenet_bs64_autoaug.py). When defining `train_pipeline`, just add the definition file name of `auto augment` to `__base__`, and then use `{{_base_.auto_increasing_policies}}` to reference the variables:

Add tutuorial of config #487

Add tutuorial of config #487

Conversation

Ezra-Yu commented Oct 14, 2021 • edited Loading

Motivation

Modification

Checklist

codecov bot commented Oct 14, 2021 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mzr1996 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mzr1996 left a comment

Choose a reason for hiding this comment

Ezra-Yu commented Oct 14, 2021 •

edited

Loading

codecov bot commented Oct 14, 2021 •

edited

Loading