!5295 Fix some doc errors in pp distributions and bijectors

Merge pull request !5295 from peixu_ren/custom_bijector

mindspore/nn/probability/bijector/bijector.py

@@ -101,13 +101,13 @@ class Bijector(Cell):
 
     def forward_log_jacobian(self, *args, **kwargs):
         """
-        Logarithm of the derivative of forward transformation.
+        Logarithm of the derivative of the forward transformation.
         """
         return self._forward_log_jacobian(*args, **kwargs)
 
     def inverse_log_jacobian(self, *args, **kwargs):
         """
-        Logarithm of the derivative of forward transformation.
+        Logarithm of the derivative of the inverse transformation.
         """
         return self._inverse_log_jacobian(*args, **kwargs)
 
@@ -131,11 +131,14 @@ class Bijector(Cell):
         """
         Override construct in Cell.
 
-        Args:
-            *inputs: inputs[0] is always the name of a function.
+        Note:
+            Names of supported functions include:
+            'forward', 'inverse', 'forward_log_jacobian', 'inverse_log_jacobian'.
 
-        Notes:
-            Always raise RuntimeError as Distribution should not be called directly.
+        Args:
+            name (str): name of the function.
+            *args (list): list of positional arguments needed for the function.
+            **kwargs (dictionary): dictionary of keyword arguments needed for the function.
         """
         if name == 'forward':
             return self.forward(*args, **kwargs)

mindspore/nn/probability/bijector/exp.py

@@ -20,6 +20,9 @@ class Exp(PowerTransform):
     Exponential Bijector.
     This Bijector performs the operation: Y = exp(x).
 
+    Args:
+        name (str): name of the bijector. Default: 'Exp'.
+
     Examples:
         >>> # To initialize a Exp bijector
         >>> import mindspore.nn.probability.bijector as msb
@@ -32,11 +35,12 @@ class Exp(PowerTransform):
         >>>         self.e1 = msb.Exp()
         >>>
         >>>     def construct(self, value):
-        >>>
         >>>         # Similar calls can be made to other probability functions
         >>>         # by replacing 'forward' with the name of the function
