add add_new_algorithm.md

docs/zh_CN/community/add_new_algorithm.md

+# 添加新算法
+
+PaddleClas 将一个算法分解为以下几个部分，并对各部分进行模块化处理，方便快速组合出新的算法。
+- [1. 添加算法可能改动的模块](#1)
+  -[1.1 数据加载和处理](#1)
+  -[1.2. 网络](#2)
+  -[1.3. 后处理](#3)
+  -[1.4. 损失函数](#4)
+  -[1.5. 指标评估](#5)
+  -[1.6. 优化器](#6)
+- [2. 合入PaddleClas套件必须新增的模块](#2)
+  -[2.1 文档](#2.1)
+  -[2.2 TIPC](#2.2)
+
+
+<a name="1"></a>
+
+## 1. 添加算法可能改动的模块
+
+
+<a name="1.1"></a>
+
+### 1.1 数据加载和处理
+
+数据加载和处理由不同的模块(module)组成，其完成了图片的读取、数据增强和label的制作。这一部分在[ppcls/data](../../../ppcls/data)下。 各个文件及文件夹作用说明如下:
+
+```bash
+ppcls/data/
+├── dataloader #  数据读取、采样模块
+│   ├── xxx_dataset.py # 数据读取模块
+│   ├── xxx_sampler.py # 数据采样模块
+│   ├── ......
+├── __init__.py
+├── postprocess # 模型后处理
+│   ├── threshoutput.py # 对结果的卡阈值后处理
+│   ├── topk.py # Topk后处理
+│   ├── ......
+├── preprocess # 模型前处理，通常指数据预处理
+│   ├── batch_ops # batch 维度图像预处理
+│   │   ├── batch_operators.py
+│   │   └── __init__.py
+│   ├── __init__.py
+│   └── ops # 数据增强模块
+│       ├── operators.py # 常见的数据预处理
+│       ├── randaugment.py # 随机增强预处理
+│       └── ......
+└── utils
+    └── get_image_list.py # 将文件夹中的图片文件转换为img list
+```
+
+PaddleClas 内置了大量图像操作相关模块，对于没有内置的模块可通过如下步骤添加:
+
+1. 如果只涉及单个图像的操作，在 [ppcls/data/preprocess/ops](../../../ppcls/data/preprocess/ops) 文件夹下新建文件，如果设计整个batch的图像操作，需要在 [ppcls/data/preprocess/batch_ops](../../../ppcls/data/preprocess/batch_ops) 文件夹下新建文件，如my_module.py。
+2. 在 my_module.py 文件内添加相关代码，示例代码如下:
+
+```python
+class MyModule:
+    def __init__(self, *args, **kwargs):
+        # your init code
+        pass
+
+    def __call__(self, img):
+        # your process code
+        return img
+```
+
+3. 在 [ppcls/data/preprocess/\_\_init\_\_.py](../../../ppcls/data/preprocess/__init__.py) 文件内导入添加的模块。
+
+数据处理的所有处理步骤由不同的模块顺序执行而成，在config文件中按照列表的形式组合并执行。如:
+
+```yaml
+# angle class data process
+transforms:
+  - DecodeImage: # load image
+      img_mode: BGR
+      channel_first: False
+  - MyModule:
+      args1: args1
+      args2: args2
+```
+
+<a name="1.2"></a>
+
+### 1.2 网络
+
+网络部分完成了网络的组网操作，，这一部分在[ppcls/arch/](../../../ppcls/arch/)下。 进入网络的数据将按照顺序(transforms->backbones->
+necks->heads)依次通过这四个部分。其中，非特征模型的neck和head为空。
+
+```bash
+ppcls/arch/
+├── backbone
+│   ├── base # PaddleClas精选模型继承的基类，负责对网络结构的自定义后处理修改
+│   │   └── theseus_layer.py
+│   ├── legendary_models # PaddleClas 精选的backbone
+│   │   ├── pp_lcnet.py
+│   │   ├── resnet.py
+│   │   ├── swin_transformer.py
+│   │   ├── ...
+│   ├── model_zoo # PaddleClas 常见的 backbone
+│   │   ├── alexnet.py
+│   │   ├── efficientnet.py
+│   │   ├── ......
+│   └── variant_models # 模型变种模块
+│       ├── pp_lcnetv2_variant.py
+│       └── vgg_variant.py
+├── distill # 蒸馏模块
+│   └── afd_attention.py
+├── gears # 识别模型的neck、head 模块
+│   ├── arcmargin.py
+│   └── ......
+├── slim # 模型压缩模块
+└── utils.py
+```
+
+PaddleClas内置了大量的常见的backbone、识别模型的neck、head模块，对于没有内置的模块可通过如下步骤添加，所有模块添加步骤相似，以backbone为例:
+
+1. 在 [ppcls/arch/backbone/model_zoo/](../../../ppcls/arch/backbone/model_zoo/) 文件夹下新建文件，如my_backbone.py。
+2. 在 my_backbone.py 文件内添加相关代码，示例代码如下:
+
+```python
+import paddle
+import paddle.nn as nn
+import paddle.nn.functional as F
+
+
+class MyBackbone(nn.Layer):
+    def __init__(self, *args, **kwargs):
+        super(MyBackbone, self).__init__()
+        # your init code
+        self.conv = nn.xxxx
+
+    def forward(self, inputs):
+        # your network forward
+        y = self.conv(inputs)
+        return y
+```
+
+3. 在 [ppcls/arch/backbone/\_\_init\_\_.py](../../../ppcls/arch/backbone/__init__.py)文件内导入添加的模块。
+
+在完成网络的模块添加之后，只需要配置文件中进行配置即可使用，如:
+
+```yaml
+# model architecture
+Arch:
+  name: MyBackbone
+  class_num: your_class_num
+```
+
+<a name="1.3"></a>
+
+### 1.3 后处理
+
+后处理实现对模型结果的输出处理。这一部分在[ppcls/data/postprocess/](../../../ppcls/data/postprocess/)下。
+PaddleClas内置了topk、threshoutput、attr_rec等后处理模块，对于没有内置的组件可通过如下步骤添加:
+
+1. 在 [ppcls/data/postprocess/](../../../ppcls/data/postprocess/) 文件夹下新建文件，如 my_postprocess.py。
+2. 在 my_postprocess.py 文件内添加相关代码，示例代码如下:
+
+```python
+import paddle
+
+
+class MyPostProcess:
+    def __init__(self, *args, **kwargs):
+        # your init code
+        pass
+
+    def __call__(self, preds, label=None, *args, **kwargs):
+        if isinstance(preds, paddle.Tensor):
+            preds = preds.numpy()
+        # you preds decode code
+        preds = self.decode_preds(preds)
+        if label is None:
+            return preds
+        # you label decode code
+        label = self.decode_label(label)
+        return preds, label
+
+    def decode_preds(self, preds):
+        # you preds decode code
+        pass
+
+    def decode_label(self, preds):
+        # you label decode code
+        pass
+```
+
+3. 在 [ppcls/data/postprocess/\_\_init\_\_.py](../../../ppcls/data/postprocess/__init__.py)文件内导入添加的模块。
+
+在后处理模块添加之后，只需要配置文件中进行配置即可使用，如:
+
+```yaml
+Infer:
+  PostProcess:
+    args1: args1
+    args2: args2
+  
+```
+
+**备注：** 该模块只在infer时使用。
+
+<a name="1.4"></a>
+
+### 1.4 损失函数
+
+损失函数用于计算网络输出和label之间的距离。这一部分在[ppcls/loss/](../../../ppcls/loss/)下。
+PaddleClas内置了CE Loss、BCELoss、TripletLoss等十多种损失函数，对于没有内置的模块可通过如下步骤添加:
+
+1. 在 [ppcls/loss/](../../../ppcls/loss/) 文件夹下新建文件，如 my_loss.py。
+2. 在 my_loss.py 文件内添加相关代码，示例代码如下:
+
+```python
+import paddle
+from paddle import nn
+
+
+class MyLoss(nn.Layer):
+    def __init__(self, **kwargs):
+        super().__init__()
+        # you init code
+        pass
+        
+    def loss(self, **kwargs):
+        your loss code
+        pass
+
+    def forward(self, x, label):
+        loss = self.loss(input=predicts, label=label)
+        return {'your loss name': loss}
+```
+
+3. 在 [ppcls/loss/\__init\__.py](../../../ppcls/loss/__init__.py)文件内导入添加的模块。
+
+在损失函数添加之后，只需要配置文件中进行配置即可使用，如:
+
+```yaml
+Loss:
+  Train:
+    - MyLoss:
+        weight: 1.0
+```
+
+**备注：** weight是指该Loss占总Loss的权重，此处支持多个Loss同时计算。
+
+<a name="1.5"></a>
+
+### 1.5 指标评估
+
+指标评估用于计算网络在当前batch上的性能。这一部分在[ppcls/metric/](../../../ppcls/metric/)下。 PaddleClas内置了图像单标签分类、图像多标签分类、图像识别等算法相关的指标评估模块，对于没有内置的模块可通过如下步骤添加:
+
+1. 在 [ppcls/metric/](../../../ppcls/metric/) 文件夹下新建文件，如my_metric.py。
+2. 在 my_metric.py 文件内添加相关代码，示例代码如下:
+
+```python
+
+class MyMetric(nn.Layer):
+    def __init__(self, **kwargs):
+        super().__init__()
+        # you init code
+        pass
+
+    def forward(self, preds, batch, *args, **kwargs):
+        metric = self.get_metric(preds, batch, *args, **kwargs)
+        return {'your metric name':  metric}
+
+    def get_metric(self, *args, **kwargs):
+        # you metric code
+        pass
+
+```
+
+3. 在 [ppcls/metric/\_\_init\_\_.py](../../../ppcls/metric/__init__.py)文件内导入添加的模块。
+
+在指标评估模块添加之后，只需要配置文件中进行配置即可使用，如:
+
+```yaml
+Metric:
+  Train:
+    - MyMetric:
+        args: args
+  Eval:
+    - MyMetric:
+        args: args
+```
+
+<a name="1.6"></a>
+
+### 1.6 优化器
+
+优化器用于训练网络。优化器内部还包含了网络正则化和学习率衰减模块。 这一部分在[ppcls/optimizer/](../../ppcls/optimizer/)下。 PaddleClas内置了`Momentum`,`SGD`
+,`Adam`和`AdamW`等常用的优化器模块，`Constant`、`Linear`,`Cosine`,`Step`和`Piecewise`等常用的学习率衰减模块。
+
+对于没有内置的模块可通过如下步骤添加，以`optimizer`为例:
+
+1. 在 [ppcls/optimizer//optimizer.py](../../../ppcls/optimizer//optimizer.py) 文件内创建自己的优化器，示例代码如下:
+
+```python
+from paddle import optimizer as optim
+
+
+class MyOptim(object):
+    def __init__(self, learning_rate=0.001, *args, **kwargs):
+        super().__init__()
+        self.learning_rate = learning_rate
+        # you init code
+        pass
+        ：
+    def __call__(self, parameters):
+        # It is recommended to wrap the built-in optimizer of paddle
+        opt = optim.XXX(
+            learning_rate=self.learning_rate,
+            parameters=parameters)
+        return opt
+
+```
+
+在优化器模块添加之后，只需要配置文件中进行配置即可使用，如:
+
+```yaml
+Optimizer:
+  name: MyOptim
+  args1: args1
+  args2: args2
+  lr:
+    name: Cosine
+    learning_rate: 0.001
+  regularizer:
+    name: 'L2'
+    factor: 0.0001
+```
+
+<a name="2"></a>
+
+## 2. 合入PaddleClas套件必须新增的模块
+
+<a name="2.1"></a>
+
+### 2.1 文档
+
+PaddleClas 中的算法都有相对应的文档说明，当给 PaddleClas 提供新的算法时，需要增加相应的文档说明。文档的位置说明如下：
+
+算法类型|需要修改的文档地址|备注|
+| --- | --- | --- |
+| 骨干网络 |[文档地址1](../models/ImageNet1k)；[文档地址2](../models/ImageNet1k/README.md)|在文档地址1中新增模型介绍，在文档地址2中新增模型的精度等信息| 
+| PULC |[文档地址1](../models/PULC)；[文档地址2](../models/PULC/model_list.md)|在文档地址1中新增模型介绍，在文档地址2中新增模型的精度等信息| 
+| 知识蒸馏相关 |[文档地址](../training/advanced/knowledge_distillation.md)|-|
+| 数据增强相关 |[文档地址1](../training/config_description/data_augmentation.md)；[文档地址2](../algorithm_introduction/data_augmentation.md)|-|
+| 其他 |[文档地址1](../algorithm_introduction)；[文档地址2](../training)；[文档地址3](../models)|需要判断在文档地址1、文档地址2、文档地址3中添加相关的文档|
+
+**备注：** 如果在添加文档过程中遇到任何问题，欢迎给我们提[issue](https://github.com/PaddlePaddle/PaddleClas/issues)。
+
+<a name="2.2"></a>
+
+### 2.2 TIPC
+
+飞桨除了基本的模型训练和预测，还提供了支持多端多平台的高性能推理部署工具。PaddleClas中所有模型和算法需要通过飞桨训推一体认证 (Training and Inference Pipeline Certification(TIPC)) ，在您提供模型时，模型需要同时通过该认证。
+
+TIPC 当前包含很多细的方向的认证，当前只需要通过新增模型只需要通过训练和推理的基础认证即可，详情可以参考：[Linux端基础训练预测功能测试](../../../test_tipc/docs/test_train_inference_python.md)，开发流程简述如下：
+
+- 1.新增 TIPC config，此处可以参考[DeiT](../../../test_tipc/configs/DeiT)的config配置。
+- 2.走通[Linux 端基础训练预测功能测试模式一](../../../test_tipc/docs/test_train_inference_python.md#22-功能测试)，检查输出没有报错即可。
+
+**备注：** 
+- 当前只需要走通功能测试的模式一即可；
+- 如果在添加TIPC过程中遇到任何问题，欢迎给我们提 [issue](https://github.com/PaddlePaddle/PaddleClas/issues)。
\ No newline at end of file

docs/zh_CN/community/how_to_contribute.md

@@ -17,8 +17,9 @@
         - [1.2.9 签署 CLA 协议和通过单元测试](#1.2.9)
         - [1.2.10 删除分支](#1.2.10)
         - [1.2.11 提交代码的一些约定](#1.2.11)
-- [2. 总结](#2)
-- [3. 参考文献](#3)
+- [2. 如何新增算法](#2)
+- [3. 总结](#3)
+- [4. 参考文献](#4)
 
 <a name="1"></a>
 ## 1. 如何贡献代码
@@ -28,12 +29,12 @@
 
 PaddleClas 未来将维护 2 种分支，分别为：
 
-* release/x.x 系列分支：为稳定的发行版本分支，会适时打 tag 发布版本，适配 Paddle 的 release 版本。当前最新的分支为 release/2.3 分支，是当前默认分支，适配 Paddle v2.1.0 。随着版本迭代， release/x.x 系列分支会越来越多，默认维护最新版本的 release 分支，前 1 个版本分支会修复 bug，其他的分支不再维护。
+* release/x.x 系列分支：为稳定的发行版本分支，会适时打 tag 发布版本，适配 PaddlePaddle 的 release 版本。当前最新的分支为 release/2.5 分支，是当前默认分支，适配 PaddlePaddle >= 2.2 。随着版本迭代， release/x.x 系列分支会越来越多，默认维护最新版本的 release 分支，前 1 个版本分支会修复 bug，其他的分支不再维护。
 * develop 分支：为开发分支，适配 Paddle 的 develop 版本，主要用于开发新功能。如果有同学需要进行二次开发，请选择 develop 分支。为了保证 develop 分支能在需要的时候拉出 release/x.x 分支， develop 分支的代码只能使用 Paddle 最新 release 分支中有效的 api 。也就是说，如果 Paddle develop 分支中开发了新的 api，但尚未出现在 release 分支代码中，那么请不要在 PaddleClas 中使用。除此之外，对于不涉及 api 的性能优化、参数调整、策略更新等，都可以正常进行开发。
 
 PaddleClas 的历史分支，未来将不再维护。考虑到一些同学可能仍在使用，这些分支还会继续保留：
 
-* release/static 分支：这个分支曾用于静态图的开发与测试，目前兼容 >=1.7 版本的 Paddle 。如果有特殊需求，要适配旧版本的 Paddle，那还可以使用这个分支，但除了修复 bug 外不再更新代码。
+* release/static 分支：这个分支曾用于静态图的开发与测试，目前兼容 >=1.7 版本的 PaddlePaddle 。如果有特殊需求，要适配旧版本的 PaddlePaddle，那还可以使用这个分支，但除了修复 bug 外不再更新代码。
 * dygraph-dev 分支：这个分支将不再维护，也不再接受新的代码，请使用的同学尽快迁移到 develop 分支。
 
 
@@ -242,11 +243,16 @@ git branch -D new_branch
 - 请采用 `start a review` 进行回复，而非直接回复的方式。原因是每个回复都会发送一封邮件，会造成邮件灾难。
 
 <a name="2"></a>
-## 2. 总结
+## 2. 如何新增算法
 
-* 开源社区依赖于众多开发者与用户的贡献和反馈，在这里感谢与期待大家向 PaddleClas 提出宝贵的意见与 Pull Request，希望我们可以一起打造一个领先实用全面的图像识别代码仓库！
+PaddleClas的发展离不开广大开发者的贡献，为了快速帮助开发者开发新的算法，我们总结了在PaddleClas中新增算法的一些需要的操作，请参考[如何新增算法](add_new_algorithm.md)。
 
 <a name="3"></a>
-## 3. 参考文献
+## 3. 总结
+
+* 开源社区依赖于众多开发者与用户的贡献和反馈，在这里感谢与期待大家向 PaddleClas 提出宝贵的意见与 Pull Request，希望我们可以一起打造一个领先实用全面的图像识别代码仓库！
+
+<a name="4"></a>
+## 4. 参考文献
 1. [PaddlePaddle 本地开发指南](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/08_contribution/index_cn.html)
 2. [向开源框架提交 pr 的过程](https://blog.csdn.net/vim_wj/article/details/78300239)