mindspore 2.3.0__cp310-cp310-win_amd64.whl → 2.4.0__cp310-cp310-win_amd64.whl

mindspore/numpy/array_creations.py

@@ -1,4 +1,4 @@
-# Copyright 2020-2021 Huawei Technologies Co., Ltd
+# Copyright 2020-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.
@@ -278,7 +278,7 @@ def ones(shape, dtype=mstype.float32):
     Args:
         shape (Union[int, tuple, list]): the shape of the new tensor.
         dtype (Union[:class:`mindspore.dtype`, str], optional): Designated tensor dtype.
-            Default is :class:`mstype.float32`.
+            Default is ``mstype.float32``.
 
     Returns:
         Tensor, with the designated `shape` and `dtype`, filled with ones.
@@ -311,7 +311,7 @@ def zeros(shape, dtype=mstype.float32):
     Args:
         shape (Union[int, tuple, list]): the shape of the new tensor.
         dtype (Union[:class:`mindspore.dtype`, str], optional): Designated tensor dtype.
-            Default is :class:`mstype.float32`.
+            Default is mstype.float32.
 
     Returns:
         Tensor, with the designated `shape` and `dtype`, filled with zeros.
@@ -433,7 +433,7 @@ def randn(*shape, dtype=mstype.float32):
         *shape (Union[int, tuple(int), list(int)]): Shape of the new tensor, e.g.,
             :math:`(2, 3)` or :math:`2`.
         dtype (Union[:class:`mindspore.dtype`, str], optional): Designated tensor dtype, it must
-            be float type. Default is :class:`mindspore.float32`.
+            be float type. Default is ``mindspore.float32``.
 
     Returns:
         Tensor, with the designated shape and dtype, filled with a sample (or samples)
@@ -474,7 +474,7 @@ def rand(*shape, dtype=mstype.float32):
         *shape (Union[int, tuple(int), list(int)]): Shape of the new tensor, e.g.,
             :math:`(2, 3)` or :math:`2`.
         dtype (Union[:class:`mindspore.dtype`, str], optional): Designated tensor dtype, it must
-            be float type. Default is :class:`mindspore.float32`.
+            be float type. Default is ``mindspore.float32``.
 
     Returns:
         Tensor, with the designated shape and dtype, filled with random numbers from the
@@ -519,7 +519,7 @@ def randint(minval, maxval=None, shape=None, dtype=mstype.int32):
         maxval(Union[int], optional): End value of interval. The interval does not include this value.
         shape (Union[int, tuple(int)]): Shape of the new tensor, e.g., :math:`(2, 3)` or :math:`2`.
         dtype (Union[:class:`mindspore.dtype`, str], optional): Designated tensor dtype, it must
-            be int type. Default is :class:`mindspore.int32`.
+            be int type. Default is `mindspore.int32`.
 
     Returns:
         Tensor, with the designated shape and dtype, filled with random integers from minval (inclusive)
@@ -1068,9 +1068,9 @@ def ones_like(a, dtype=None, shape=None):
         a (Union[Tensor, list, tuple]): The shape and data-type of a define these same
             attributes of the returned array.
         dtype (:class:`mindspore.dtype`, optional): Overrides the data type of the
-            result.
-        shape (int or sequence of ints, optional): Overrides the shape
-            of the result.
+            result. Default: ``None``.
+        shape (int, sequence of ints, optional): Overrides the shape
+            of the result. Default: ``None``.
 
     Returns:
         Tensor, array of ones with the same shape and type as `a`.
@@ -1107,7 +1107,7 @@ def zeros_like(a, dtype=None, shape=None):
             attributes of the returned array.
         dtype (:class:`mindspore.dtype`, optional): Overrides the data type of the
             result.
-        shape (int or sequence of ints, optional): Overrides the shape
+        shape (int, sequence of ints, optional): Overrides the shape
             of the result.
 
     Returns:
@@ -1137,8 +1137,8 @@ def full_like(a, fill_value, dtype=None, shape=None):
     Returns a full array with the same shape and type as a given array.
 
     Note:
-        Input array must have the same size across a dimension.
-        If `a` is not a Tensor, dtype is float32 by default if not provided.
+        - Input array must have the same size across a dimension.
+        - If `a` is not a Tensor, dtype is float32 by default if not provided.
 
     Args:
         a (Union[Tensor, list, tuple]): The shape and data-type of `a` define these same
