From 6e58088973f526f17d655302acb820596c6905e0 Mon Sep 17 00:00:00 2001 From: LutaoChu <30695251+LutaoChu@users.noreply.github.com> Date: Tue, 18 Aug 2020 22:38:32 +0800 Subject: [PATCH] add normalize op docs, fix the typo of L1Loss op docs, test=develop (#2390) --- doc/fluid/api_cn/nn_cn/functional_cn.rst | 1 + .../api_cn/nn_cn/functional_cn/l1_loss_cn.rst | 28 ++++----- .../nn_cn/functional_cn/normalize_cn.rst | 59 +++++++++++++++++++ doc/fluid/api_cn/nn_cn/loss_cn/L1Loss_cn.rst | 26 ++++---- 4 files changed, 87 insertions(+), 27 deletions(-) create mode 100644 doc/fluid/api_cn/nn_cn/functional_cn/normalize_cn.rst diff --git a/doc/fluid/api_cn/nn_cn/functional_cn.rst b/doc/fluid/api_cn/nn_cn/functional_cn.rst index b492a51cc..cf0d405bf 100644 --- a/doc/fluid/api_cn/nn_cn/functional_cn.rst +++ b/doc/fluid/api_cn/nn_cn/functional_cn.rst @@ -10,5 +10,6 @@ functional functional_cn/l1_loss_cn.rst functional_cn/nll_loss_cn.rst + functional_cn/normalize_cn.rst functional_cn/margin_ranking_loss_cn.rst functional_cn/mse_loss_cn.rst diff --git a/doc/fluid/api_cn/nn_cn/functional_cn/l1_loss_cn.rst b/doc/fluid/api_cn/nn_cn/functional_cn/l1_loss_cn.rst index d7bf747f4..77c9a232a 100644 --- a/doc/fluid/api_cn/nn_cn/functional_cn/l1_loss_cn.rst +++ b/doc/fluid/api_cn/nn_cn/functional_cn/l1_loss_cn.rst @@ -1,38 +1,38 @@ l1_loss ------------------------------- -.. py:function:: paddle.nn.functional.l1_loss(x, label, reduction='mean', name=None) +.. py:function:: paddle.nn.functional.l1_loss(input, label, reduction='mean', name=None) -该接口计算输入 ``x`` 和标签 ``label`` 间的 `L1 loss` 损失。 +该接口计算输入 ``input`` 和标签 ``label`` 间的 `L1 loss` 损失。 该损失函数的数学计算公式如下： 当 `reduction` 设置为 ``'none'`` 时， .. math:: - Out = \lvert x - label\rvert + Out = \lvert input - label\rvert 当 `reduction` 设置为 ``'mean'`` 时， .. math:: - Out = MEAN(\lvert x - label\rvert) + Out = MEAN(\lvert input - label\rvert) 当 `reduction` 设置为 ``'sum'`` 时， .. math:: - Out = SUM(\lvert x - label\rvert) + Out = SUM(\lvert input - label\rvert) 参数 ::::::::: - - **x** (Tensor): - 输入的Tensor，维度是[N, *], 其中N是batch size， `*` 是任意数量的额外维度。数据类型为：float32、float64、int32、int64。 - - **label** (Tensor): - 标签，维度是[N, *], 与 ``x`` 相同。数据类型为：float32、float64、int32、int64。 + - **input** (Tensor): - 输入的Tensor，维度是[N, *], 其中N是batch size， `*` 是任意数量的额外维度。数据类型为：float32、float64、int32、int64。 + - **label** (Tensor): - 标签，维度是[N, *], 与 ``input`` 相同。数据类型为：float32、float64、int32、int64。 - **reduction** (str, 可选): - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 `L1Loss` 的均值；设置为 ``'sum'`` 时，计算 `L1Loss` 的总和；设置为 ``'none'`` 时，则返回 `L1Loss`。 - **name** (str，可选): - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 返回 ::::::::: -``Tensor``, 输入 ``x`` 和标签 ``label`` 间的 `L1 loss` 损失。如果 :attr:`reduction` 是 ``'none'``, 则输出Loss的维度为 [N, *], 与输入 ``x`` 相同。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。 +``Tensor``, 输入 ``input`` 和标签 ``label`` 间的 `L1 loss` 损失。如果 `reduction` 是 ``'none'``, 则输出Loss的维度为 [N, *], 与输入 ``input`` 相同。如果 `reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。 代码示例 @@ -40,24 +40,24 @@ l1_loss .. code-block:: python - import paddle import numpy as np + import paddle paddle.disable_static() - x_data = np.array([[1.5, 0.8], [0.2, 1.3]]).astype("float32") + input_data = np.array([[1.5, 0.8], [0.2, 1.3]]).astype("float32") label_data = np.array([[1.7, 1], [0.4, 0.5]]).astype("float32") - x = paddle.to_variable(x_data) + input = paddle.to_variable(input_data) label = paddle.to_variable(label_data) - l1_loss = paddle.nn.functional.l1_loss(x, label) + l1_loss = paddle.nn.functional.l1_loss(input, label) print(l1_loss.numpy()) # [0.35] - l1_loss = paddle.nn.functional.l1_loss(x, label, reduction='none') + l1_loss = paddle.nn.functional.l1_loss(input, label, reduction='none') print(l1_loss.numpy()) # [[0.20000005 0.19999999] # [0.2 0.79999995]] - l1_loss = paddle.nn.functional.l1_loss(x, label, reduction='sum') + l1_loss = paddle.nn.functional.l1_loss(input, label, reduction='sum') print(l1_loss.numpy()) # [1.4] diff --git a/doc/fluid/api_cn/nn_cn/functional_cn/normalize_cn.rst b/doc/fluid/api_cn/nn_cn/functional_cn/normalize_cn.rst new file mode 100644 index 000000000..04b5b185b --- /dev/null +++ b/doc/fluid/api_cn/nn_cn/functional_cn/normalize_cn.rst @@ -0,0 +1,59 @@ +normalize +------------------------------- + +.. py:function:: paddle.nn.functional.normalize(x, p=2, axis=1, epsilon=1e-12, name=None) + +该接口使用 :math:`L_p` 范数沿维度 ``axis`` 对 ``x`` 进行归一化。计算公式如下： + +.. math:: + + y = \frac{x}{ \max\left( \lvert \lvert x \rvert \rvert_p, epsilon\right) } + +.. math:: + \lvert \lvert x \rvert \rvert_p = \left(\sum_i {\lvert x_i\rvert^p} \right)^{1/p} + +其中 :math:`\sum_i{\lvert x_i\rvert^p}` 沿维度 ``axis`` 进行计算。 + + +参数 +::::::::: + - **x** (Tensor) - 输入可以是N-D Tensor。数据类型为：float32、float64。 + - **p** (float|int, 可选) - 范数公式中的指数值。默认值:2 + - **axis** (int, 可选）- 要进行归一化的轴。如果 ``x`` 是1-D Tensor，轴固定为0。如果 `axis < 0`，轴为 `x.ndim + axis`。-1表示最后一维。 + - **epsilon** (float，可选) - 添加到分母上的值以防止分母除0。默认值为1e-12。 + - **name** (str，可选) - 操作的名称(可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name`。 + +返回 +::::::::: +``Tensor``, 输出的形状和数据类型和 ``x`` 相同。 + +抛出异常： +::::::::: + - ``TypeError`` - 当参数 ``p`` 或者 ``axis`` 的类型不符合要求时。或者当参数 ``x`` 的类型或数据类型不符合要求时。 + +代码示例 +::::::::: + +.. code-block:: python + + import numpy as np + import paddle + import paddle.nn.functional as F + + paddle.disable_static() + x = np.arange(6, dtype=np.float32).reshape(2,3) + x = paddle.to_variable(x) + y = F.normalize(x) + print(y.numpy()) + # [[0. 0.4472136 0.8944272 ] + # [0.42426404 0.5656854 0.7071067 ]] + + y = F.normalize(x, p=1.5) + print(y.numpy()) + # [[0. 0.40862012 0.81724024] + # [0.35684016 0.4757869 0.5947336 ]] + + y = F.normalize(x, axis=0) + print(y.numpy()) + # [[0. 0.24253564 0.37139067] + # [1. 0.97014254 0.9284767 ]] diff --git a/doc/fluid/api_cn/nn_cn/loss_cn/L1Loss_cn.rst b/doc/fluid/api_cn/nn_cn/loss_cn/L1Loss_cn.rst index 71f366e32..f5a41b3a8 100644 --- a/doc/fluid/api_cn/nn_cn/loss_cn/L1Loss_cn.rst +++ b/doc/fluid/api_cn/nn_cn/loss_cn/L1Loss_cn.rst @@ -3,24 +3,24 @@ L1Loss .. py:class:: paddle.nn.loss.L1Loss(reduction='mean', name=None) -该接口用于创建一个L1Loss的可调用类，L1Loss计算输入x和标签label间的 `L1 loss` 损失。 +该接口用于创建一个L1Loss的可调用类，L1Loss计算输入input和标签label间的 `L1 loss` 损失。 该损失函数的数学计算公式如下： 当 `reduction` 设置为 ``'none'`` 时， .. math:: - Out = \lvert x - label\rvert + Out = \lvert input - label\rvert 当 `reduction` 设置为 ``'mean'`` 时， .. math:: - Out = MEAN(\lvert x - label\rvert) + Out = MEAN(\lvert input - label\rvert) 当 `reduction` 设置为 ``'sum'`` 时， .. math:: - Out = SUM(\lvert x - label\rvert) + Out = SUM(\lvert input - label\rvert) 参数 @@ -30,36 +30,36 @@ L1Loss 形状 ::::::::: - - **x** (Tensor): - 输入的Tensor，维度是[N, *], 其中N是batch size， `*` 是任意数量的额外维度。数据类型为：float32、float64、int32、int64。 - - **label** (Tensor): - 标签，维度是[N, *], 与 ``x`` 相同。数据类型为：float32、float64、int32、int64。 - - **output** (Tensor): - 输入 ``x`` 和标签 ``label`` 间的 `L1 loss` 损失。如果 :attr:`reduction` 是 ``'none'``, 则输出Loss的维度为 [N, *], 与输入 ``x`` 相同。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。 + - **input** (Tensor): - 输入的Tensor，维度是[N, *], 其中N是batch size， `*` 是任意数量的额外维度。数据类型为：float32、float64、int32、int64。 + - **label** (Tensor): - 标签，维度是[N, *], 与 ``input`` 相同。数据类型为：float32、float64、int32、int64。 + - **output** (Tensor): - 输入 ``input`` 和标签 ``label`` 间的 `L1 loss` 损失。如果 `reduction` 是 ``'none'``, 则输出Loss的维度为 [N, *], 与输入 ``input`` 相同。如果 `reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出Loss的维度为 [1]。 代码示例 ::::::::: .. code-block:: python - import paddle import numpy as np + import paddle paddle.disable_static() - x_data = np.array([[1.5, 0.8], [0.2, 1.3]]).astype("float32") + input_data = np.array([[1.5, 0.8], [0.2, 1.3]]).astype("float32") label_data = np.array([[1.7, 1], [0.4, 0.5]]).astype("float32") - x = paddle.to_variable(x_data) + input = paddle.to_variable(input_data) label = paddle.to_variable(label_data) l1_loss = paddle.nn.loss.L1Loss() - output = l1_loss(x, label) + output = l1_loss(input, label) print(output.numpy()) # [0.35] l1_loss = paddle.nn.loss.L1Loss(reduction='sum') - output = l1_loss(x, label) + output = l1_loss(input, label) print(output.numpy()) # [1.4] l1_loss = paddle.nn.loss.L1Loss(reduction='none') - output = l1_loss(x, label) + output = l1_loss(input, label) print(output.numpy()) # [[0.20000005 0.19999999] # [0.2 0.79999995]] -- GitLab