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

mindspore/ops/operations/_custom_ops_utils.py

@@ -0,0 +1,247 @@
+# Copyright 2024 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.
+# ============================================================================
+
+"""compile custom kernel with ninja"""
+
+import os
+import shlex
+import subprocess
+import sysconfig
+import time
+import stat
+from mindspore import log as logger
+
+
+class VersionManager:
+    """version manager"""
+
+    def __init__(self):
+        self.entries = {}  # module_name : (version, hash)
+
+    def _get_version(self, module_name):
+        """get version"""
+        return self.entries.get(module_name, (None, None))[0]
+
+    def _update_version_if_changed(self, module_name, sources, build_args, build_dir):
+        """update version if changed"""
+        hash_value = self._update_hash(0, build_dir)
+        hash_value = self._update_sources_hash(hash_value, sources)
+        hash_value = self._update_args_hash(hash_value, build_args)
+
+        entry = self.entries.get(module_name)
+        if entry is None:
+            self.entries[module_name] = entry = (0, hash_value)
+        elif hash_value != entry[1]:
+            self.entries[module_name] = entry = (entry[0] + 1, hash_value)
+
+        return entry[0]
+
+    def _update_hash(self, seed, value):
+        """update hash value"""
+        # Good old boost::hash_combine
+        return seed ^ (hash(value) + 0x9e3779b9 + (seed << 6) + (seed >> 2))
+
+    def _update_sources_hash(self, hash_value, sources):
+        """hash source files"""
+        for filename in sources:
+            with open(filename) as file:
+                hash_value = self._update_hash(hash_value, file.read())
+        return hash_value
+
+    def _update_args_hash(self, hash_value, build_args):
+        """hash build arguments"""
+        for group in build_args:
+            if group:
+                for argument in group:
+                    hash_value = self._update_hash(hash_value, argument)
+        return hash_value
+
+    def check_version(self, name, sources, cflags, ldflags, include_paths, build_dir):
+        """check version"""
+        old_version = self._get_version(name)
+        version = self._update_version_if_changed(name, sources, [cflags, ldflags, include_paths], build_dir)
+        logger.info(f'Build module {name}, version={version}')
+        if version > 0:
+            if version != old_version:
+                logger.info(
+                    f'The conditions for extension module {name} have changed. '
+                    f'Updating to version {version} and re-building as {name}_v{version}.'
+                )
+            name = f'{name}_v{version}'
+
+        if version != old_version:
+            return True
+        logger.info(f'No modifications detected for extension module {name}')
+        return False
+
+
+version_manager = VersionManager()
+
+
+class FileLocker:
+    """FileLocker"""
+
+    def __init__(self, build_dir):
+        """FileLocker"""
+        self.lock_file_name = os.path.join(build_dir, 'build.lock')
+        self.lock_fd = None
+
+    def try_lock(self):
+        """Acquire a file-based lock."""
+        try:
+            mode = stat.S_IRUSR | stat.S_IWUSR
+            self.lock_fd = os.open(self.lock_file_name, os.O_CREAT | os.O_EXCL, mode)
+            return True
+        except FileExistsError:
+            return False
+
+    def release_lock(self):
+        """Release the file-based lock."""
+        if self.lock_fd is not None:
+            os.close(self.lock_fd)
+            self.lock_fd = None
+        os.remove(self.lock_file_name)
+
+    def wait(self):
+        """Wait until lock is released."""
+        while os.path.exists(self.lock_file_name):
+            time.sleep(0.5)
+
+
+class ExtensionBuilder:
+    """ExtensionBuilder"""
+
+    def __init__(self):
+        """ExtensionBuilder"""
+
+    def _get_build_directory(self, module_name):
+        """Get build directory."""
+        build_root = os.environ.get('MS_COMPILER_CACHE_PATH')
+        if build_root is None:
+            build_root = os.path.realpath("./kernel_meta")
+        logger.info(f'Using {build_root} as MindSpore extensions root...')
+
+        build_dir = os.path.join(build_root, module_name)
+        if not os.path.exists(build_dir):
+            os.makedirs(build_dir, exist_ok=True)
+        return build_dir
+
+    def _compile(self, name, sources, cflags, ldflags, include_paths, build_dir):
+        """Compile."""
+        if version_manager.check_version(name, sources, cflags, ldflags, include_paths, build_dir):
+            locker = FileLocker(build_dir)
+            if locker.try_lock():
+                try:
+                    self._write_ninja_file_and_build_library(name, sources, cflags, ldflags, include_paths, build_dir)
+                finally:
+                    locker.release_lock()
+            else:
+                locker.wait()
+        logger.info(f'Loading extension module {name}...')
+
+    def _verify_ninja_availability(self):
+        """Check ninja is available."""
+        try:
+            subprocess.check_output('ninja --version'.split())
+        except Exception:
+            raise RuntimeError("Ninja is required to load C++ extensions")
+
+    def _write_ninja_file_and_build_library(self, module_name, sources, cflags, ldflags, include_paths, build_dir):
+        """Write ninja file and build library."""
+        self._verify_ninja_availability()
+
+        ninja_build_file = os.path.join(build_dir, 'build.ninja')
+        logger.info(f'Save ninja build file {ninja_build_file}.')
+        self._write_ninja_file(ninja_build_file, module_name, sources, cflags, ldflags, include_paths)
+
+        logger.info(f'Building extension module {module_name}.')
+        self._run_ninja_build(build_dir, module_name)
+
+    def _write_ninja_file(self, fname, name, sources, extra_cflags, extra_ldflags, extra_include_paths):
+        """Write ninja file."""
+        python_include_path = sysconfig.get_path('include', scheme='posix_prefix')
+        python_includes = [python_include_path] if python_include_path is not None else []
+        cflags = [f'-DMS_EXTENSION_NAME={name}', "-D_GLIBCXX_USE_CXX11_ABI=0"]
+        cflags += [f'-I{shlex.quote(os.path.abspath(include.strip()))}' for include in extra_include_paths]
+        cflags += [f'-isystem {shlex.quote(include)}' for include in python_includes]
+        cflags += ['-fPIC', '-std=c++17']
+        cflags += extra_cflags
+        cflags = [flag.strip() for flag in cflags]
+
+        # '/path/to/file.cpp' -> 'file'
+        objs = [os.path.splitext(os.path.basename(src))[0] + ".o" for src in sources]
+        sources = [os.path.abspath(file) for file in sources]
+        ldflags = ['-shared'] + [flag.strip() for flag in extra_ldflags]
+        target = name + '.so'
+
+        config = ['ninja_required_version = 1.3']
+        config.append('cxx = ' + os.environ.get('CXX', 'g++'))
+
+        flags = [f'cflags = {" ".join(cflags)}']
+        flags.append(f'ldflags = {" ".join(ldflags)}')
+
+        compile_rule = ['rule compile']
+        compile_rule.append('  command = $cxx -MMD -MF $out.d $cflags -c $in -o $out')
+        compile_rule.append('  depfile = $out.d')
+        compile_rule.append('  deps = gcc')
+
+        build = [f'build {obj.replace(" ", "$ ")}: compile {src.replace(" ", "$ ")}' for src, obj in zip(sources, objs)]
+
+        link_rule = ['rule link', '  command = $cxx $in $ldflags -o $out']
+        link = [f'build {target}: link {" ".join(objs)}']
+        default = [f'default {target}']
+
+        blocks = [config, flags, compile_rule, link_rule, build, link, default]
+        content = "\n\n".join("\n".join(b) for b in blocks) + "\n"
+
+        if os.path.exists(fname):
+            with open(fname) as f:
+                old_content = f.read()
+            if old_content == content:
+                return
+
+        with open(fname, 'w') as source_file:
+            source_file.write(content)
+
+    def _run_ninja_build(self, build_dir, module_name):
+        """Run ninja build."""
+        cmd = ['ninja', '-v']
+        env = os.environ.copy()
+
+        try:
+            subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, cwd=build_dir, check=True, env=env)
+            # If the build succeeds, do nothing with the output (silent)
+        except subprocess.CalledProcessError as e:
+            # Capture the error details
+            stderr_output = e.stderr.decode() if e.stderr else ""
+            stdout_output = e.stdout.decode() if e.stdout else ""
+            full_output = stderr_output + stdout_output
+
+            # Format the error message
+            msg = f"Error building extension '{module_name}': {full_output}"
+
+            # In multi-card situation, only one process build the library.
+            # When building failed, the old extension library should be removed.
+            so_file = os.path.join(build_dir, f"{module_name}.so")
+            if os.path.exists(so_file):
+                os.remove(so_file)
+            raise RuntimeError(msg) from e
+
+    def build(self, module_name, sources, extra_cflags=None, extra_ldflags=None, extra_include_paths=None):
+        """Build module."""
+        src = [sources] if isinstance(sources, str) else sources
+        build_dir = self._get_build_directory(module_name)
+        self._compile(module_name, src, extra_cflags, extra_ldflags, extra_include_paths, build_dir)
+        return os.path.join(build_dir, f"{module_name}.so")