@@ -1146,7 +1146,7 @@ def full_like(a, fill_value, dtype=None, shape=None):
         fill_value (scalar): Fill value.
         dtype (:class:`mindspore.dtype`, optional): Overrides the data type of the
             result.
-        shape (int or sequence of ints, optional): Overrides the shape
+        shape (int, sequence of ints, optional): Overrides the shape
             of the result.
 
     Returns:
@@ -1178,7 +1178,7 @@ def tri(N, M=None, k=0, dtype=mstype.float32):
     Args:
         N(int): Number of rows in the array.
         M(int, optional): Number of columns in the array. By default, `M` is taken
-            equal to N.
+            equal to N. Default: ``None`` .
         k(int, optional): The sub-diagonal at and below which the array is filled.
             :math:`k = 0` is the main diagonal, while :math:`k < 0` is below it, and :math:`k > 0` is above.
             Default: ``0`` .
@@ -1382,47 +1382,44 @@ def diagonal(a, offset=0, axis1=0, axis2=1):
 
 def trace(a, offset=0, axis1=0, axis2=1, dtype=None):
     """
-    Returns the sum along diagonals of the array.
-
-    If `a` is 2-D, the sum along its diagonal with the given offset is returned,
-    i.e., the sum of elements ``a[i,i+offset]`` for all `i`.
-    If `a` has more than two dimensions, then the axes specified by `axis1` and
-    `axis2` are used to determine the 2-D sub-arrays whose traces are returned.
-    The shape of the resulting array is the same as that of a with `axis1` and
-    `axis2` removed.
+    Return the sum along diagonals of the tensor.
 
     Note:
-        On GPU, the supported dtypes are np.float16, and np.float32.
-        On CPU, the supported dtypes are np.float16, np.float32, and np.float64.
+        - `trace` is currently only used in `mindscience` scientific computing scenarios and
+          dose not support other usage scenarios.
+        - `trace` is not supported on Windows platform yet.
 
     Args:
-        a (Tensor): Array from which the diagonals are taken.
+        a (Tensor): A matrix to be calculated.
         offset (int, optional): Offset of the diagonal from the main diagonal.
-            Can be positive or negative. Defaults to main diagonal.
+          Can be positive or negative. Default: ``0``.
         axis1 (int, optional): Axis to be used as the first axis of the 2-D
-            sub-arrays from which the diagonals should be taken. Defaults to
-            first axis (0).
+          sub-arrays from which the diagonals should be taken. Default: ``0``.
         axis2 (int, optional): Axis to be used as the second axis of the 2-D
-            sub-arrays from which the diagonals should be taken. Defaults to
-            second axis.
-        dtype (:class:`mindspore.dtype`, optional): Default: ``None`` . Overrides the dtype of the
-            output Tensor.
+          sub-arrays from which the diagonals should be taken. Default: ``1``.
+        dtype (:class:`mindspore.dtype`, optional): Overrides the dtype of the
+          output Tensor if not ``None``. Default: ``None``.
 
     Returns:
-        Tensor, sum_along_diagonals. If `a` is 2-D, the sum along the diagonal
-        is returned. If `a` has larger dimensions, then an array of sums along
-        diagonals is returned.
+        Tensor, the sum along diagonals. If `a` is 2-D, the sum along the diagonal is returned.
+        If `a` has more than two dimensions, then the axes specified by `axis1` and `axis2` are used
+        to determine the 2-D sub-arrays whose traces are returned. The shape of the resulting
+        array is the same as that of `a` with `axis1` and `axis2` removed.
 
     Raises:
-        ValueError: If the input tensor has less than two dimensions.
+        ValueError: If `a` has less than two dimensions.
+        ValueError: If `axis1` or `axis2` is not in [-dims, dims), which dims is dimension of `a`.
+        ValueError: If axes specified by `axis1` and `axis2` are same.
 
     Supported Platforms:
         ``Ascend`` ``GPU`` ``CPU``
 
     Examples:
-        >>> import mindspore.numpy as np
-        >>> output = np.trace(np.eye(3))
-        >>> print(output)
+        >>> import numpy as np
+        >>> from mindspore import Tensor
+        >>> from mindspore.numpy import trace
+        >>> x = Tensor(np.eye(3, dtype=np.float32))
+        >>> print(trace(x))
         3.0
     """
     return a.trace(offset=offset, axis1=axis1, axis2=axis2, dtype=dtype)
