add NLLLoss url

Author: joey12300

python/paddle/nn/functional/loss.py

@@ -68,14 +68,19 @@
 ]
 
 
-def nll_loss(x, label, weight=None, ignore_index=-100, reduction='mean'):
+def nll_loss(x,
+             label,
+             weight=None,
+             ignore_index=-100,
+             reduction='mean',
+             name=None):
     """
     This api returns negative log likelihood.
-    See more detail in `paddle.nn.loss.NLLLoss`.
-  
+    See more detail in :ref:`api_nn_loss_NLLLoss` .
+
     Parameters:
          x (Tensor): Input tensor, the data type is float32, float64.
-         label (Tensor): Label tensor, the data type is int64_t.
+         label (Tensor): Label tensor, the data type is int64.
          weight (Tensor, optional): Weight tensor, a manual rescaling weight given
              to each class. If given, it has to be a Tensor of size `C`. Otherwise,
              it treated as if having all ones. the data type is
@@ -85,48 +90,35 @@ def nll_loss(x, label, weight=None, ignore_index=-100, reduction='mean'):
          reduction (str, optional): Indicate how to average the loss,
              the candicates are ``'none'`` | ``'mean'`` | ``'sum'``.
              If :attr:`reduction` is ``'mean'``, the reduced mean loss is returned;
+                :attr:`reduction` is ``'sum'``, the reduced sum loss is returned;
+                :attr:`reduction` is ``'none'``, no reduction will be apllied.
              Default is ``'mean'``.
-  
+         name (str, optional): Name for the operation (optional, default is None).
+             For more information, please refer to :ref:`api_guide_Name`.
+
     Returns:
          The tensor variable storing the nll_loss.
-    
+
     Examples:
-         import paddle
-         import numpy as np
-         from paddle.nn.functional import nll_loss
-         log_softmax = paddle.nn.LogSoftmax(axis=1)
-         
-         x_np = np.random.random(size=(10, 10)).astype(np.float32)
-         label_np = np.random.randint(0, 10, size=(10,)).astype(np.int64)
-         
-         place = paddle.CPUPlace()
-         
-         # imperative mode
-         paddle.enable_imperative(place)
-         x = paddle.imperative.to_variable(x_np)
-         log_out = log_softmax(x)
-         label = paddle.imperative.to_variable(label_np)
-         imperative_result = nll_loss(log_out, label)
-         print(imperative_result.numpy())
-         
-         # declarative mode
-         paddle.disable_imperative()
-         prog = paddle.Program()
-         startup_prog = paddle.Program()
-         with paddle.program_guard(prog, startup_prog):
-             x = paddle.nn.data(name='x', shape=[10, 10], dtype='float32')
-             label = paddle.nn.data(name='label', shape=[10], dtype='int64')
-             log_out = log_softmax(x)
-             res = nll_loss(log_out, label)
-         
-             exe = paddle.Executor(place)
-             declaritive_result = exe.run(
-                 prog,
-                 feed={"x": x_np,
-                       "label": label_np},
-                 fetch_list=[res])
-         print(declaritive_result)
+        .. code-block:: python
+
+                import paddle
+                import numpy as np
+                from paddle.nn.functional import nll_loss
+                log_softmax = paddle.nn.LogSoftmax(axis=1)
 
+                x_np = np.random.random(size=(10, 10)).astype(np.float32)
+                label_np = np.random.randint(0, 10, size=(10,)).astype(np.int64)
+
+                place = paddle.CPUPlace()
+
+                # imperative mode
+                paddle.enable_imperative(place)
+                x = paddle.imperative.to_variable(x_np)
+                log_out = log_softmax(x)
+                label = paddle.imperative.to_variable(label_np)
+                imperative_result = nll_loss(log_out, label)
+                print(imperative_result.numpy())
     """
     if reduction not in ['sum', 'mean', 'none']:
         raise ValueError(
@@ -152,6 +144,7 @@ def nll_loss(x, label, weight=None, ignore_index=-100, reduction='mean'):
             out, _ = core.ops.reshape2(out, 'shape', out_shape)
         return out
 
+    helper = LayerHelper('nll_loss', **locals())
     x_shape = list(x.shape)
     x_dims = len(x_shape)
     if x_dims < 2:
@@ -165,7 +158,6 @@ def nll_loss(x, label, weight=None, ignore_index=-100, reduction='mean'):
         label = paddle.reshape(label, shape=[n, 1, -1])
         out_shape = [n] + x_shape[2:]
 
-    helper = LayerHelper('nll_loss', **locals())
     fluid.data_feeder.check_variable_and_dtype(x, 'x', ['float32', 'float64'],
                                                'nll_loss')
     fluid.data_feeder.check_variable_and_dtype(label, 'label', ['int64'],

python/paddle/nn/layer/loss.py

@@ -506,8 +506,6 @@ class NLLLoss(fluid.dygraph.Layer):
         \\end{cases}
 
     Parameters:
-        x (Tensor): Input tensor, the data type is float32, float64. 
-        label (Tensor): Label tensor, the data type is int64_t.
         weight (Tensor, optional): Weight tensor, a manual rescaling weight given
             to each class. If given, it has to be a Tensor of size `C`. Otherwise,
             it treated as if having all ones. the data type is 
@@ -516,27 +514,34 @@ class NLLLoss(fluid.dygraph.Layer):
             and does not contribute to the input gradient.
         reduction (str, optional): Indicate how to average the loss, 
             the candicates are ``'none'`` | ``'mean'`` | ``'sum'``.
-            If :attr:`reduction` is ``'mean'``, the reduced mean loss is returned; 
+            If :attr:`reduction` is ``'mean'``, the reduced mean loss is returned;
+               :attr:`reduction` is ``'sum'``, the reduced sum loss is returned;
+               :attr:`reduction` is ``'none'``, no reduction will be apllied.
             Default is ``'mean'``.
+         name (str, optional): Name for the operation (optional, default is None).
+             For more information, please refer to :ref:`api_guide_Name`.
+
+    Shape:
+        x (Tensor): Input tensor, the data type is float32, float64.
+        label (Tensor): Label tensor, the data type is int64.
 
     Returns:
-        The callable object which calculates negative log likelihood loss when 
-        get the input `x` and `label`.
+        The callable object which calculates negative log likelihood loss.
 
     Examples:
-
         .. code-block:: python
+
                 import paddle
                 import numpy as np
-                
+
                 nll_loss = paddle.nn.layer.NLLLoss()
                 log_softmax = paddle.nn.LogSoftmax(axis=1)
-                
+
                 x_np = np.random.random(size=(10, 10)).astype(np.float32)
                 label_np = np.random.randint(0, 10, size=(10,)).astype(np.int64)
-                
+
                 place = paddle.CPUPlace()
-                
+
                 # imperative mode
                 paddle.enable_imperative(place)
                 x = paddle.imperative.to_variable(x_np)
@@ -564,16 +569,26 @@ class NLLLoss(fluid.dygraph.Layer):
                 print(declaritive_result)
     """
 
-    def __init__(self, weight=None, ignore_index=-100, reduction='mean'):
+    def __init__(self,
+                 weight=None,
+                 ignore_index=-100,
+                 reduction='mean',
+                 name=None):
+        if reduction not in ['sum', 'mean', 'none']:
+            raise ValueError(
+                "The value of 'reduction' in nll_loss should be 'sum', 'mean' or "
+                "'none', but received %s, which is not allowed." % reduction)
         super(NLLLoss, self).__init__()
         self.weight = weight
         self.ignore_index = ignore_index
         self.reduction = reduction
+        self.name = name
 
     def forward(self, x, label):
         return F.nll_loss(
             x,
             label,
             weight=self.weight,
             ignore_index=self.ignore_index,
-            reduction=self.reduction)
+            reduction=self.reduction,
+            name=self.name)