mindspore/ops/operations/_grad_ops.py

@@ -36,7 +36,7 @@ from ..auto_generate import (AbsGrad, ACosGrad, LogitGrad, AcoshGrad, AsinGrad,
                              ResizeBicubicGrad, HSigmoidGrad, CholeskyGrad, ResizeNearestNeighborGrad, LayerNormGrad,
                              HShrinkGrad, LayerNormGradGrad, SiLUGrad, MaximumGrad, MaximumGradGrad, RmsNormGrad,
                              FlashAttentionScoreGrad, UpsampleTrilinear3DGrad, UpsampleNearest3DGrad, MaskedSelectGrad,
-                             BinaryCrossEntropyGrad, SoftShrinkGrad, SeluGrad, SmoothL1LossGrad)
+                             BinaryCrossEntropyGrad, SoftShrinkGrad, SoftMarginLossGrad, SeluGrad, SmoothL1LossGrad)
 
 
 class SparseFillEmptyRowsGrad(Primitive):
@@ -1639,15 +1639,6 @@ class SliceGrad(PrimitiveWithInfer):
                 'value': None}
 
 
-class SoftMarginLossGrad(Primitive):
-    """Computes gradient for prediction on SoftMarginLoss."""
-
-    @prim_attr_register
-    def __init__(self, reduction="mean"):
-        self.init_prim_io_names(inputs=['predict', 'label', "dout"], outputs=['gradient'])
-        self.reduction = validator.check_string(reduction, ['none', 'sum', 'mean'], 'reduction', self.name)
-
-
 class StridedSliceGrad(Primitive):
     """
     Performs grad of StridedSlice operation.

mindspore/ops/operations/_inner_ops.py

@@ -21,7 +21,6 @@ import weakref
 import numpy as np
 
 from mindspore.common import Tensor
-from mindspore.common._stub_tensor import StubTensor
 from mindspore.ops import composite as C
 from mindspore.ops.operations.array_ops import Cast
 from mindspore.ops.operations._scalar_ops import bit_or, bit_and
@@ -29,7 +28,7 @@ from mindspore.ops import signature as sig
 from mindspore.ops.operations.math_ops import _infer_shape_reduce
 from mindspore.ops.primitive import PrimitiveWithCheck, PrimitiveWithInfer, prim_attr_register, Primitive, \
     _run_op, _check_contains_variable
-from mindspore._c_expression import Tensor as Tensor_
+from mindspore._c_expression import TensorPy as Tensor_
 from mindspore._c_expression import typing, HookType
 from mindspore._c_expression import pyboost_generator
 from mindspore import _checkparam as validator
@@ -38,8 +37,6 @@ from mindspore.common.parameter import Parameter
 from mindspore.common._stub_tensor import _convert_stub
 from mindspore.communication.management import GlobalComm, get_rank, _get_group, get_group_size
 from mindspore.common.api import _pynative_executor
-from mindspore.common._register_for_adapter import ms_adapter_registry
-from mindspore import ops
 from ..auto_generate import TensorCopySlices, SiLU, Cummin, TopKRouter, ExtractImagePatches, DecoderKVCache, \
     PromptKVCache, ApplyCamePart1, ApplyCamePart2, ApplyCamePart3, ApplyCamePart4
 
@@ -668,17 +665,17 @@ class ErrorOnDynamicShapeInput(PrimitiveWithInfer):
 
 class SequenceMask(PrimitiveWithCheck):
     """