-        >>>         ans1 = self.e1.forward(value)
-        >>>         ans2 = self.e1.backward(value)
+        >>>         ans1 = self.s1.forward(value)
+        >>>         ans2 = self.s1.inverse(value)
+        >>>         ans3 = self.s1.forward_log_jacobian(value)
+        >>>         ans4 = self.s1.inverse_log_jacobian(value)
     """
     def __init__(self,
                  name='Exp'):

mindspore/nn/probability/bijector/power_transform.py

@@ -29,8 +29,12 @@ class PowerTransform(Bijector):
 
     This bijector is equivalent to the `Exp` bijector when `c=0`
 
+    Raises:
+        ValueError: If the power is less than 0 or is not known statically.
+
     Args:
         power (int or float): scale factor. Default: 0.
+        name (str): name of the bijector. Default: 'PowerTransform'.
 
     Examples:
         >>> # To initialize a PowerTransform bijector of power 0.5
@@ -44,10 +48,12 @@ class PowerTransform(Bijector):
         >>>         self.p1 = msb.PowerTransform(0.5)
         >>>
         >>>     def construct(self, value):
-        >>>
         >>>         # Similar calls can be made to other probability functions
         >>>         # by replacing 'forward' with the name of the function
-        >>>         ans = self.p1.forward(, value)
+        >>>         ans1 = self.s1.forward(value)
+        >>>         ans2 = self.s1.inverse(value)
+        >>>         ans3 = self.s1.forward_log_jacobian(value)
+        >>>         ans4 = self.s1.inverse_log_jacobian(value)
     """
 
     def __init__(self,

mindspore/nn/probability/bijector/scalar_affine.py

@@ -29,6 +29,7 @@ class ScalarAffine(Bijector):
     Args:
         scale (float): scale factor. Default: 1.0.
         shift (float): shift factor. Default: 0.0.
+        name (str): name of the bijector. Default: 'ScalarAffine'.
 
     Examples:
         >>> # To initialize a ScalarAffine bijector of scale 1 and shift 2
@@ -43,10 +44,10 @@ class ScalarAffine(Bijector):
         >>>     def construct(self, value):
         >>>         # Similar calls can be made to other probability functions
         >>>         # by replacing 'forward' with the name of the function
-        >>>         ans = self.s1.forward(value)
-        >>>         ans = self.s1.inverse(value)
-        >>>         ans = self.s1.forward_log_jacobian(value)
-        >>>         ans = self.s1.inverse_log_jacobian(value)
+        >>>         ans1 = self.s1.forward(value)
+        >>>         ans2 = self.s1.inverse(value)
+        >>>         ans3 = self.s1.forward_log_jacobian(value)
+        >>>         ans4 = self.s1.inverse_log_jacobian(value)
     """
 
     def __init__(self,

mindspore/nn/probability/bijector/softplus.py

@@ -33,6 +33,7 @@ class Softplus(Bijector):
 
     Args:
         sharpness (float): scale factor. Default: 1.0.
+        name (str): name of the bijector. Default: 'Softplus'.
 
     Examples:
         >>> # To initialize a Softplus bijector of sharpness 2
@@ -47,10 +48,10 @@ class Softplus(Bijector):
         >>>     def construct(self, value):
         >>>         # Similar calls can be made to other probability functions
         >>>         # by replacing 'forward' with the name of the function
-        >>>         ans = self.sp1.forward(value)
-        >>>         ans = self.sp1.inverse(value)
-        >>>         ans = self.sp1.forward_log_jacobian(value)
-        >>>         ans = self.sp1.inverse_log_jacobian(value)
+        >>>         ans1 = self.sp1.forward(value)
+        >>>         ans2 = self.sp1.inverse(value)
+        >>>         ans3 = self.sp1.forward_log_jacobian(value)
+        >>>         ans4 = self.sp1.inverse_log_jacobian(value)
     """
 
     def __init__(self,

mindspore/nn/probability/distribution/distribution.py

@@ -454,13 +454,14 @@ class Distribution(Cell):
         Override construct in Cell.
 
         Note:
-            Names of supported functions:
+            Names of supported functions include:
             'prob', 'log_prob', 'cdf', 'log_cdf', 'survival_function', 'log_survival'
             'var', 'sd', 'entropy', 'kl_loss', 'cross_entropy', 'sample'.
 
         Args:
             name (str): name of the function.
-            *args (list): list of arguments needed for the function.
+            *args (list): list of positional arguments needed for the function.
+            **kwargs (dictionary): dictionary of keyword arguments needed for the function.
         """
 
         if name == 'log_prob':

mindspore/nn/probability/distribution/transformed_distribution.py

@@ -35,6 +35,28 @@ class TransformedDistribution(Distribution):
         The arguments used to initialize the original distribution cannot be None.
         For example, mynormal = nn.Normal(dtype=dtyple.float32) cannot be used to initialized a
         TransformedDistribution since mean and sd are not specified.
+
+    Examples:
+        >>> # To initialize a transformed distribution, e.g. lognormal distribution,
+        >>> # using Normal distribution as the base distribution, and Exp bijector as the bijector function.
+        >>> import mindspore.nn.probability.distribution as msd
+        >>> import mindspore.nn.probability.bijector as msb
+        >>> ln = msd.TransformedDistribution(msb.Exp(),
+        >>>                                  msd.Normal(0.0, 1.0, dtype=mstype.float32),
+        >>>                                  dtype=mstype.float32)
+        >>>
+        >>> # To use a transformed distribution in a network
+        >>> class net(Cell):
+        >>>     def __init__(self):
+        >>>         super(net, self).__init__():
+        >>>         self.ln = msd.TransformedDistribution(msb.Exp(),
+        >>>                                               msd.Normal(0.0, 1.0, dtype=mstype.float32),
+        >>>                                               dtype=mstype.float32)
+        >>>
+        >>>     def construct(self, value):
+        >>>         # Similar calls can be made to other probability functions
+        >>>         # by replacing 'sample' with the name of the function
+        >>>         ans = self.ln.sample(shape=(2, 3))
     """
     def __init__(self,
                  bijector,