@@ -1589,7 +1586,7 @@ class NdGrid:
 
 class MGridClass(NdGrid):
     """
-    mgrid is an :class:`NdGrid` instance with ``sparse=False``.
+    mgrid is an `NdGrid` instance with ``sparse=False``.
 
     The dimension and number of the output arrays are equal to the number
     of indexing dimensions. If the step length is not a complex number,
@@ -1638,7 +1635,7 @@ class MGridClass(NdGrid):
 
 class OGridClass(NdGrid):
     """
-    ogrid is an :class:`NdGrid` instance with ``sparse=True``.
+    ogrid is an `NdGrid` instance with ``sparse=True``.
 
     The dimension and number of the output arrays are equal to the number
     of indexing dimensions. If the step length is not a complex number,
@@ -1957,8 +1954,8 @@ def indices(dimensions, dtype=mstype.int32, sparse=False):
     varying only along the corresponding axis.
 
     Args:
-        dimensions (tuple or list of ints): The shape of the grid.
-        dtype (:class:`mindspore.dtype`, optional): Data type of the result.
+        dimensions (Union[list(int), tuple]): The shape of the grid.
+        dtype (:class:`mindspore.dtype`, optional): Data type of the result. Default: ``mstype.int32``.
         sparse (boolean, optional): Default: ``False`` . Return a sparse
             representation of the grid instead of a dense representation.
 
@@ -2167,7 +2164,7 @@ def triu_indices(n, k=0, m=None):
         n (int): The size of the arrays for which the returned indices will be valid.
         k (int, optional): Diagonal offset, default: ``0`` .
         m (int, optional): The column dimension of the arrays for which the returned
-            arrays will be valid. By default `m` is taken equal to `n`.
+            arrays will be valid. By default `m` is taken equal to `n`. Default: ``None`` .
 
     Returns:
         The indices for the triangle. The returned tuple contains two tensors, each
@@ -2196,7 +2193,7 @@ def tril_indices(n, k=0, m=None):
         n (int): The size of the arrays for which the returned indices will be valid.
         k (int, optional): Diagonal offset, default: ``0`` .
         m (int, optional): The column dimension of the arrays for which the returned
-            arrays will be valid. By default `m` is taken equal to `n`.
+            arrays will be valid. By default `m` is taken equal to `n`. Default: ``None`` .
 
     Returns:
         The indices for the triangle. The returned tuple contains two tensors, each
@@ -2259,7 +2256,7 @@ def tril_indices_from(arr, k=0):
 
     Returns:
         triu_indices_from, tuple of 2 tensor, shape(N)
-        Indices for the upper-triangle of `arr`.
+        Indices for the lower-triangle of `arr`.
 
     Raises:
         TypeError: If `arr` cannot be converted to tensor, or `k` is not a number.
@@ -2291,15 +2288,15 @@ def histogram_bin_edges(a, bins=10, range=None, weights=None):  # pylint: disabl
     Args:
         a (Union[int, float, bool, list, tuple, Tensor]): Input data. The histogram
             is computed over the flattened array.
-        bins ((Union[int, tuple, list, Tensor])): If `bins` is an int, it defines the number
+        bins (Union[int, tuple, list, Tensor], optional): If `bins` is an int, it defines the number
             of equal-width bins in the given range (10, by default). If `bins` is a
             sequence, it defines the bin edges, including the rightmost edge,
             allowing for non-uniform bin widths.
-        range((float, float), optional): The lower and upper range of the bins. If
+        range ((float, float), optional): The lower and upper range of the bins. If
             not provided, `range` is simply ``(a.min(), a.max())``. Values outside
             the range are ignored. The first element of the range must be less than
             or equal to the second. Default: ``None`` .
-        weights(Union[int, float, bool, list, tuple, Tensor], optional):  An array of weights,
+        weights (Union[int, float, bool, list, tuple, Tensor], optional):  An array of weights,
             of the same shape as `a`. Each value in `a` only contributes its associated weight
             towards the bin count (instead of 1). This is currently not used by any of the bin
             estimators, but may be in the future. Default: ``None`` .