-    Returns a mask tensor representing the first N positions of each cell.
+    Returns a mask tensor representing the first N positions of each cell. The internal element data type is bool.
 
     If lengths has shape [d_1, d_2, ..., d_n], then the resulting tensor mask has type and shape
     [d_1, d_2, ..., d_n, maxlen], with mask[i_1, i_2, ..., i_n, j] = (j < lengths[i_1, i_2, ..., i_n])
 
     Inputs:
-        - **lengths** (Tensor) - Tensor to calculate the mask for. All values in this tensor should be
+        - **lengths** (Tensor) - The input tensor. All values in this tensor should be
           less than or equal to `maxlen`. Values greater than `maxlen` will be treated as `maxlen`.
           Must be type int32 or int64.
 
-        - **maxlen** (int) - size of the last dimension of returned tensor. Must be positive and same
+        - **maxlen** (int) - Specify the length of the returned tensor. Must be positive and same
           type as elements in `lengths`.
 
     Outputs:
@@ -2256,74 +2253,6 @@ class IsInstance(PrimitiveWithInfer):
         return out
 
 
-class ConvertToAdapterTensor(Primitive):
-    """
-    Convert a tensor from MindSpore's Tensor type to MSAdapter's Tensor type,
-    where MSAdapter's Tensor is a subclass of MindSpore's Tensor.
-
-    Inputs:
-        - **x** (Tensor) - The input tensor.
-
-    Outputs:
-        A tensor, whose type is MSAdapter's Tensor.
-
-    Supported Platforms:
-        ``Ascend`` ``GPU`` ``CPU``
-
-    Examples:
-        >>> x = Tensor([1, 2 ,3])
-        >>> x = ops.ConvertToAdapterTensor()(x)
-        >>> print(x)
-        [1 2 3]
-    """
-
-    @prim_attr_register
-    def __init__(self):
-        """Initialize"""
-
-    def __call__(self, x):
-        """Run in PyNative mode"""
-        return ms_adapter_registry.tensor(x, cast_tensor=True)
-
-
-convert_to_adapter_tensor = ConvertToAdapterTensor()
-
-
-class ConvertToMsTensor(Primitive):
-    """
-    Convert a tensor from MSAdapter's Tensor type to MindSpore's Tensor type,
-    where MSAdapter's Tensor is a subclass of MindSpore's Tensor.
-
-    Inputs:
-        - **x** (Tensor) - The input tensor.
-
-    Outputs:
-        A tensor, whose type is MindSpore's Tensor.
-
-    Supported Platforms:
-        ``Ascend`` ``GPU`` ``CPU``
-
-    Examples:
-        >>> x = Tensor([1, 2 ,3])
-        >>> x = ops.ConvertToMsTensor()(x)
-        >>> print(x)
-        [1 2 3]
-    """
-
-    @prim_attr_register
-    def __init__(self):
-        """Initialize"""
-
-    def __call__(self, x):
-        """Run in PyNative mode"""
-        if isinstance(x, StubTensor):
-            return StubTensor(stub=x.stub, tensor=x.tensor)
-        return ops.auto_generate.deepcopy(x)
-
-
-convert_to_ms_tensor = ConvertToMsTensor()
-
-
 class GetGrad(Primitive):
     """
         Use the position id or Parameter object to get the gradient from the output
@@ -2475,7 +2404,7 @@ class FFN(Primitive):
     The FFN computation is similar to Feed-Forward Network, it contains matmul + gelu + matmul.
 
     Args:
-        activation (string): The activation type, set to 'fastgelu' or 'gelu'.
+        activation (str): The activation type, set to 'fastgelu' or 'gelu'.
             Only support 'fastgelu' for now. Default: "fastgelu".
         inner_precise (int): The precise mode, set to 0 for high precision or 1 for high performance.
             Only support 1 for now. Default: 0.

mindspore/ops/operations/_ms_kernel.py

@@ -496,7 +496,7 @@ def kernel(fn=None, reg_info=None, compile_attrs=None):
         callable function is equal to the case when `fn` is not None.
 
     Supported Platforms:
-        ``Ascend`` ``GPU`` ``CPU``
+        ``GPU`` ``CPU``
 
     Examples:
         >>> import numpy as np
@@ -510,12 +510,12 @@ def kernel(fn=None, reg_info=None, compile_attrs=None):
         ...     "test3": 12,
         ... }
         >>> # Create the reg info json string.
-        >>> op_gpu_info = CustomRegOp() \\
+        >>> op_cpu_info = CustomRegOp() \\
         ...     .input(0, "a") \\
         ...     .input(0, "b") \\
         ...     .output(0, "y") \\
         ...     .dtype_format(DataType.F32_None, DataType.F32_None, DataType.F32_None) \\
-        ...     .target("GPU") \\
+        ...     .target("CPU") \\
         ...     .get_op_info()
         >>>
         >>> # Create inputs for the custom op.
@@ -524,7 +524,7 @@ def kernel(fn=None, reg_info=None, compile_attrs=None):
         ...
         >>> # Write a Hybrid DSL function through the decorator @kernel.
         >>> # We can also pass the compile attrs and the reg info through the decorator.
-        >>> @kernel(reg_info=op_gpu_info, compile_attrs=attrs)
+        >>> @kernel(reg_info=op_cpu_info, compile_attrs=attrs)
         ... def outer_product(a, b):
         ...     c = output_tensor(a.shape, a.dtype)
         ...
@@ -539,12 +539,6 @@ def kernel(fn=None, reg_info=None, compile_attrs=None):
         >>> # We can use the function directly as a python function.
         >>> # In this case, the inputs should be numpy arrays.
         >>> result = outer_product(input_x, input_y)
-        ...
-        >>> # Create a custom op with mode "hybrid" (default value) by the Hybrid DSL function.
-        >>> # In this case, we will enjoy the automatic dtype/shape infer for free.
-        >>> # The inputs should be mindspore tensors.
-        >>> test_op_hybrid = ops.Custom(outer_product)
-        >>> output = test_op_hybrid(Tensor(input_x), Tensor(input_y))
     """
     if compile_attrs is None:
         compile_attrs = {}

