映射文档 No. 1 (#5699)

* backup

* backup

* fix code style

* resolve conversation

* fix equation

* fix equation

* fix equation

* fix conversation

* fix conversation

* fix conversation

* fix conversation

docs/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.grid_sample.md

@@ -0,0 +1,32 @@
+## [ 仅参数名不一致 ] torch.nn.functional.grid_sample
+
+### [torch.nn.functional.grid_sample](https://pytorch.org/docs/stable/generated/torch.nn.functional.grid_sample.html?highlight=grid_sample#torch.nn.functional.grid_sample)
+
+```python
+torch.nn.functional.grid_sample(input,
+                        grid,
+                        mode='bilinear',
+                        padding_mode='zeros',
+                        align_corners=None)
+```
+
+### [paddle.nn.functional.grid_sample](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/grid_sample_cn.html)
+
+```python
+paddle.nn.functional.grid_sample(x,
+                        grid,
+                        mode='bilinear',
+                        padding_mode='zeros',
+                        align_corners=True,
+                        name=None)
+```
+
+两者功能一致，仅参数名不一致，具体如下：
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| input           | x           | 表示输入的 Tensor，仅参数名不一致。               |
+| grid           | grid           |  输入网格数据张量。               |
+| mode           | mode           |   指定插值方式。               |
+| padding_mode           | padding_mode           |   指定超出边界的填充方式。               |
+| align_corners           | align_corners           |   是否将角落的点进行中心对齐。     |

docs/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.nll_loss.md

@@ -0,0 +1,52 @@
+## [ torch 参数更多 ]torch.nn.functional.nll_loss
+
+### [torch.nn.functional.nll_loss](https://pytorch.org/docs/stable/generated/torch.nn.functional.nll_loss.html#torch-nn-functional-nll-loss)
+
+```python
+torch.nn.functional.nll_loss(input,
+                    target,
+                    weight=None,
+                    size_average=None,
+                    ignore_index=- 100,
+                    reduce=None,
+                    reduction='mean')
+```
+
+### [paddle.nn.functional.nll_loss](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/nll_loss_cn.html#nll-loss)
+
+```python
+paddle.nn.functional.nll_loss(input,
+                    label,
+                    weight=None,
+                    ignore_index=-100,
+                    reduction='mean',
+                    name=None)
+```
+
+其中 Pytorch 相⽐ Paddle ⽀持更多其他参数，具体如下：
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| input          | input         | 输入 Tensor                                     |
+| target          | label         | 输入 Tensor 对应的标签值,仅参数名不一致。            |
+| size_average          | -         | 已弃用                                      |
+| weight          | weight  | 手动指定每个类别的权重                          |
+| ignore_index          | ignore_index  |  指定一个忽略的标签值，此标签值不参与计算                   |
+| reduce          | -         | 已弃用                                     |
+| reduction          | reduction         | 表示应用于输出结果的规约方式，可选值有：'none', 'mean', 'sum'                         |
+
+### 转写示例
+```python
+# Pytorch 的 size_average、 reduce 参数转为 Paddle 的 reduction 参数
+if size_average is None:
+    size_average = True
+if reduce is None:
+    reduce = True
+
+if size_average and reduce:
+    reduction = 'mean'
+elif reduce:
+    reduction = 'sum'
+else:
+    reduction = 'none'
+```

docs/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.pad.md

@@ -0,0 +1,34 @@
+## [ 仅 paddle 参数更多 ]torch.nn.functional.one_hot
+
+### [torch.nn.functional.pad](https://pytorch.org/docs/stable/generated/torch.nn.functional.pad.html)
+
+```python
+torch.nn.functional.pad(input,
+                            pad,
+                            mode='constant',
+                            value=None)
+```
+
+### [paddle.nn.functional.pad](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/pad_cn.html#pad)
+
+```python
+paddle.nn.functional.pad(x,
+                            pad,
+                            mode='constant',
+                            value=0.0,
+                            data_format='NCHW',
+                            name=None)
+```
+
+两者功能一致，其中 Paddle 相比 PyTorch 支持更多其他参数，具体如下：
+
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| input          | x         | 表示输入的 Tensor，仅参数名不一致。                                     |
+| pad          | pad         | 表示一个 one-hot 向量的长度 。                                     |
+| mode          | mode         | 表示填充的模式。                                     |
+| value          | value         | 表示填充的值，mode 为'constant'时有效 。                |
+| -        | data_format |  指定输入的数据格式, PyTorch 无此参数， Paddle 保持默认即可。 |
+
+在实际使用过程中，`data_format` 参数需要根据输入参数进行指定

docs/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.pixel_shuffle.md

@@ -0,0 +1,21 @@
+## [ 仅 paddle 参数更多 ]torch.nn.functional.pixel_shuffle
+
+### [torch.nn.functional.pixel_shuffle](https://pytorch.org/docs/stable/generated/torch.nn.functional.pixel_shuffle.html?highlight=pixel_shuffle#torch.nn.functional.pixel_shuffle)
+
+```python
+torch.nn.functional.pixel_shuffle(input, upscale_factor)
+```
+
+### [paddle.nn.functional.pixel_shuffle](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/pixel_shuffle_cn.html)
+
+```python
+paddle.nn.functional.pixel_shuffle(x, upscale_factor, data_format='NCHW', name=None)
+```
+
+两者功能一致，其中 Paddle 相比 PyTorch 支持更多其他参数，具体如下：
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| input           | x           | 表示输入的 Tensor，仅参数名不一致。               |
+| downscale_factor           | downscale_factor           |   减小空间分辨率的减小因子。               |
+| -           | data_format           |   指定输入张量格式, PyTorch 无此参数， Paddle 保持默认即可 。             |

docs/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.pixel_unshuffle.md

@@ -0,0 +1,22 @@
+## [ 仅  paddle 参数更多 ] torch.nn.functional.pixel_unshuffle
+
+### [torch.nn.functional.pixel_unshuffle](https://pytorch.org/docs/stable/generated/torch.nn.functional.pixel_unshuffle.html?highlight=pixel_unshuffle#torch.nn.functional.pixel_unshuffle)
+
+```python
+torch.nn.functional.pixel_unshuffle(input, downscale_factor)
+```
+
+### [paddle.nn.functional.pixel_unshuffle](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/pixel_unshuffle_cn.html)
+
+```python
+paddle.nn.functional.pixel_unshuffle(x, downscale_factor, data_format='NCHW', name=None)
+```
+
+两者功能一致，其中 Paddle 相比 PyTorch 支持更多其他参数，具体如下：
+
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| input           | x           | 表示输入的 Tensor，仅参数名不一致。      |
+| downscale_factor           | downscale_factor           |   减小空间分辨率的减小因子。               |
+| -           | data_format           |   指定输入张量格式，PyTorch 无此参数，Paddle 保持默认即可。               |

docs/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.smooth_l1_loss.md

@@ -0,0 +1,98 @@
+##  [ 参数用法不一致 ]torch.nn.functional.smooth_l1_loss
+
+### [torch.nn.functional.smooth_l1_loss](https://pytorch.org/docs/stable/generated/torch.nn.functional.smooth_l1_loss.html)
+
+```python
+torch.nn.functional.smooth_l1_loss(input,
+                    target,
+                    size_average=None,
+                    reduce=None,
+                    reduction='mean',
+                    beta=1.0)
+```
+
+### [paddle.nn.functional.smooth_l1_loss](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/smooth_l1_loss_cn.html#smooth-l1-loss)
+
+```python
+paddle.nn.functional.smooth_l1_loss(input,
+                    label,
+                    reduction='mean',
+                    delta=1.0,
+                    name=None)
+```
+
+两者功能一致，但 Paddle 的 `delta` 和 PyTorch 的 `beta` 参数在公式中用法不一致，具体如下：
+
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| input          | input         | 输入 Tensor                                     |
+| target          | label         | 输入 Tensor 对应的标签，仅参数名不一致。                                |
+| size_average          | -         | 已弃用                                      |
+| reduce          | -         | 已弃用                                     |
+| reduction          | reduction         | 表示应用于输出结果的规约方式，可选值有：'none', 'mean', 'sum'   |
+| beta          | delta         | SmoothL1Loss 损失的阈值参数                       |
+
+Torch 中 Smooth L1 loss 的计算方式:
+
+$$
+\ell(x, y) = \left [l_1, ..., l_N\ \right ]^T
+$$
+
+其中:
+
+$$
+l_n = \begin{cases}
+0.5 (x_n - y_n)^2 / beta, & \text{if } |x_n - y_n| < beta \\
+|x_n - y_n| - 0.5 * beta, & \text{otherwise }
+\end{cases}
+$$
+
+而 Paddle 中 Smooth L1 loss 的计算方式:
+
+$$
+loss(x,y)  = \left [ z_1, ..., z_N \right ]^T
+$$
+
+其中：
+
+$$
+z_i = \begin{cases}
+        0.5(x_i - y_i)^2 & {if |x_i - y_i| < delta} \\
+        delta * |x_i - y_i| - 0.5 * delta^2 & {otherwise}
+        \end{cases}
+$$
+
+所以如果 PyTorch 函数参数 $beta$ 与 Paddle 中的参数 $delta$ 取值相同，则 Paddle 的 loss 要再除以 $delta$ 值才能与 Torch 中的结果对齐。
+
+
+### 转写示例
+
+#### size_average
+
+
+```python
+# Pytorch 的 size_average、 reduce 参数转为 Paddle 的 reduction 参数
+if size_average is None:
+    size_average = True
+if reduce is None:
+    reduce = True
+if size_average and reduce:
+    reduction = 'mean'
+elif reduce:
+    reduction = 'sum'
+else:
+    reduction = 'none'
+```
+
+#### beta
+```python
+# PyTorch 的 beta 参数转化为 delta 参数
+a=0.8
+
+# PyTorch 写法
+output = torch.nn.functional.smooth_l1_loss(input, label, beta=a)
+
+# Paddle 写法
+output = paddle.nn.functional.smooth_l1_loss(input, label, delta=a) / a
+```

docs/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.soft_margin_loss.md

@@ -0,0 +1,47 @@
+## [ torch 参数更多 ]torch.nn.functional.soft_margin_loss
+
+### [torch.nn.functional.soft_margin_loss](https://pytorch.org/docs/stable/generated/torch.nn.functional.soft_margin_loss.html?highlight=soft_margin_loss#torch.nn.functional.soft_margin_loss)
+
+```python
+torch.nn.functional.soft_margin_loss(input,
+                             target,
+                             size_average=None,
+                             reduce=None,
+                             reduction='mean')
+```
+
+### [paddle.nn.functional.soft_margin_loss](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/soft_margin_loss_cn.html)
+
+```python
+paddle.nn.functional.soft_margin_loss(input,
+                              label,
+                              reduction='mean',
+                              name=None)
+```
+
+其中 Pytorch 相⽐ Paddle ⽀持更多其他参数，具体如下：
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| input          | input         | 输入 Tensor 。                                    |
+| target          | label         | 输入 Tensor 对应的标签值，仅参数名不一致。               |
+| size_average          | -         | 已弃用                                      |
+| reduce          | -         | 已弃用                                     |
+| reduction          | reduction         | 表示应用于输出结果的规约方式，可选值有：'none', 'mean', 'sum'。        |
+
+### 转写示例
+#### size_average
+```python
+# Pytorch 的 size_average、 reduce 参数转为 Paddle 的 reduction 参数
+if size_average is None:
+    size_average = True
+if reduce is None:
+    reduce = True
+
+if size_average and reduce:
+    reduction = 'mean'
+elif reduce:
+    reduction = 'sum'
+else:
+    reduction = 'none'
+```

docs/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.triplet_margin_loss.md

@@ -0,0 +1,62 @@
+## [torch 参数更多 ] torch.nn.functional.triplet_margin_loss
+
+### [torch.nn.functional.triplet_margin_loss](https://pytorch.org/docs/stable/generated/torch.nn.functional.triplet_margin_loss.html?highlight=triplet_margin_loss#torch.nn.functional.triplet_margin_loss)
+
+```python
+torch.nn.functional.triplet_margin_loss(anchor,
+                positive,
+                negative,
+                margin=1.0,
+                p=2,
+                eps=1e-06,
+                swap=False,
+                size_average=None,
+                reduce=None,
+                reduction='mean')
+```
+
+### [paddle.nn.functional.triplet_margin_loss](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/triplet_margin_loss_cn.html)
+
+```python
+paddle.nn.functional.triplet_margin_loss(input,
+                positive,
+                negative,
+                margin: float = 1.0,
+                p: float = 2.0,
+                epsilon: float = 1e-6,
+                swap: bool = False,
+                reduction: str = 'mean',
+                name: str = None)
+```
+
+其中 Pytorch 相⽐ Paddle ⽀持更多其他参数，具体如下：
+### 参数映射
+| PyTorch       | PaddlePaddle | 备注                                                   |
+| ------------- | ------------ | ------------------------------------------------------ |
+| anchor          | input         | 输入 Tensor，仅参数名不一致。                        |
+| positive          | positive         | 输入正样本                                 |
+| negative          | negative         | 输入负样本                                     |
+| margin          | margin         |  手动指定间距                                  |
+| p          | p         | 指定范数                                 |
+| eps          | epsilon         | 防止除数为零的常数                                  |
+| swap          | swap         | 是否进行交换                                  |
+| size_average          | -         | 已弃用                                      |
+| reduce          | -         | 已弃用                                     |
+| reduction          | reduction         | 表示应用于输出结果的规约方式，可选值有：'none', 'mean', 'sum'             |
+
+### 转写示例
+#### size_average
+```python
+# Pytorch 的 size_average、 reduce 参数转为 Paddle 的 reduction 参数
+if size_average is None:
+    size_average = True
+if reduce is None:
+    reduce = True
+
+if size_average and reduce:
+    reduction = 'mean'
+elif reduce:
+    reduction = 'sum'
+else:
+    reduction = 'none'
+```