@@ -2623,10 +2620,10 @@ def pad(arr, pad_width, mode="constant", stat_length=None, constant_values=0,
     Args:
         arr (Union[list, tuple, Tensor]): The array to pad.
         pad_width (Union[int, tuple, list]): Number of values padded to the edges of
-            each axis. :class:`((before_1, after_1), ... (before_N, after_N))` creates
-            unique pad widths for each axis. :class:`((before, after),)` yields same
-            before and after pad for each axis. :class:`(pad,)` or int is a shortcut
-            for :class:`before = after = pad width` for all axes.
+            each axis. ``((before_1, after_1), ... (before_N, after_N))`` creates
+            unique pad widths for each axis. ``((before, after),)`` yields same
+            before and after pad for each axis. ``(pad,)`` or int is a shortcut
+            for ``before = after = pad width`` for all axes.
         mode (string, optional):
             One of the following string values:
 
@@ -2645,26 +2642,26 @@ def pad(arr, pad_width, mode="constant", stat_length=None, constant_values=0,
               are used to pad the end and the end values are used to pad the beginning.
             - empty: Pads with undefined values.
             - <function>: The padding function, if used, should modify and return a new 1-d tensor.
-              It has the following signature: :class:`padding_func(tensor, iaxis_pad_width, iaxis, kwargs)`
+              It has the following signature: ``padding_func(tensor, iaxis_pad_width, iaxis, kwargs)``
         stat_length (Union[tuple, list, int], optional): Used in \'maximum\', \'mean\',
             \'median\', and \'minimum\'.  Number of values at edge of each axis used
-            to calculate the statistic value. :class:`((before_1, after_1), ... (before_N, after_N))`
-            creates unique statistic lengths for each axis. :class:`((before, after),)`
-            yields same before and after statistic lengths for each axis. :class:`(stat_length,)`
-            or int is a shortcut for :class:`before = after = statistic length` for all
+            to calculate the statistic value. ``((before_1, after_1), ... (before_N, after_N))``
+            creates unique statistic lengths for each axis. ``((before, after),)``
+            yields same before and after statistic lengths for each axis. ``(stat_length,)``
+            or int is a shortcut for ``before = after = statistic length`` for all
             axes. Default: ``None``, to use the entire axis.
         constant_values (Union[tuple, list, int], optional):
-            Used in :class:`constant mode`. The values to set the padded values for each
-            axis. :class:`((before_1, after_1), ... (before_N, after_N))` creates unique pad
-            constants for each axis. :class:`((before, after),)` yields same before and
-            after constants for each axis. :class:`(constant,)` or :class:`constant` is
-            a shortcut for :class:`before = after = constant` for all axes. Default: ``0`` .
+            Used in ``constant mode``. The values to set the padded values for each
+            axis. ``((before_1, after_1), ... (before_N, after_N))`` creates unique pad
+            constants for each axis. ``((before, after),)`` yields same before and
+            after constants for each axis. ``(constant,)`` or ``constant`` is
+            a shortcut for ``before = after = constant`` for all axes. Default: ``0`` .
         end_values (Union[tuple, list, int], optional): Used in 'linear_ramp'.  The values
             used for the ending value of the linear_ramp and that will form the edge of
-            the padded `arr`. :class:`((before_1, after_1), ... (before_N, after_N))`
-            unique end values for each axis. :class:`((before, after),)` yields same before
-            and after end values for each axis. :class:`(constant,)` or :class:`constant`
-            is a shortcut for :class:`before = after = constant` for all axes. Default: ``0`` .
+            the padded `arr`. ``((before_1, after_1), ... (before_N, after_N))``
+            unique end values for each axis. ``((before, after),)`` yields same before
+            and after end values for each axis. ``(constant,)`` or ``constant``
+            is a shortcut for ``before = after = constant`` for all axes. Default: ``0`` .
         reflect_type(string, optional) can choose between \'even\' and \'odd\'. Used in
             \'reflect\', and \'symmetric\'. The \'even\' style is the default with an
             unaltered reflection around the edge value. For the \'odd\' style, the extended
@@ -2680,7 +2677,7 @@ def pad(arr, pad_width, mode="constant", stat_length=None, constant_values=0,
         TypeError: If `arr`, `pad_width`, `stat_length`, `constant_values` or `end_values`
             have types not specified above.
         ValueError: If `mode` cannot be recognized, or if `pad_width`, `stat_length`,
-            `constant_values`, `end_values` cannot broadcast to :class:`(arr.ndim, 2)`,
+            `constant_values`, `end_values` cannot broadcast to ``(arr.ndim, 2)``,
             or if keyword arguments got unexpected inputs.
         NotImplementedError: If mode is function or \'median\'.