Hackathon No.30

docs/api/paddle/nn/Overview_cn.rst

@@ -256,6 +256,7 @@ Loss层
     " :ref:`paddle.nn.MSELoss <cn_api_paddle_nn_MSELoss>` ", "均方差误差损失层"
     " :ref:`paddle.nn.NLLLoss <cn_api_nn_loss_NLLLoss>` ", "NLLLoss层"
     " :ref:`paddle.nn.SmoothL1Loss <cn_api_paddle_nn_SmoothL1Loss>` ", "平滑L1损失层"
+    " :ref:`paddle.nn.TripletMarginWithDistanceLoss <cn_api_paddle_nn_TripletMarginWithDistanceLoss>` ", "TripletMarginWithDistanceLoss层"
 
 .. _vision_layers:
 
@@ -475,6 +476,7 @@ Embedding相关函数
     " :ref:`paddle.nn.functional.smooth_l1_loss <cn_paddle_nn_functional_loss_smooth_l1>` ", "用于计算平滑L1损失"
     " :ref:`paddle.nn.functional.softmax_with_cross_entropy <cn_api_fluid_layers_softmax_with_cross_entropy>` ", "将softmax操作、交叉熵损失函数的计算过程进行合并"
     " :ref:`paddle.nn.functional.margin_cross_entropy <cn_api_paddle_nn_functional_margin_cross_entropy>` ", "支持 ``Arcface``，``Cosface``，``Sphereface`` 的结合 Margin 损失函数"
+    " :ref:`paddle.nn.functional.triplet_margin_with_distance_loss <cn_paddle_nn_functional_triplet_margin_with_distance_loss>` ", "用户自定义距离函数用于计算triplet margin loss 损失"
 
 .. _common_functional:
 

docs/api/paddle/nn/TripletMarginWithDistanceLoss_cn.rst

@@ -0,0 +1,50 @@
+.. _cn_api_paddle_nn_TripletMarginWithDistanceLoss:
+
+TripletMarginWithDistanceLoss
+-------------------------------
+
+.. py:class:: paddle.nn.TripletMarginWithDistanceLoss(distance_function=None, margin: float = 1.0, swap: bool = False, reduction: str = 'mean')
+
+创建一个TripletMarginWithDistanceLoss的可调用类，通过计算输入 `input` 和 `positive` 和 `negative` 间的 `triplet margin loss` 损失，测量样本之间，即 `input` 与 `positive examples` 和 `negative examples` 的相对相似性。
+
+
+损失函数按照下列公式计算
+
+.. math::
+    L(input, pos, neg) = \max \{d(input_i, pos_i) - d(input_i, neg_i) + {\rm margin}, 0\}
+
+
+其中的距离函数可以由用户自定义，使用lambda或是def都可以。如果未定义则调用2范数计算距离
+
+.. math::
+    d(x_i, y_i) = \left\lVert {\bf x}_i - {\bf y}_i \right\rVert_2
+
+
+其中 ``distance_function`` 为距离函数，默认为2范数。 ``margin`` 为（input,positive）与（input,negative）的距离间隔， ``swap`` 的内容可以看论文 `Learning shallow convolutional feature descriptors with triplet losses <http://www.bmva.org/bmvc/2016/papers/paper119/paper119.pdf>`_。
+
+最后，该api会添加 `reduce` 操作到前面的输出Out上。当 `reduction` 为 `none` 时，直接返回最原始的 `Out` 结果。当 `reduction` 为 `mean` 时，
+返回输出的均值 :math:`Out = MEAN(Out)` 。当 `reduction` 为 `sum` 时，返回输出的求和 :math:`Out = SUM(Out)` 。
+
+
+参数
+:::::::::
+    - **distance_function** (可选) - 手动指定范数，默认为None, 使用欧式距离。
+    - **swap** (bool，可选) - 默认为False
+    - **margin** (float，可选) - 手动指定间距，默认为1。
+    - **reduction** (str,可选) - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 Loss 的均值；设置为 ``'sum'`` 时，计算 Loss 的总和；设置为 ``'none'`` 时，则返回原始Loss。
+    - **name** (str，可选) - 操作的名称（可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。
+
+形状
+:::::::::
+    - **input** (Tensor) - :math:`[N, *]` , 其中N是batch_size， `*` 是任意其他维度。数据类型是float32、float64。
+    - **positive** (Tensor) - :math:`[N, *]` ，标签 ``positive`` 的维度、数据类型与输入 ``input`` 相同。
+    - **negative** (Tensor) - :math:`[N, *]` ，标签 ``negative`` 的维度、数据类型与输入 ``input`` 相同。
+    - **output** (Tensor) - 输出的Tensor。如果 :attr:`reduction` 是 ``'none'``, 则输出的维度为 :math:`[N, *]` , 与输入 ``input`` 的形状相同。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出的维度为 :math:`[1]` 。
+
+返回
+:::::::::
+   返回计算TripletMarginWithDistanceLoss的可调用对象。
+
+代码示例
+:::::::::
+COPY-FROM: paddle.nn.TripletMarginWithDistanceLoss