mindspore/ops/operations/_rl_inner_ops.py

@@ -859,7 +859,7 @@ class TensorsQueueCreate(PrimitiveWithInfer):
         dtype (mindspore.dtype): the data type in the TensorsQueue.
         shapes (tuple(tuple(int))): the shape of each tensor in element.
         size (int): The size of the TensorsQueue.
-        name (string): the name of this TensorsQueue. Default: "Q".
+        name (str): the name of this TensorsQueue. Default: "Q".
 
     Inputs:
         None.

mindspore/ops/operations/_scalar_ops.py

@@ -1,4 +1,4 @@
-# Copyright 2023 Huawei Technologies Co., Ltd
+# Copyright 2023-2025 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.
@@ -16,7 +16,8 @@
 
 from mindspore.ops.primitive import Primitive, prim_attr_register
 from .manually_defined import ScalarAdd, ScalarBool, ScalarDiv, ScalarMul, ScalarEq, ScalarFloorDiv, ScalarGe, \
-    ScalarGt, ScalarLe, ScalarLog, ScalarLt, ScalarMod, ScalarPow, ScalarSub, ScalarUadd, ScalarUsub
+    ScalarGt, ScalarLe, ScalarLog, ScalarLt, ScalarMod, ScalarPow, ScalarSub, ScalarUadd, ScalarUsub, ScalarMax, \
+    ScalarMin
 
 
 class bool_not(Primitive):

