mindspore 2.4.0__cp310-cp310-macosx_10_15_x86_64.whl

mindspore/nn/probability/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2020 Huawei Technologies Co., Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+"""
+Probability.
+
+The high-level components used to construct the probabilistic network.
+"""
+
+from . import bijector
+from . import distribution

mindspore/nn/probability/bijector/__init__.py

@@ -0,0 +1,35 @@
+# Copyright 2020 Huawei Technologies Co., Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+"""
+Bijectors are the high-level components used to construct the probabilistic network.
+"""
+
+from .bijector import Bijector
+from .power_transform import PowerTransform
+from .exp import Exp
+from .scalar_affine import ScalarAffine
+from .softplus import Softplus
+from .gumbel_cdf import GumbelCDF
+from .invert import Invert
+
+__all__ = [
+    'Bijector',
+    'PowerTransform',
+    'Exp',
+    'ScalarAffine',
+    'Softplus',
+    'GumbelCDF',
+    'Invert',
+]

mindspore/nn/probability/bijector/bijector.py

@@ -0,0 +1,337 @@
+# Copyright 2020 Huawei Technologies Co., Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+"""Bijector"""
+from mindspore import context
+from mindspore.nn.cell import Cell
+from mindspore.ops import operations as P
+from mindspore.ops import functional as F
+from mindspore.ops.operations import _inner_ops as inner
+from mindspore.common import dtype as mstype
+from mindspore.common.tensor import Tensor
+from mindspore import _checkparam as validator
+from ..distribution._utils.utils import CheckTensor, cast_to_tensor, raise_type_error
+from ..distribution import Distribution
+from ..distribution import TransformedDistribution
+
+
+class Bijector(Cell):
+    """
+    Bijecotr class. A bijector perform a mapping from one distribution to the other via some function.
+    If :math:`X` is a random variable following the original distribution,
+    and :math:`g(x)` is the mapping function,
+    then :math:`Y = g(X)` is the random variable following the transformed distribution.
+
+    Args:
+        is_constant_jacobian (bool): Whether the Bijector has constant derivative. Default: ``False`` .
+        is_injective (bool): Whether the Bijector is a one-to-one mapping. Default: ``True`` .
+        name (str): The name of the Bijector. Default: ``None`` .
+        dtype (mindspore.dtype): The type of the distributions that the Bijector can operate on. Default: ``None`` .
+        param (dict): The parameters used to initialize the Bijector. Default: ``None`` .
+
+    Note:
+        `dtype` of bijector represents the type of the distributions that the bijector could operate on.
+        When `dtype` is None, there is no enforcement on the type of input value except that the input value
+        has to be float type. During initialization, when `dtype` is None, there is no enforcement on the dtype
+        of the parameters. All parameters should have the same float type, otherwise a TypeError will be raised.
+        Specifically, the parameter type will follow the dtype of the input value, i.e. parameters of the bijector
+        will be casted into the same type as input value when `dtype` is None.
+        When `dtype` is specified, it is forcing the parameters and input value to be the same dtype as `dtype`.
+        When the type of parameters or the type of the input value is not the same as `dtype`, a TypeError will be
+        raised. Only subtype of mindspore.float_type can be used to specify bijector's `dtype`.
+
+    Supported Platforms:
+        ``Ascend`` ``GPU``
+    """
+
+    def __init__(self,
+                 is_constant_jacobian=False,
+                 is_injective=True,
+                 name=None,
+                 dtype=None,
+                 param=None):
+        """
+        Constructor of Bijector class.
+        """
+        super(Bijector, self).__init__()
+        validator.check_value_type('name', name, [str], type(self).__name__)
+        validator.check_value_type(
+            'is_constant_jacobian', is_constant_jacobian, [bool], name)
+        validator.check_value_type('is_injective', is_injective, [bool], name)
+        if dtype is not None:
+            validator.check_type_name(
+                "dtype", dtype, mstype.float_type, type(self).__name__)
+        self._name = name
+        self._dtype = dtype
+        self._parameters = {}
+        # parsing parameters
+        for k in param.keys():
+            if k == 'param':
+                continue
+            if not(k == 'self' or k.startswith('_')):
+                self._parameters[k] = param[k]
+
+        # if no bijector is used as an argument during initialization
+        if 'bijector' not in param.keys():
+            self._batch_shape = self._calc_batch_shape()
+            self._is_scalar_batch = self._check_is_scalar_batch()
+
+        self._is_constant_jacobian = is_constant_jacobian
+        self._is_injective = is_injective
+
+        self.context_mode = context.get_context('mode')
+        self.checktensor = CheckTensor()
+
+        # ops needed for the base class
+        self.cast_base = P.Cast()
+        self.dtype_base = P.DType()
+        self.shape_base = P.Shape()
+        self.sametypeshape_base = inner.SameTypeShape()
+        self.issubclass_base = inner.IsSubClass()
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def dtype(self):
+        return self._dtype
+
+    @property
+    def parameters(self):
+        return self._parameters
+
+    @property
+    def is_constant_jacobian(self):
+        return self._is_constant_jacobian
+
+    @property
+    def is_injective(self):
+        return self._is_injective
+
+    @property
+    def batch_shape(self):
+        return self._batch_shape
+
+    @property
+    def is_scalar_batch(self):
+        return self._is_scalar_batch
+
+    def _check_value_dtype(self, value):
+        """
+        Firstly check if the input value is Tensor. Then, if `self.dtype` is None, check
+        if the input tensor is or can be directly cast into a float tensor.
+        If `self.dtype` is not None, check if the input tensor's dtype is `self.dtype`.
+        """
+        self.checktensor(value, 'input value of bijector')
+        value_type = self.dtype_base(value)
+        if self.dtype is None:
+            if self.issubclass_base(value_type, mstype.float_):
+                return value
+            return raise_type_error('input value of bijector', value_type, mstype.float_)
+        dtype_tensor = F.fill(self.dtype, self.shape_base(value), 0.0)
+        self.sametypeshape_base(value, dtype_tensor)
+        return value
+
+    def _shape_mapping(self, shape):
+        shape_tensor = F.fill(self.parameter_type, shape, 0.0)
+        dist_shape_tensor = F.fill(
+            self.parameter_type, self.batch_shape, 0.0)
+        return (shape_tensor + dist_shape_tensor).shape
+
+    def shape_mapping(self, shape):
+        return self._shape_mapping(shape)
+
+    def _add_parameter(self, value, name):
+        """
+        Cast `value` to a tensor and add it to `self.default_parameters`.
+        Add `name` into  and `self.parameter_names`.
+        """
+        # initialize the attributes if they do not exist yet
+        if not hasattr(self, 'default_parameters'):
+            self.default_parameters = []
+            self.parameter_names = []
+            self.common_dtype = None
+        # cast value to a tensor if it is not None
+        if isinstance(value, bool) or value is None:
+            raise TypeError(f"{name} cannot be type {type(value)}")
+        value_t = Tensor(value)
+        # if the bijector's dtype is not specified
+        if self.dtype is None:
+            if self.common_dtype is None:
+                self.common_dtype = value_t.dtype
+            elif value_t.dtype != self.common_dtype:
+                raise TypeError(
+                    f"{name} should have the same dtype as other arguments.")
+            # check if the parameters are casted into float-type tensors
+            validator.check_type_name(
+                f"dtype of {name}", value_t.dtype, mstype.float_type, type(self).__name__)
+        # check if the dtype of the input_parameter agrees with the bijector's dtype
+        elif value_t.dtype != self.dtype:
+            raise TypeError(
+                f"{name} should have the same dtype as the bijector's dtype.")
+        self.default_parameters += [value,]
+        self.parameter_names += [name,]
+        return value_t
+
+    def _calc_batch_shape(self):
+        """
+        Calculate batch_shape based on parameters.
+        """
+        if 'param_dict' not in self.parameters:
+            return None
+        param_dict = self.parameters.get('param_dict')
+        broadcast_shape_tensor = None
+        for value in param_dict.values():
+            if value is None:
+                return None
+            if broadcast_shape_tensor is None:
+                broadcast_shape_tensor = cast_to_tensor(value)
+            else:
+                value = cast_to_tensor(value)
+                broadcast_shape_tensor = (value + broadcast_shape_tensor)
+        return broadcast_shape_tensor.shape
+
+    def _check_is_scalar_batch(self):
+        """
+        Check if the parameters used during initialization are scalars.
+        """
+        if 'param_dict' not in self.parameters.keys():
+            return False
+        param_dict = self.parameters.get('param_dict')
+        for value in param_dict.values():
+            if value is None:
+                continue
+            if not isinstance(value, (int, float)):
+                return False
+        return True
+
+    def _check_value(self, value, name):
+        """
+        Check availability of `value` as a Tensor.
+        """
+        self.checktensor(value, name)
+        return value
+
+    def cast_param_by_value(self, value, para):
+        """
+        Cast the parameter(s) of the bijector to be the same type of input_value.
+
+        Args:
+            value (Tensor): input value.
+            para (Tensor): parameter(s) of the bijector.
+
+        Returns:
+            Tensor, the value of parameters after casting.
+        """
+        local = self.cast_base(para, self.dtype_base(value))
+        return local
+
+    def forward(self, value, *args, **kwargs):
+        """
+        Forward transformation: transform the input value to another distribution.
+
+        Args:
+            value (Tensor): the value of the input variables.
+            *args (list): the list of positional arguments forwarded to subclasses.
+            **kwargs (dict): the dictionary of keyword arguments forwarded to subclasses.
+
+        Returns:
+            Tensor, the value of the transformed random variable.
+        """
+        return self._forward(value, *args, **kwargs)
+
+    def inverse(self, value, *args, **kwargs):
+        """
+        Inverse transformation: transform the input value back to the original distribution.
+
+        Args:
+            value (Tensor): the value of the transformed variables.
+            *args (list): the list of positional arguments forwarded to subclasses.
+            **kwargs (dict): the dictionary of keyword arguments forwarded to subclasses.
+
+        Returns:
+            Tensor, the value of the input random variable.
+        """
+        return self._inverse(value, *args, **kwargs)
+
+    def forward_log_jacobian(self, value, *args, **kwargs):
+        """
+        Logarithm of the derivative of the forward transformation.
+
+        Args:
+            value (Tensor): the value of the input variables.
+            *args (list): the list of positional arguments forwarded to subclasses.
+            **kwargs (dict): the dictionary of keyword arguments forwarded to subclasses.
+
+        Returns:
+            Tensor, the value of logarithm of the derivative of the forward transformation.
+        """
+        return self._forward_log_jacobian(value, *args, **kwargs)
+
+    def inverse_log_jacobian(self, value, *args, **kwargs):
+        """
+        Logarithm of the derivative of the inverse transformation.
+
+        Args:
+            value (Tensor): the value of the transformed variables.
+            *args (list): the list of positional arguments forwarded to subclasses.
+            **kwargs (dict): the dictionary of keyword arguments forwarded to subclasses.
+
+        Returns:
+            Tensor, the value of logarithm of the derivative of the inverse transformation.
+        """
+        return self._inverse_log_jacobian(value, *args, **kwargs)
+
+    def __call__(self, *args, **kwargs):
+        """
+        Call Bijector directly.
+        This __call__ may go into two directions:
+        If args[0] is a distribution instance, the call will generate a new distribution derived from
+        the input distribution.
+        Otherwise, input[0] must be the name of a Bijector function, e.g. "forward", then this call will
+        go in the construct and invoke the corresponding Bijector function.
+
+        Args:
+            *args: args[0] shall be either a distribution or the name of a Bijector function.
+        """
+        if isinstance(args[0], Distribution):
+            return TransformedDistribution(self, args[0])
+        return super(Bijector, self).__call__(*args, **kwargs)
+
+    def construct(self, name, *args, **kwargs):
+        """
+        Override `construct` in Cell.
+
+        Note:
+            Names of supported functions include:
+            'forward', 'inverse', 'forward_log_jacobian', and 'inverse_log_jacobian'.
+
+        Args:
+            name (str): The name of the function.
+            *args (list): the list of positional arguments forwarded to subclasses.
+            **kwargs (dict): the dictionary of keyword arguments forwarded to subclasses.
+
+        Returns:
+            Tensor, the result of the function corresponding to name.
+        """
+        if name == 'forward':
+            return self.forward(*args, **kwargs)
+        if name == 'inverse':
+            return self.inverse(*args, **kwargs)
+        if name == 'forward_log_jacobian':
+            return self.forward_log_jacobian(*args, **kwargs)
+        if name == 'inverse_log_jacobian':
+            return self.inverse_log_jacobian(*args, **kwargs)
+        raise Exception('Invalid name')

mindspore/nn/probability/bijector/exp.py

@@ -0,0 +1,65 @@
+# Copyright 2020 Huawei Technologies Co., Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+"""Exp Bijector"""
+from .power_transform import PowerTransform
+
+
+class Exp(PowerTransform):
+    r"""
+    Exponential Bijector.
+    This Bijector performs the operation:
+
+    .. math::
+        Y = \exp(x).
+
+    Args:
+        name (str): The name of the Bijector. Default: ``'Exp'`` .
+
+    Supported Platforms:
+        ``Ascend`` ``GPU``
+
+    Examples:
+        >>> import mindspore
+        >>> import mindspore.nn as nn
+        >>> from mindspore import Tensor
+        >>>
+        >>> # To initialize an Exp bijector.
+        >>> exp_bijector = nn.probability.bijector.Exp()
+        >>> value = Tensor([1, 2, 3], dtype=mindspore.float32)
+        >>> ans1 = exp_bijector.forward(value)
+        >>> print(ans1.shape)
+        (3,)
+        >>> ans2 = exp_bijector.inverse(value)
+        >>> print(ans2.shape)
+        (3,)
+        >>> ans3 = exp_bijector.forward_log_jacobian(value)
+        >>> print(ans3.shape)
+        (3,)
+        >>> ans4 = exp_bijector.inverse_log_jacobian(value)
+        >>> print(ans4.shape)
+        (3,)
+    """
+
+    def __init__(self,
+                 name='Exp'):
+        super(Exp, self).__init__(name=name)
+
+    def extend_repr(self):
+        """Display instance object as string."""
+        if self.is_scalar_batch:
+            str_info = 'exp'
+        else:
+            str_info = 'batch_shape = {}'.format(self.batch_shape)
+        return str_info

mindspore/nn/probability/bijector/gumbel_cdf.py

@@ -0,0 +1,144 @@
+# Copyright 2020 Huawei Technologies Co., Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+"""GumbelCDF Bijector"""
+from mindspore.ops import operations as P
+from ..distribution._utils.utils import check_greater_zero
+from ..distribution._utils.custom_ops import exp_generic, log_generic
+from .bijector import Bijector
+
+
+class GumbelCDF(Bijector):
+    r"""
+    GumbelCDF Bijector.
+    This Bijector performs the operation:
+
+    .. math::
+        Y = \exp(-\exp(\frac{-(X - loc)}{scale}))
+
+    Args:
+        loc (float, list, numpy.ndarray, Tensor): The location. Default: ``0.0`` .
+        scale (float, list, numpy.ndarray, Tensor): The scale. Default: ``1.0`` .
+        name (str): The name of the Bijector. Default: ``'GumbelCDF'`` .
+
+    Note:
+        `scale` must be greater than zero.
+        For `inverse` and `inverse_log_jacobian`, input should be in range of (0, 1).
+        The dtype of `loc` and `scale` must be float.
+        If `loc`, `scale` are passed in as numpy.ndarray or tensor, they have to have
+        the same dtype otherwise an error will be raised.
+
+    Raises:
+        TypeError: When the dtype of `loc` or `scale` is not float,
+                   or when the dtype of `loc` and `scale` is not same.
+
+    Supported Platforms:
+        ``Ascend`` ``GPU``
+
+    Examples:
+        >>> import mindspore
+        >>> import mindspore.nn as nn
+        >>> import mindspore.nn.probability.bijector as msb
+        >>> from mindspore import Tensor
+        >>>
+        >>> # To initialize a GumbelCDF bijector of loc 1.0, and scale 2.0.
+        >>> gumbel_cdf = msb.GumbelCDF(1.0, 2.0)
+        >>> # To use a GumbelCDF bijector in a network.
+        >>> x = Tensor([1, 2, 3], dtype=mindspore.float32)
+        >>> y = Tensor([0.1, 0.2, 0.3], dtype=mindspore.float32)
+        >>> ans1 = gumbel_cdf.forward(x)
+        >>> print(ans1.shape)
+        (3,)
+        >>> ans2 = gumbel_cdf.inverse(y)
+        >>> print(ans2.shape)
+        (3,)
+        >>> ans3 = gumbel_cdf.forward_log_jacobian(x)
+        >>> print(ans3.shape)
+        (3,)
+        >>> ans4 = gumbel_cdf.inverse_log_jacobian(y)
+        >>> print(ans4.shape)
+        (3,)
+    """
+
+    def __init__(self,
+                 loc=0.0,
+                 scale=1.0,
+                 name='GumbelCDF'):
+        """
+        Constructor of GumbelCDF Bijector.
+        """
+        param = dict(locals())
+        param['param_dict'] = {'loc': loc, 'scale': scale}
+        super(GumbelCDF, self).__init__(name=name, param=param)
+
+        self._loc = self._add_parameter(loc, 'loc')
+        self._scale = self._add_parameter(scale, 'scale')
+        check_greater_zero(self._scale, "scale")
+
+        self.cast = P.Cast()
+        self.exp = exp_generic
+        self.log = log_generic
+
+    @property
+    def loc(self):
+        """
+        Return the loc parameter of the bijector.
+
+        Output:
+            Tensor, the loc parameter of the bijector.
+        """
+        return self._loc
+
+    @property
+    def scale(self):
+        """
+        Return the scale parameter of the bijector.
+
+        Output:
+            Tensor, the scale parameter of the bijector.
+        """
+        return self._scale
+
+    def extend_repr(self):
+        """Display instance object as string."""
+        if self.is_scalar_batch:
+            str_info = 'loc = {}, scale = {}'.format(self.loc, self.scale)
+        else:
+            str_info = 'batch_shape = {}'.format(self.batch_shape)
+        return str_info
+
+    def _forward(self, x):
+        x = self._check_value_dtype(x)
+        loc_local = self.cast_param_by_value(x, self.loc)
+        scale_local = self.cast_param_by_value(x, self.scale)
+        z = (x - loc_local) / scale_local
+        return self.exp((-1) * self.exp(-z))
+
+    def _inverse(self, y):
+        y = self._check_value_dtype(y)
+        loc_local = self.cast_param_by_value(y, self.loc)
+        scale_local = self.cast_param_by_value(y, self.scale)
+        return loc_local - scale_local * self.log((-1) * self.log(y))
+
+    def _forward_log_jacobian(self, x):
+        x = self._check_value_dtype(x)
+        loc_local = self.cast_param_by_value(x, self.loc)
+        scale_local = self.cast_param_by_value(x, self.scale)
+        z = (x - loc_local) / scale_local
+        return -z - self.exp(-z) - self.log(scale_local)
+
+    def _inverse_log_jacobian(self, y):
+        y = self._check_value_dtype(y)
+        scale_local = self.cast_param_by_value(y, self.scale)
+        return self.log(scale_local / (-1. * y * self.log(y)))