docs/api/paddle/nn/functional/triplet_margin_with_distance_loss_cn.rst

@@ -0,0 +1,52 @@
+.. _cn_api_paddle_nn_functional_triplet_margin_with_distance_loss:
+
+triplet_margin_with_distance_loss
+-------------------------------
+
+.. py:class:: paddle.nn.functional.triplet_margin_with_distance_loss(input, positive, negative, distance_function=None, margin: float = 1.0, swap: bool = False, reduction: str = 'mean')
+
+该api计算输入 `input` 和 `positive` 和 `negative` 间的 `triplet margin loss` 损失。
+
+
+损失函数按照下列公式计算
+
+.. math::
+    L(input, pos, neg) = \max \{d(input_i, pos_i) - d(input_i, neg_i) + {\rm margin}, 0\}
+
+
+其中的距离函数可以由用户自定义，使用lambda或是def都可以。如果未定义则调用2范数计算距离
+
+.. math::
+    d(x_i, y_i) = \left\lVert {\bf x}_i - {\bf y}_i \right\rVert_2
+
+
+然后， ``distance_function`` 为距离函数，默认为2范数。 ``margin`` 为（input,positive）与（input,negative）的距离间隔， ``swap`` 的内容可以看论文 `Learning shallow convolutional feature descriptors with triplet losses <http://www.bmva.org/bmvc/2016/papers/paper119/paper119.pdf>`_。
+
+最后，该算子会添加 `reduce` 操作到前面的输出Out上。当 `reduction` 为 `none` 时，直接返回最原始的 `Out` 结果。当 `reduction` 为 `mean` 时，返回输出的均值 :math:`Out = MEAN(Out)` 。当 `reduction` 为 `sum` 时，返回输出的求和 :math:`Out = SUM(Out)` 。
+
+
+参数
+:::::::::
+    - **input** (Tensor) - :math:`[N, * ]` , 其中N是batch_size， `*` 是任意其他维度。数据类型是float32、float64。
+    - **positive** (Tensor) - :math:`[N, *]` ，正样本。
+    - **negative** (Tensor) - :math:`[N, *]` ，负样本。
+    - **distance_function** (可选) - 手动指定范数，默认为None, 计算欧式距离。
+    - **swap** (bool，可选) 
+    - **margin** (float，可选) - 手动指定间距，默认为1。
+    - **reduction** (str,可选) - 指定应用于输出结果的计算方式，可选值有: ``'none'``, ``'mean'``, ``'sum'`` 。默认为 ``'mean'``，计算 Loss 的均值；设置为 ``'sum'`` 时，计算 Loss 的总和；设置为 ``'none'`` 时，则返回原始Loss。
+    - **name** (str，可选) - 操作的名称（可选，默认值为None）。更多信息请参见 :ref:`api_guide_Name` 。
+
+形状
+:::::::::
+    - **input** (Tensor) - :math:`[N, *]` , 其中N是batch_size， `*` 是任意其他维度。数据类型是float32、float64。
+    - **positive** (Tensor) - :math:`[N, *]` ，标签 ``positive`` 的维度、数据类型与输入 ``input`` 相同。
+    - **negative** (Tensor) - :math:`[N, *]` ，标签 ``negative`` 的维度、数据类型与输入 ``input`` 相同。
+    - **output** (Tensor) - 输出的Tensor。如果 :attr:`reduction` 是 ``'none'``, 则输出的维度为 :math:`[N, *]` , 与输入 ``input`` 的形状相同。如果 :attr:`reduction` 是 ``'mean'`` 或 ``'sum'``, 则输出的维度为 :math:`[1]` 。
+
+返回
+:::::::::
+   返回计算的Loss。
+
+代码示例
+:::::::::
+COPY-FROM: paddle.nn.functional.triplet_margin_with_distance_loss