mindspore/ops/operations/_sequence_ops.py

@@ -16,7 +16,7 @@
 from mindspore.ops.primitive import Primitive, PrimitiveWithCheck, prim_attr_register
 import mindspore._checkparam as validator
 from mindspore.common import Tensor
-from mindspore._c_expression import Tensor as Tensor_
+from mindspore._c_expression import TensorPy as Tensor_
 
 
 class ListAppend(Primitive):

mindspore/ops/operations/_tensor_array.py

@@ -33,7 +33,7 @@ class TensorArray(PrimitiveWithInfer):
         element_shape (tuple[int]): the shape of each tensor in a TensorArray.
         dynamic_size (bool): If true the TensorArray can increase the size. Default: ``True``.
         size (int): The size of the TensorArray if dynamic_size = False.
-        name (string): the name of this TensorArray. Default: "TA".
+        name (str): the name of this TensorArray. Default: "TA".
 
     Inputs:
         None.

mindspore/ops/operations/array_ops.py

@@ -32,7 +32,7 @@ from mindspore._checkparam import _check_3d_int_or_tuple
 from mindspore.common import dtype as mstype
 from mindspore.common._decorator import deprecated
 from mindspore.common import Tensor, CSRTensor, COOTensor
-from mindspore._c_expression import Tensor as Tensor_
+from mindspore._c_expression import TensorPy as Tensor_
 from mindspore._c_expression import CSRTensor as CSRTensor_
 from mindspore._c_expression import COOTensor as COOTensor_
 from ..auto_generate import (
@@ -273,7 +273,7 @@ class Im2Col(Primitive):
     each sliding `ksizes`- sized block within the spatial dimensions
     of input `x` into a column (i.e., last dimension) of a 4-D output
     tensor of shape :math:`(N, C, \prod(\text{kernel_size}), L)`, where
-    :math:`C \times \prod(\text{kernel_size})` is the total number of values
+    :math:`C \times \prod(\text{kernel_size})` is the total number of elements
     within each block (a block has :math:`\prod(\text{kernel_size})` spatial
     locations each containing a `C`-channeled vector), and :math:`L` is
     the total number of such blocks:
@@ -1169,7 +1169,7 @@ class TupleToArray(PrimitiveWithInfer):
 
     Inputs:
         - **input_x** (tuple) - A tuple of numbers. These numbers have the same type.
-          The shape is :math:`(N,*)` where :math:`*` means any number of additional dimensions.
+          The shape is :math:`(N,)`.
 
     Outputs:
         Tensor, if the input tuple contains `N` numbers, then the shape of the output tensor is :math:`(N,)`.
@@ -1802,9 +1802,9 @@ class Unstack(Primitive):
     Refer to :func:`mindspore.ops.unstack` for more details.
 
     Args:
-        axis (int): Dimension along which to unpack. Default: ``0`` .
+        axis (int, optional): Dimension along which to unpack. Default: ``0`` .
             Negative values wrap around. The range is [-R, R).
-        num (Union[None, int]): The number of output tensors.
+        num (Union[None, int], optional): The number of output tensors.
             Automatically inferred by input_x and axis if ``None`` . Default: ``None`` .
 
     Inputs:
@@ -2113,7 +2113,7 @@ class ScatterNdUpdate(Primitive):
     the relatively highest priority data type.
 
     Args:
-        use_locking (bool): Whether to protect the assignment by a lock. Default: ``True`` .
+        use_locking (bool, optional): Whether to protect the assignment by a lock. Default: ``True`` .
 
     Inputs:
         - **input_x** (Union[Parameter, Tensor]) - The target tensor, with data type of Parameter or Tensor.
@@ -2244,7 +2244,7 @@ class ScatterMin(_ScatterOpDynamic):
     when `updates` does not support conversion to the data type required by `input_x`.
 
     Args:
-        use_locking (bool): Whether to protect the assignment by a lock. Default: ``False`` .
+        use_locking (bool, optional): Whether to protect the assignment by a lock. Default: ``False`` .
 
     Inputs:
         - **input_x** (Union[Parameter, Tensor]) - The target tensor, with data type of Parameter or Tensor.
@@ -2306,7 +2306,7 @@ class ScatterAdd(Primitive):
         This is an in-place update operator. Therefore, the `input_x` will be updated after the operation is completed.
 
     Args:
-        use_locking (bool): Whether to protect the assignment by a lock.
+        use_locking (bool, optional): Whether to protect the assignment by a lock.
             If ``True`` , `input_x` will be protected by the lock.
             Otherwise, the calculation result is undefined. Default: ``False`` .
 
@@ -2426,7 +2426,7 @@ class ScatterSub(Primitive):
     the relatively highest priority data type.
 
     Args:
-        use_locking (bool): Whether to protect the assignment by a lock. Default: ``False`` .
+        use_locking (bool, optional): Whether to protect the assignment by a lock. Default: ``False`` .
 
     Inputs:
         - **input_x** (Union[Parameter, Tensor]) - The target tensor, with data type of Parameter or Tensor.
@@ -3037,7 +3037,7 @@ class ScatterNdDiv(_ScatterNdOp):
 
 class ScatterNdMax(_ScatterNdOp):
     r"""
-    Applies sparse maximum to individual values or slices in a tensor.
+    Computes sparse maximum to individual values or slices in a tensor.
 
     Using given values to update parameter value through the maximum operation, along with the input indices.
     This operation outputs the `input_x` after the update is done, which makes it convenient to use the updated value.
@@ -3587,7 +3587,7 @@ class ReverseSequence(PrimitiveWithInfer):
 
     Args:
         seq_dim (int): The dimension where reversal is performed. Required.
-        batch_dim (int): The input is sliced in this dimension. Default: ``0`` .
+        batch_dim (int, optional): The input is sliced in this dimension. Default: ``0`` .
 
     Inputs:
         - **x** (Tensor) - The input to reverse, supporting all number types including bool.
@@ -3838,10 +3838,11 @@ class EmbeddingLookup(Primitive):
     `offset`.
 
     Inputs:
-        - **input_params** (Tensor) - The shape of tensor is :math:`(x_1, x_2, ..., x_R)`.
-          This represents a Tensor slice, instead of the entire Tensor. Currently, the dimension is restricted to be 2.
-        - **input_indices** (Tensor) - The shape of tensor is :math:`(y_1, y_2, ..., y_S)`.
-          Specifies the indices of elements of the original Tensor. Values can be out of range of `input_params`,
+        - **input_params** (Tensor) - a Tensor slice, the shape is :math:`(x_1, x_2, ..., x_R)`.
+          Currently, the dimension is restricted to be 2.
+        - **input_indices** (Tensor) - Specifies the indices of elements of the original Tensor.
+          The shape is :math:`(y_1, y_2, ..., y_S)`.
+          Values can be out of range of `input_params`,
           and the exceeding part will be filled with 0 in the output. Values do not support negative and the result
           is undefined if values are negative. The data type should be int32 or int64.
         - **offset** (int) - Specifies the offset value of this `input_params` slice. Thus the real indices
@@ -4068,7 +4069,8 @@ class TensorScatterUpdate(_TensorScatterOp):
     r"""
     Creates a new tensor by updating the positions in `input_x` indicated by
     `indices`, with values from `update`. This operation is almost equivalent to using
-    :class:`mindspore.ops.ScatterNdUpdate` , except that the updates are applied on `input_x` instead of a zero tensor.
+    :class:`mindspore.ops.ScatterNdUpdate` , except that the updates are applied on output `Tensor`
+    instead of `input_x`.
 
     `indices` must have rank at least 2, the last axis is the depth of each index
     vectors. For each index vector, there must be a corresponding value in `update`. If
@@ -4230,12 +4232,25 @@ class TensorScatterSub(Primitive):
     r"""
     Creates a new tensor by subtracting the values from the positions in `input_x` indicated by
     `indices`, with values from `updates`. When multiple values are provided for the same
-    index, the result of the update will be to subtract these values respectively. This operation is almost
+    index, the result of the update will subtract these values respectively. This operation is almost
     equivalent to using :class:`mindspore.ops.ScatterNdSub` , except that the updates are applied on output `Tensor`
     instead of input `Parameter`.
 
-    .. math::
-        output\left [indices  \right ] = input\_x- update
+    .. code-block:: python
+
+        # Iterate through all index
+        for i in range(indices.shape[0]):
+            for j in range(indices.shape[1]):
+                ...
+                for k in range(indices.shape[-2]):  # The last dimension is coordinate dimension
+                    # Get current index combination
+                    index_tuple = (i, j, ..., k)
+                    # Get target position
+                    target_index = indices[index_tuple]
+                    # Get corresponding update value
+                    update_value = updates[index_tuple]
+                    # Perform subtraction operation
+                    output[target_index] -= update_value
 
     Refer to :func:`mindspore.ops.tensor_scatter_sub` for more details.
 
@@ -5522,7 +5537,7 @@ class AffineGrid(Primitive):
 
     Args:
         align_corners (bool, optional): Geometrically, each pixel of input is viewed as a squqre instead of dot.
-            If True, consider extremum -1 and 1 referring to the centers of the pixels rather than pixel corners.
+            If ``True``, consider extremum -1 and 1 referring to the centers of the pixels rather than pixel corners.
             The default value is ``False`` , extremum -1 and 1 refer to the corners of the pixels, so that sampling is
             irrelevant to resolution of the image. Default: ``False`` .
 
@@ -5534,7 +5549,7 @@ class AffineGrid(Primitive):
           or :math:`(N, C, D, H, W)` for 3D grid.
 
     Outputs:
-        Tensor, a tensor whose data type is same as 'theta', and the shape is :math:`(N, H, W, 2)` for 2D grid
+        Tensor, a tensor whose data type is same as `theta`, and the shape is :math:`(N, H, W, 2)` for 2D grid
         or :math:`(N, D, H, W, 3)` for 3D grid.
 
     Supported Platforms:
@@ -5743,7 +5758,7 @@ class TopK(Primitive):
           - CPU: all numeric types.
 
         - **k** (Union(Tensor, int)) - The number of top elements to be computed along the last dimension.
-          If `k` is a Tensor, the supported dtype is int32 and it should be 0-D or 1-D with shape :math:`(1, )` .
+          The supported dtype is int32 and it should be 0-D or 1-D Tensor with shape :math:`(1, )` .
 
     Outputs:
         A tuple consisting of `values` and `indexes`.