mindspore 2.4.10__cp311-cp311-win_amd64.whl → 2.6.0rc1__cp311-cp311-win_amd64.whl

mindspore/ops/function/clip_func.py

@@ -26,11 +26,13 @@ from mindspore.ops.primitive import _primexpr
 from mindspore.ops._primitive_cache import _get_cache_prim
 from mindspore import _checkparam as Validator
 from mindspore.ops.auto_generate import clamp_tensor, clamp_scalar
+from mindspore.ops.auto_generate import inplace_clamp_tensor, inplace_clamp_scalar
 
 __all__ = [
     'clip_by_value',
     'clip_by_norm',
     'clamp',
+    'clamp_',
     'clip',
     'clip_by_global_norm',
 ]
@@ -64,18 +66,20 @@ def _cal_total_norm(x, norm_type):
 
 def clip_by_norm(x, max_norm, norm_type=2.0, error_if_nonfinite=False):
     r"""
-    Clip norm of a set of input Tensors. This norm is the result of calculating the norm of all elements in the input
-    separately, connecting them into a vector, and then calculating the norm.
+    The input Tensor is cropped based on norm. The computation is done by concatenating the norms of
+    all the input elementsinto a vector and then computing the norm of that vector.
+    The Tensor gradient value corresponding to the `identifier`.
 
     Note:
         The interface is suitable for gradient clipping scenarios, and only supports input of type float.
 
     Args:
-          x (Union(Tensor, list[Tensor], tuple[Tensor])): Input that wishes to be clipped.
-          max_norm (Union(float, int)): The upper limit of the norm for this group of network parameters.
-          norm_type (Union(float, int)): Norm type. Default: ``2.0``.
-          error_if_nonfinite (bool): If it is ``True``, an exception is thrown if the total norm from the input
-              is nan, inf or -inf. If it is ``False``, no exception will be thrown.Default: ``False`` .
+        x (Union[Tensor, list[Tensor], tuple[Tensor]]): Input that wishes to be clipped.
+        max_norm (Union[float, int]): The upper limit of the norm for this group of network parameters.
+        norm_type (Union[float, int], optional): Norm type. Default: ``2.0``.
+        error_if_nonfinite (bool, optional): If it is ``True``,
+            an exception is thrown if the total norm from the input
+            is nan, inf or -inf. If it is ``False``, no exception will be thrown.Default: ``False`` .
 
     Returns:
         Tensors, a list or tuple of Tensors, representing clipped Tensors.
@@ -221,11 +225,67 @@ def clip_by_value(x, clip_value_min=None, clip_value_max=None):
 
 
 def clamp(input, min=None, max=None):
+    r"""
+    Clamp all elements of the input tensor within the range [min, max].
+
+    .. math::
+
+        out_i= \left\{
+        \begin{array}{align}
+            max & \text{ if } input_i\ge max \\
+            input_i & \text{ if } min \lt input_i \lt max \\
+            min & \text{ if } input_i \le min \\
+        \end{array}\right.
+
+    Note:
+        - `min` and `max` cannot be None at the same time;
+        - If `min` is ``None`` , there is no lower bound.
+        - if `max` is ``None`` , there is no upper bound.
+        - If `min` is greater than `max`, the value of all elements in Tensor will be set to `max`;
+
+    Args:
+          input (Tensor): The input tensor.
+          min (Union(Tensor, float, int), optional): The minimum value. Default ``None`` .
+          max (Union(Tensor, float, int), optional): The maximum value. Default ``None`` .
+
+    Returns:
+          Tensor
+
+    Supported Platforms:
+        ``Ascend`` ``GPU`` ``CPU``
+
+    Examples:
+        >>> import mindspore
+        >>> # case 1: `min` and `max` are integer
+        >>> input = mindspore.tensor([[1, 25, 5, 7], [4, 11, 6, 21]])
+        >>> mindspore.ops.clamp(input, 5, 20)
+        Tensor(shape=[2, 4], dtype=Int64, value=
+        [[ 5, 20,  5,  7],
+         [ 5, 11,  6, 20]])
+        >>>
+        >>> # case 2: If `min` and `max` are tensors, their shapes need to be broadcastable with input.
+        >>> min = mindspore.tensor([2, 4, 6, 8])
+        >>> max = mindspore.tensor([10, 12, 14, 18])
+        >>> mindspore.ops.clamp(input, min, max)
+        Tensor(shape=[2, 4], dtype=Int64, value=
+        [[ 2, 12,  6,  8],
+         [ 4, 11,  6, 18]])
+    """
+    if isinstance(min, Tensor) or isinstance(max, Tensor):
+        return clamp_tensor(input, min, max)
+    return clamp_scalar(input, min, max)
+
+
+def clamp_(input, min=None, max=None):
     r"""
     Clamps tensor values between the specified minimum value and maximum value.
 
     Limits the value of :math:`input` to a range, whose lower limit is `min` and upper limit is `max` .
 
+    .. warning::
+
+        This is an experimental API that is subject to change or deletion.
+
     .. math::
 
         out_i= \left\{
@@ -258,7 +318,7 @@ def clamp(input, min=None, max=None):
           TypeError: If the type of `max` is not in None, Tensor, float or int.
 
     Supported Platforms:
-        ``Ascend`` ``GPU`` ``CPU``
+        ``Ascend``
 
     Examples:
         >>> # case 1: the data type of input is Tensor
@@ -268,14 +328,14 @@ def clamp(input, min=None, max=None):
         >>> min_value = Tensor(5, mindspore.float32)
         >>> max_value = Tensor(20, mindspore.float32)
         >>> input = Tensor(np.array([[1., 25., 5., 7.], [4., 11., 6., 21.]]), mindspore.float32)
-        >>> output = ops.clamp(input, min_value, max_value)
-        >>> print(output)
+        >>> input.clamp_(min_value, max_value)
+        >>> print(input)
         [[ 5. 20.  5.  7.]
          [ 5. 11.  6. 20.]]
     """
     if isinstance(min, Tensor) or isinstance(max, Tensor):
-        return clamp_tensor(input, min, max)
-    return clamp_scalar(input, min, max)
+        return inplace_clamp_tensor(input, min, max)
+    return inplace_clamp_scalar(input, min, max)
 
 def clip(input, min=None, max=None):
     r"""
@@ -347,30 +407,27 @@ def clip_by_global_norm(x, clip_norm=1.0, use_norm=None):
     Clips tensor values by the ratio of the sum of their norms.
 
     Note:
-        - Input `x` should be a tuple or list of tensors. Otherwise, it will raise an error.
         - On the SEMI_AUTO_PARALLEL mode or AUTO_PARALLEL mode, if the input `x` is the gradient,
           the gradient norm values on all devices will be automatically aggregated by allreduce inserted after
           the local square sum of the gradients.
 
     Args:
         x (Union(tuple[Tensor], list[Tensor])): Input data to clip.
-        clip_norm (Union(float, int)): The clipping ratio, it should be greater than 0. Default: ``1.0`` .
-        use_norm (None): The global norm. Default: ``None`` . Currently only none is supported.
+        clip_norm (Union(float, int)): The clipping ratio, it should be greater than 0. Default ``1.0`` .
+        use_norm (None): The global norm. Currently only none is supported. Default ``None`` .
 
     Returns:
-        tuple[Tensor], a clipped Tensor. It has the same data type as `x` and each Tensor in the output tuple is the
-        same as the original input shape.
+        Tuple of tensors
 
     Supported Platforms:
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
-        >>> from mindspore import Tensor, ops
-        >>> import numpy as np
-        >>> x1 = np.array([[2., 3.], [1., 2.]]).astype(np.float32)
-        >>> x2 = np.array([[1., 4.], [3., 1.]]).astype(np.float32)
-        >>> input_x = (Tensor(x1), Tensor(x2))
-        >>> out = ops.clip_by_global_norm(input_x, 1.0)
+        >>> import mindspore
+        >>> x1 = mindspore.tensor([[2., 3.], [1., 2.]], dtype=mindspore.float32)
+        >>> x2 = mindspore.tensor([[1., 4.], [3., 1.]], dtype=mindspore.float32)
+        >>> input_x = (x1, x2)
+        >>> out = mindspore.ops.clip_by_global_norm(input_x, 1.0)
         >>> print(out)
         (Tensor(shape=[2, 2], dtype=Float32, value=
         [[ 2.98142403e-01,  4.47213590e-01],

mindspore/ops/function/debug_func.py

@@ -23,17 +23,17 @@ from .._primitive_cache import _get_cache_prim
 
 def print_(*input_x):
     """
-    Outputs the inputs to stdout. The outputs are printed to screen by default.
+    Outputs the inputs to stdout.
+    The outputs are printed to screen by default.
     It can also be saved in a file by setting the parameter  `print_file_path` in `context`.
-    Once set, the output will be saved in the file specified by print_file_path.
     :func:`mindspore.parse_print` can be employed to reload the data.
     For more information, please refer to :func:`mindspore.set_context` and :func:`mindspore.parse_print`.
-    In Ascend platform with graph mode, can set environment variables `MS_DUMP_SLICE_SIZE` and `MS_DUMP_WAIT_TIME`
-    to solve operator execution failure when outputting big tensor or outputting tensor intensively.
+    In Ascend platform with graph mode, the environment variables `MS_DUMP_SLICE_SIZE` and `MS_DUMP_WAIT_TIME`
+    can be set to solve operator execution failure when outputting big tensor or outputting tensor intensively.
 
     Note:
         In pynative mode, please use python print function.
-        In Ascend platform with graph mode, the bool, int and float would be converted into Tensor to print, and
+        In Ascend platform with graph mode, the bool, int and float would be converted into tensor to print, and
         str remains unchanged.
         This function is used for debugging.
 
@@ -44,18 +44,14 @@ def print_(*input_x):
     Returns:
         Invalid value, should be ignored.
 
-    Raises:
-        TypeError: If `input_x` is not one of the following: Tensor, bool, int, float, str, tuple or list.
-
     Supported Platforms:
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
-        >>> import numpy as np
-        >>> from mindspore import Tensor, ops
-        >>> x = Tensor(np.ones([2, 1]).astype(np.int32))
-        >>> y = Tensor(np.ones([2, 2]).astype(np.int32))
-        >>> result = ops.print_('Print Tensor x and Tensor y:', x, y)
+        >>> import mindspore
+        >>> x = mindspore.tensor(mindspore.ops.ones([2, 1], mindspore.int32))
+        >>> y = mindspore.tensor(mindspore.ops.ones([2, 2], mindspore.int32))
+        >>> result = mindspore.ops.print_('Print Tensor x and Tensor y:', x, y)
         Print Tensor x and Tensor y:
         Tensor(shape=[2, 1], dtype=Int32, value=
         [[1],
@@ -71,12 +67,13 @@ def print_(*input_x):
 
 def tensordump(file_name, tensor, mode='out'):
     """
-    Save Tensor in numpy's npy format.
+    Save tensor in npy format.
 
-    In Parallel situation, tensordump will dump slice of data at each rank.
+    .. warning::
+        - The parameter `mode` will no longer support the value 'all'.
 
-    In Ascend platform with graph mode,
-    Your code OpA --> OpB may compiled as OpA --> RedistributionOps --> OpB.
+    In Parallel situation, tensordump will dump slice of data at each rank.
+    In Ascend platform with graph mode, Your code OpA --> OpB may compiled as OpA --> RedistributionOps --> OpB.
 
     Note: The redistribution operator is introduced,
     Due to inter-device communication and shard strategies in the static graph parallel scenario.
@@ -88,90 +85,93 @@ def tensordump(file_name, tensor, mode='out'):
     So the parameter mode is to handle this situation.
 
     Assuming OpA's output is used as both tensordump's input parameter and OpB's input parameter.
-    Different requirements of saving dump data can be achieved by configuring parameter mode:
+    Different requirements of saving dump data can be achieved by configuring parameter `mode` :
 
-    - If the mode is 'out', the dump data contains only OpA's output slice.
-    - If the mode is 'all', the dump data contains both OpA's output slice and OpB's input slice.
-    - If the mode is 'in', the dump data contains only OpB's input slice.
+    - If the `mode` is 'out', the dump data contains only OpA's output slice.
+    - If the `mode` is 'in', the dump data contains only OpB's input slice.
 
-    For mode 'all' or 'in', the input slice npy file format is: id_fileName_cNodeID_dumpMode_rankID.npy.
+    For `mode` 'in', the input slice npy file format is: fileName_dumpMode_dtype_id.npy.
 
-    For mode 'out' or 'all' the output slice npy file format is: id_filename.npy.
+    For `mode` 'out', the output slice npy file format is: fileName_dtype_id.npy.
 
-    - id: An auto increment ID.
     - fileName: Value of the parameter file_name
-      (if parameter file_name is a user-specified path, the value of fileName is the last level of the path).
-    - cNodeID: The cnode ID in ir graph of step_parallel_end.ir.
-    - dumpMode: Value of the parameter mode.
-    - rankID: Logical device id.
+      (if parameter `file_name` is a user-specified path, the value of fileName is the last level of the path).
+    - dumpMode: Value of the parameter `mode`.
+    - dtype: The original data type. Data of type bfloat16 stored in the .npy file will be converted to float32.
+    - id: An auto increment ID.
 
     Note:
+        - In Ascend platform with graph mode, the environment variables `MS_DUMP_SLICE_SIZE` and `MS_DUMP_WAIT_TIME`
+          can be set to solve operator execution failure when outputting big tensor or outputting tensor intensively.
         - The operator of tensordump doesn't support in control flow.
-        - If current parallel mode is STAND_ALONE, mode should only be 'out'.
-        - Parameter mode will be set to 'out' if user doesn't configure it.
+        - If current parallel mode is STAND_ALONE, `mode` should only be 'out'.
         - This function is used for debugging.
 
     Args:
         file_name (str): The path of the npy file saves.
         tensor (Tensor): The tensor that user want to dump.
-        mode (str, optional): Used to control tensordump behavior, available value is one of ['in', 'out', 'all'].
-            Default value is ``out``.
-
-    Raises:
-        TypeError: If `file_name` is not str.
-        TypeError: If `tensor` is not Tensor.
-        TypeError: If `mode` is not str.
-        ValueError: If `mode` is not in one of ['in', 'out', 'all'].
+        mode (str, optional): Used to control tensordump behavior, available value is one of ['in', 'out'].
+            Default ``out`` .
 
     Supported Platforms:
         ``Ascend``
 
     Examples:
         .. note::
-            Using msrun command to run below example: msrun --worker_num=2 --local_worker_num=2 --master_port=11450
-            --log_dir=msrun_log --join=True --cluster_time_out=300 tensordump_example.py
+            Using msrun command to run below example: msrun --worker_num=2 --local_worker_num=2
+            --master_port=11450 --log_dir=msrun_log --join=True --cluster_time_out=300 tensordump_example.py
 
+        >>> import os
         >>> import numpy as np
-        >>> import mindspore as ms
-        >>> from mindspore import nn, Tensor, ops, context
-        >>> from mindspore.ops import operations as P
+        >>> import mindspore
+        >>> from mindspore import nn, context
         >>> from mindspore.communication import init, get_rank
+        >>> from mindspore.parallel.auto_parallel import AutoParallel
+        >>> from mindspore.nn.utils import no_init_parameters
         >>> init()
         >>> rank_id = get_rank()
-        >>> dump_path = f'dumps/rank_{rank_id}/mul1_mul2.npy'
+        >>> dump_path = f'rank_{rank_id}_mul1_mul2.npy'
         >>> class Net(nn.Cell):
         ...     def __init__(self, strategy1, strategy2):
         ...         super(Net, self).__init__()
-        ...         self.matmul1 = P.MatMul().shard(strategy1)
-        ...         self.matmul2 = P.MatMul().shard(strategy2)
+        ...         self.matmul1 = mindspore.ops.MatMul().shard(strategy1)
+        ...         self.matmul2 = mindspore.ops.MatMul().shard(strategy2)
         ...
         ...     def construct(self, x, y, b):
         ...         out1 = self.matmul1(x, y)
-        ...         ops.tensordump(dump_path, out1, 'all')
+        ...         mindspore.ops.tensordump(dump_path, out1, 'out')
         ...         out2 = self.matmul2(out1, b)
         ...         return out2
         ...
-        >>> ms.set_context(mode=ms.GRAPH_MODE, save_graphs=2)
-        >>> context.set_auto_parallel_context(parallel_mode='semi_auto_parallel', full_batch=True)
+        >>> mindspore.set_context(mode=mindspore.GRAPH_MODE)
+        >>> os.environ["MS_DEV_SAVE_GRAPHS"] = "2"
         >>> strategy1 = ((1, 2), (2, 1))
         >>> strategy2 = ((1, 2), (2, 1))
-        >>> net = Net(strategy1, strategy2)
-        >>> x = Tensor(0.1 * np.random.randn(64, 64).astype(np.float32))
-        >>> y = Tensor(0.1 * np.random.randn(64, 64).astype(np.float32))
-        >>> b = Tensor(0.1 * np.random.randn(64, 64).astype(np.float32))
-        >>> out = net(x, y, b)
+        >>> with no_init_parameters():
+        >>>     net = Net(strategy1, strategy2)
+        >>> x = mindspore.tensor(0.1 * mindspore.ops.randn(64, 64), mindspore.float32)
+        >>> y = mindspore.tensor(0.1 * mindspore.ops.randn(64, 64), mindspore.float32)
+        >>> b = mindspore.tensor(0.1 * mindspore.ops.randn(64, 64), mindspore.float32)
+        >>> parallel_net = Autoparallel(net, parallel_mode="semi_auto")
+        >>> parallel_net.dataset_strategy(config="full_batch")
+        >>> out = parallel_net(x, y, b)
         >>> print(f"out shape is: {out.shape}")
-        >>> matmul1_output_slice = np.load('0_mul1_mul2.npy')                       # load matmul1's output slice
-        >>> matmul2_input_slice = np.load('1_mul1_mul2_CNode_64_all_rank_0.npy')    # load matmul2's input slice
+        >>> # out shape is (64, 64)
+        >>> matmul1_output_slice = np.load(f'rank_{rank_id}_mul1_mul2_float32_0.npy')      # load matmul1's output slice
+        >>> print(f"matmul1_output_slice is loaded, shape is: {matmul1_output_slice.shape}")
+        >>> # matmul1_output_slice is loaded, shape is: (64, 64)
     """
+
     if not isinstance(file_name, str):
         raise TypeError(f"Parameter file_name should only be build_in str type but got: {type(file_name)}")
     if not isinstance(tensor, Tensor):
         raise TypeError(f"Parameter tensor should only be Tensor type, but got: {type(tensor)}")
     if not isinstance(mode, str):
         raise TypeError(f"Parameter mode should only be build_in str type, but got: {type(mode)}")
-    mode_list = ['out', 'in', 'all']
+    mode_list = ['out', 'in']
     if mode not in mode_list:
+        if mode == 'all':
+            raise ValueError(f"Argument [mode] has been not supported value of 'all'.")
         raise ValueError(f"Parameter mode should in {mode_list}, but got {mode}")
     _tensordump = _get_cache_prim(P.TensorDump)(input_output=mode)
     return _tensordump(file_name, tensor)

mindspore/ops/function/grad/__init__.py

@@ -27,6 +27,7 @@ from .grad_func import (
     vjp,
     linearize,
     stop_gradient,
+    stop_gradient_,
     get_grad
 )