From 9280c1182b21c196e9cd9f1b319fda123bbff346 Mon Sep 17 00:00:00 2001 From: lilinjie Date: Sat, 4 Feb 2023 15:45:17 +0800 Subject: [PATCH] add cn docs for some apis --- docs/api/api_python/mindspore.nn.rst | 1 + .../api_python/mindspore.ops.primitive.rst | 1 + docs/api/api_python/mindspore.ops.rst | 16 ++ .../nn/mindspore.nn.PoissonNLLLoss.rst | 4 +- .../api_python/nn/mindspore.nn.Upsample.rst | 32 +++ docs/api/api_python/ops/mindspore.ops.Abs.rst | 2 +- .../ops/mindspore.ops.CountNonZero.rst | 8 + .../ops/mindspore.ops.TrilIndices.rst | 21 +- .../ops/mindspore.ops.TriuIndices.rst | 21 +- .../ops/mindspore.ops.func_aminmax.rst | 24 ++ .../ops/mindspore.ops.func_atan2.rst | 6 +- .../ops/mindspore.ops.func_atleast_1d.rst | 17 ++ .../ops/mindspore.ops.func_atleast_2d.rst | 17 ++ .../ops/mindspore.ops.func_atleast_3d.rst | 18 ++ .../ops/mindspore.ops.func_combinations.rst | 22 ++ .../ops/mindspore.ops.func_count_nonzero.rst | 19 +- .../ops/mindspore.ops.func_diag_embed.rst | 35 +++ .../ops/mindspore.ops.func_dstack.rst | 20 ++ .../ops/mindspore.ops.func_fmax.rst | 26 ++ .../ops/mindspore.ops.func_fmin.rst | 26 ++ .../ops/mindspore.ops.func_nanquantile.rst | 34 +++ .../ops/mindspore.ops.func_polygamma.rst | 24 ++ .../ops/mindspore.ops.func_quantile.rst | 31 ++ .../ops/mindspore.ops.func_sort.rst | 24 ++ .../ops/mindspore.ops.func_tril_indices.rst | 26 ++ .../ops/mindspore.ops.func_triu_indices.rst | 25 ++ .../ops/mindspore.ops.func_vstack.rst | 20 ++ docs/api/api_python_en/mindspore.nn.rst | 1 + .../api_python_en/mindspore.ops.primitive.rst | 1 + docs/api/api_python_en/mindspore.ops.rst | 16 ++ mindspore/python/mindspore/nn/layer/basic.py | 38 +-- .../python/mindspore/ops/function/__init__.py | 2 +- .../mindspore/ops/function/array_func.py | 60 ++-- .../mindspore/ops/function/math_func.py | 266 +++++++++--------- .../mindspore/ops/operations/array_ops.py | 6 +- .../mindspore/ops/operations/math_ops.py | 58 +--- 36 files changed, 683 insertions(+), 285 deletions(-) create mode 100644 docs/api/api_python/nn/mindspore.nn.Upsample.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.CountNonZero.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_aminmax.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_atleast_1d.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_atleast_2d.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_atleast_3d.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_combinations.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_diag_embed.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_dstack.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_fmax.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_fmin.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_nanquantile.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_polygamma.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_quantile.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_sort.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_tril_indices.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_triu_indices.rst create mode 100644 docs/api/api_python/ops/mindspore.ops.func_vstack.rst diff --git a/docs/api/api_python/mindspore.nn.rst b/docs/api/api_python/mindspore.nn.rst index 0c4fb5815ec..9862127dede 100644 --- a/docs/api/api_python/mindspore.nn.rst +++ b/docs/api/api_python/mindspore.nn.rst @@ -362,6 +362,7 @@ Dynamic LR函数 mindspore.nn.PixelShuffle mindspore.nn.PixelUnshuffle mindspore.nn.ResizeBilinear + mindspore.nn.Upsample 工具 ----- diff --git a/docs/api/api_python/mindspore.ops.primitive.rst b/docs/api/api_python/mindspore.ops.primitive.rst index ae864877b8e..bc0488dd79c 100644 --- a/docs/api/api_python/mindspore.ops.primitive.rst +++ b/docs/api/api_python/mindspore.ops.primitive.rst @@ -481,6 +481,7 @@ Array操作 mindspore.ops.Col2Im mindspore.ops.Concat mindspore.ops.ConjugateTranspose + mindspore.ops.CountNonZero mindspore.ops.Cummax mindspore.ops.Cummin mindspore.ops.CumProd diff --git a/docs/api/api_python/mindspore.ops.rst b/docs/api/api_python/mindspore.ops.rst index b21011ce61c..f281b8e0d3a 100644 --- a/docs/api/api_python/mindspore.ops.rst +++ b/docs/api/api_python/mindspore.ops.rst @@ -189,6 +189,9 @@ MindSpore中 `mindspore.ops` 接口与上一版本相比，新增、删除和支 mindspore.ops.atan mindspore.ops.atan2 mindspore.ops.atanh + mindspore.ops.atleast_1d + mindspore.ops.atleast_2d + mindspore.ops.atleast_3d mindspore.ops.bessel_i0 mindspore.ops.bessel_i0e mindspore.ops.bessel_i1 @@ -209,11 +212,13 @@ MindSpore中 `mindspore.ops` 接口与上一版本相比，新增、删除和支 mindspore.ops.ceil mindspore.ops.clamp mindspore.ops.clip + mindspore.ops.combinations mindspore.ops.copysign mindspore.ops.cos mindspore.ops.cosh mindspore.ops.cosine_similarity mindspore.ops.cov + mindspore.ops.diag_embed mindspore.ops.diff mindspore.ops.deg2rad mindspore.ops.digamma @@ -257,10 +262,13 @@ MindSpore中 `mindspore.ops` 接口与上一版本相比，新增、删除和支 mindspore.ops.mul mindspore.ops.multiply mindspore.ops.mvlgamma + mindspore.ops.nanquantile mindspore.ops.neg mindspore.ops.negative + mindspore.ops.polygamma mindspore.ops.positive mindspore.ops.pow + mindspore.ops.quantile mindspore.ops.rad2deg mindspore.ops.ravel mindspore.ops.real @@ -284,6 +292,8 @@ MindSpore中 `mindspore.ops` 接口与上一版本相比，新增、删除和支 mindspore.ops.tan mindspore.ops.tanhshrink mindspore.ops.trapz + mindspore.ops.tril_indices + mindspore.ops.triu_indices mindspore.ops.true_divide mindspore.ops.trunc mindspore.ops.truncate_div @@ -302,12 +312,15 @@ Reduction函数 mindspore.ops.all mindspore.ops.amax mindspore.ops.amin + mindspore.ops.aminmax mindspore.ops.any mindspore.ops.argmax mindspore.ops.argmin mindspore.ops.cummax mindspore.ops.cummin mindspore.ops.cumsum + mindspore.ops.fmax + mindspore.ops.fmin mindspore.ops.logsumexp mindspore.ops.max mindspore.ops.mean @@ -485,6 +498,7 @@ Array操作 mindspore.ops.diagonal mindspore.ops.dyn_shape mindspore.ops.dsplit + mindspore.ops.dstack mindspore.ops.einsum mindspore.ops.expand mindspore.ops.expand_dims @@ -530,6 +544,7 @@ Array操作 mindspore.ops.shuffle mindspore.ops.size mindspore.ops.slice + mindspore.ops.sort mindspore.ops.space_to_batch_nd mindspore.ops.sparse_segment_mean mindspore.ops.split @@ -562,6 +577,7 @@ Array操作 mindspore.ops.unstack mindspore.ops.view_as_real mindspore.ops.vsplit + mindspore.ops.vstack mindspore.ops.where mindspore.ops.cross mindspore.ops.cumprod diff --git a/docs/api/api_python/nn/mindspore.nn.PoissonNLLLoss.rst b/docs/api/api_python/nn/mindspore.nn.PoissonNLLLoss.rst index 9fc19666aef..a4327e45679 100644 --- a/docs/api/api_python/nn/mindspore.nn.PoissonNLLLoss.rst +++ b/docs/api/api_python/nn/mindspore.nn.PoissonNLLLoss.rst @@ -1,7 +1,7 @@ mindspore.nn.PoissonNLLLoss ============================ -.. py:class:: mindspore.nn.PoissonNLLLoss(log_input=True, full=False, eps=1e-8, reduction='mean') +.. py:class:: mindspore.nn.PoissonNLLLoss(log_input=True, full=False, eps=1e-08, reduction='mean') 计算泊松负对数似然损失。 @@ -25,7 +25,7 @@ mindspore.nn.PoissonNLLLoss 参数： - **log_input** (bool，可选) - 是否使用对数输入。默认值：True。 - **full** (bool，可选) - 是否在损失计算中包括斯特林近似项。默认值：False。 - - **eps** (float，可选) - 算对数时 `x` 的下界。默认值：1e-8。 + - **eps** (float，可选) - 算对数时 `x` 的下界。默认值：1e-08。 - **reduction** (str，可选) - 指定要应用于输出的缩减方式，取值为'none'、'mean'或'sum'。默认值：'mean'。 输入： diff --git a/docs/api/api_python/nn/mindspore.nn.Upsample.rst b/docs/api/api_python/nn/mindspore.nn.Upsample.rst new file mode 100644 index 00000000000..b421dae32b7 --- /dev/null +++ b/docs/api/api_python/nn/mindspore.nn.Upsample.rst @@ -0,0 +1,32 @@ +mindspore.nn.Upsample +===================== + +.. py:class:: mindspore.nn.Upsample(size=None, scale_factor=None, mode="nearest", align_corners=None) + + 根据指定的 `size` 或 `scale_factor` 对Tensor进行采样，过程使用上采样算法。 + + 必须指定 `size` 或 `scale_factor` 中的一个值，并且不能同时指定两者。 + + 参数： + - **size** (Union(int, tuple[int], list[int])，可选) - 采样尺寸。可以是含有一个、两个或三个元素的list或者tuple。如果包含三个元素，则分别表示 :math:`([new\_depth], [new\_height], new\_width)` 。 `size` 和 `scale_factor` 有且只有一个可以被设为None。目前该参数仅支持设为None。默认值：None。 + - **scale_factor** (Union(float, tuple[float], list[float])，可选) - 采样Tensor的缩放因子，值为正整数。 `size` 和 `scale_factor` 有且只有一个可以被设为None。目前该参数仅支持设为None。默认值：None。 + - **mode** (str，可选) - 指定的上采样算法。可选值为：'nearest'、'linear' (仅支持3D输入)、 'bilinear'、'bicubic' (仅支持4D输入)、'trilinear' (仅支持5D输入)。默认值：'nearest'。 + - **align_corners** (bool，可选) - 如果为True，使用 :math:`(new\_height - 1) / (height - 1)` 对输入进行缩放使输入数据和缩放后数据的角落对齐。如果为False，则使用 :math:`new\_height / height` 进行缩放。默认值：None，此时不指定 `align_corners` ，赋值为False。 + + 输入： + - **x** (Tensor) - 进行尺寸调整的Tensor。输入必须为3-D、4-D或5-D。其数据格式为： :math:`(batch, channels, depth(4-D或5-D才有此维度), height(5-D才有此维度), width)` 。数据类型为float16或float32。 + + 输出： + Tensor。维度为3-D、4-D或5-D，数据类型与 `x` 相同。 + + 异常： + - **TypeError** - `x` 不是Tensor。 + - **TypeError** - `mode` 不是'nearest'、'linear'、'bilinear'、'bicubic'或'trilinear'。 + - **TypeError** - `size` 不是list、tuple或None。 + - **TypeError** - `scale_factor` 不为int或None。 + - **TypeError** - `align_corners` 不是bool。 + - **TypeError** - `x` 的数据类型不是float16或float32。 + - **ValueError** - `size` 和 `scale_factor` 同时为None或同时不为None。 + - **ValueError** - `x` 或 `size` 与 `mode` 不匹配。 + - **ValueError** - `scale_factor` 小于零。 + - **ValueError** - `size` 的长度和 `mode` 不匹配。 diff --git a/docs/api/api_python/ops/mindspore.ops.Abs.rst b/docs/api/api_python/ops/mindspore.ops.Abs.rst index a8088efc294..9814b3081c9 100644 --- a/docs/api/api_python/ops/mindspore.ops.Abs.rst +++ b/docs/api/api_python/ops/mindspore.ops.Abs.rst @@ -5,4 +5,4 @@ 逐元素计算输入Tensor的绝对值。 - 更多详情请查看： :class:`mindspore.ops.abs` 。 \ No newline at end of file + 更多详情请查看： :class:`mindspore.ops.abs` 。 diff --git a/docs/api/api_python/ops/mindspore.ops.CountNonZero.rst b/docs/api/api_python/ops/mindspore.ops.CountNonZero.rst new file mode 100644 index 00000000000..c27af549f70 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.CountNonZero.rst @@ -0,0 +1,8 @@ +mindspore.ops.CountNonZero +========================== + +.. py:class:: mindspore.ops.CountNonZero + + 计算输入Tensor指定轴上的非零元素的数量。 + + 更多详情请查看： :func:`mindspore.ops.count_nonzero` 。 diff --git a/docs/api/api_python/ops/mindspore.ops.TrilIndices.rst b/docs/api/api_python/ops/mindspore.ops.TrilIndices.rst index 2ff374f8faf..f345ffd2824 100644 --- a/docs/api/api_python/ops/mindspore.ops.TrilIndices.rst +++ b/docs/api/api_python/ops/mindspore.ops.TrilIndices.rst @@ -3,23 +3,6 @@ mindspore.ops.TrilIndices .. py:class:: mindspore.ops.TrilIndices(row, col, offset=0, dtype=mstype.int32) - 返回一个包含 `row` * `col` 的矩阵的下三角形部分的索引的Tensor。Tensor的shape为 :math:`(2, tril\_size)` ，其中， `tril_size` 为下三角矩阵的元素总数。第一行包含所有索引的行坐标，第二行包含列坐标。索引按行排序，然后按列排序。 + 计算 `row` * `col` 行列矩阵的下三角元素的索引，并将它们作为一个 2xN 的Tensor返回。 - 矩阵的下三角形部分定义为对角线本身和对角线以下的元素。 - - .. note:: - 在CUDA上运行的时候， `row` * `col` 必须小于2^59以防止计算时溢出。 - - 参数： - - **row** (int) - 2-D 矩阵的行数。 - - **col** (int) - 2-D 矩阵的列数。 - - **offset** (int, 可选) - 对角线偏移量。默认值：0。 - - **dtype** (:class:`mindspore.dtype`, 可选) - 指定输出Tensor数据类型，支持的数据类型为 `mstype.int32` 和 `mstype.int64` ，默认值： `mstype.int32` 。 - - 输出： - - **y** (Tensor) - 矩阵的下三角形部分的索引。数据类型由 `dtype` 指定，shape为 :math:`(2, tril\_size)` ，其中， `tril_size` 为下三角矩阵的元素总数。 - - 异常： - - **TypeError** - 如果 `row` 、 `col` 或 `offset` 不是int。 - - **TypeError** - 如果 `dtype` 的类型不是int32或int64。 - - **ValueError** - 如果 `row` 或者 `col` 小于零。 + 更多参考详见 :func:`mindspore.ops.tril_indices` 。 diff --git a/docs/api/api_python/ops/mindspore.ops.TriuIndices.rst b/docs/api/api_python/ops/mindspore.ops.TriuIndices.rst index 5ddeea323ad..e2dd4eed7a8 100644 --- a/docs/api/api_python/ops/mindspore.ops.TriuIndices.rst +++ b/docs/api/api_python/ops/mindspore.ops.TriuIndices.rst @@ -3,23 +3,6 @@ mindspore.ops.TriuIndices .. py:class:: mindspore.ops.TriuIndices(row, col, offset=0, dtype=mstype.int32) - 返回一个包含 `row` * `col` 的矩阵的上三角形部分的索引的Tensor。Tensor的shape为 :math:`(2, tril\_size)` ，其中， `tril_size` 为上三角矩阵的元素总数。第一行包含所有索引的行坐标，第二行包含列坐标。索引按行排序，然后按列排序。 + 计算 `row` * `col` 行列矩阵的上三角元素的索引，并将它们作为一个 2xN 的Tensor返回。 - 矩阵的下三角形部分定义为对角线本身和对角线以上的元素。 - - .. note:: - 在CUDA上运行的时候， `row` * `col` 必须小于2^59以防止计算时溢出。 - - 参数： - - **row** (int) - 2-D 矩阵的行数。 - - **col** (int) - 2-D 矩阵的列数。 - - **offset** (int，可选) - 对角线偏移量。默认值：0。 - - **dtype** (:class:`mindspore.dtype`，可选) - 指定输出Tensor数据类型，支持的数据类型为 `mstype.int32` 和 `mstype.int64` ，默认值： `mstype.int32` 。 - - 输出： - - **y** (Tensor) - 矩阵的下三角形部分的索引。数据类型由 `dtype` 指定，shape为 :math:`(2, tril\_size)` ，其中， `tril_size` 为上三角矩阵的元素总数。 - - 异常： - - **TypeError** - 如果 `row` 、 `col` 或 `offset` 不是int。 - - **TypeError** - 如果 `dtype` 的类型不是int32或int64。 - - **ValueError** - 如果 `row` 或者 `col` 小于零。 + 更多参考详见 :func:`mindspore.ops.triu_indices` 。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_aminmax.rst b/docs/api/api_python/ops/mindspore.ops.func_aminmax.rst new file mode 100644 index 00000000000..6f39a4656d3 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_aminmax.rst @@ -0,0 +1,24 @@ +mindspore.ops.aminmax +====================== + +.. py:function:: mindspore.ops.aminmax(x, *, axis=0, keep_dims=False) + + 返回输入Tensor在指定轴上的最小值和最大值。 + + 参数： + - **x** (Tensor) - 输入Tensor，可以是任意维度。设输入Tensor的shape为 :math:`(x_1, x_2, ..., x_N)` 。 + + 关键字参数： + - **axis** (int，可选) - 要进行规约计算的维度。 `axis` 必须在[-rank, rank)范围内，其中 “rank” 是 `x` 的维度。默认值：0。 + - **keep_dims** (bool，可选) - 是否保留维度。如果为True，则输出shape与输入shape一致，否则移除规约计算的维度 `axis` 。默认值：False。 + + 返回： + tuple (Tensor)，包含输入Tensor在指定轴上的最小值和最大值。 + + - `keepdims` 为True，输出shape为： :math:`(x_1, x_2, ..., x_{axis-1}, 1, x_{axis+1}, ..., x_N)` 。 + - `keepdims` 为False，输出shape为： :math:`(x_1, x_2, ..., x_{axis-1}, x_{axis+1}, ..., x_N)` 。 + + 异常： + - **TypeError** - `keepdims` 不是bool类型。 + - **TypeError** - `axis` 不是int类型。 + - **ValueError** - `axis` 不在[-rank, rank)范围内。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_atan2.rst b/docs/api/api_python/ops/mindspore.ops.func_atan2.rst index 74ae3c467f7..2d18ad162db 100644 --- a/docs/api/api_python/ops/mindspore.ops.func_atan2.rst +++ b/docs/api/api_python/ops/mindspore.ops.func_atan2.rst @@ -6,7 +6,11 @@ mindspore.ops.atan2 逐元素计算input/other的反正切值。 返回 :math:`\theta\ \in\ [-\pi, \pi]` ，使得 :math:`input = r*\sin(\theta), other = r*\cos(\theta)` ，其中 :math:`r = \sqrt{input^2 + other^2}` 。 - 输入 `input` 和 `other` 会通过隐式数据类型转换使数据类型保持一致。如果数据类型不同，低精度的数据类型会被转换到高精度的数据类型。 + + .. note:: + - 参数 `input` 和 `other` 遵循 `隐式类型转换规则 `_ ，使数据类型保持一致。如果两参数数据类型不一致，则低精度类型会被转换成较高精度类型。 + - 输入必须是两个Tensor，或一个Tensor和一个Scalar。 + - 当输入是一个Tensor和一个Scalar时，Scalar只能是一个常数。 参数： - **input** (Tensor, Number.number) - 输入Tensor或常数，shape: :math:`(N,*)` ，其中 :math:`*` 表示任何数量的附加维度。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_atleast_1d.rst b/docs/api/api_python/ops/mindspore.ops.func_atleast_1d.rst new file mode 100644 index 00000000000..73c9d5d0a8c --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_atleast_1d.rst @@ -0,0 +1,17 @@ +mindspore.ops.atleast_1d +========================= + +.. py:function:: mindspore.ops.atleast_1d(inputs) + + 调整 `inputs` 中的Tensor维度，使输入中每个Tensor维度不低于1。 + + Scalar输入被转换为一维Tensor，而高维输入则被保留。 + + 参数： + - **inputs** (Union[Tensor, list[Tensor]]) - 一个或多个输入Tensor。 + + 返回： + Tensor或Tensor列表。如果返回列表，则列表中的每一个元素 `a` 满足： `a`.ndim >= 1。 + + 异常： + - **TypeError** - `input` 不是一个Tensor或Tensor列表。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_atleast_2d.rst b/docs/api/api_python/ops/mindspore.ops.func_atleast_2d.rst new file mode 100644 index 00000000000..1307a824ad4 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_atleast_2d.rst @@ -0,0 +1,17 @@ +mindspore.ops.atleast_2d +========================= + +.. py:function:: mindspore.ops.atleast_2d(inputs) + + 调整 `inputs` 中的Tensor维度，使输入中每个Tensor维度不低于2。 + + Scalar或一维Tensor被转换为二维Tensor，而高维输入则被保留。 + + 参数： + - **inputs** (Union[Tensor, list[Tensor]]) - 一个或多个输入Tensor。 + + 返回： + Tensor或Tensor列表。如果返回列表，则列表中的每一个元素 `a` 满足： `a`.ndim >= 2。 + + 异常： + - **TypeError** - `input` 不是一个Tensor或Tensor列表。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_atleast_3d.rst b/docs/api/api_python/ops/mindspore.ops.func_atleast_3d.rst new file mode 100644 index 00000000000..5605724f1b3 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_atleast_3d.rst @@ -0,0 +1,18 @@ +mindspore.ops.atleast_3d +========================= + +.. py:function:: mindspore.ops.atleast_3d(inputs) + + 调整 `inputs` 中的Tensor维度，使输入中每个Tensor维度不低于3。 + + Scalar、一维或二维Tensor被转换为三维Tensor，而高维输入则被保留。 + + 参数： + - **inputs** (Union[Tensor, list[Tensor]]) - 一个或多个输入Tensor。例如，shape为 :math:`(N,)` 的Tensor变成shape为 :math:`(1, N, 1)` 的Tensor，shape为 :math:`(M, N)` 的Tensor变成shape为 :math:`(M, N, 1)` 的Tensor。 + + 返回： + Tensor或Tensor列表。如果返回列表，则列表中的每一个元素 `a` 满足： `a`.ndim >= 3。 + 例如，一个shape为 :math:`(N,)` 的Tensor，操作后shape变成 :math:`(1, N, 1)` ，shape为 :math:`(M, N)` 的2-D Tensor shape变成 :math:`(M, N, 1)` 。 + + 异常： + - **TypeError** - `input` 不是一个Tensor或Tensor列表。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_combinations.rst b/docs/api/api_python/ops/mindspore.ops.func_combinations.rst new file mode 100644 index 00000000000..6475bdb7791 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_combinations.rst @@ -0,0 +1,22 @@ +mindspore.ops.combinations +========================== + +.. py:function:: mindspore.ops.combinations(x, r=2, with_replacement=False) + + 返回输入Tensor中元素的所有长度为 `r` 的子序列。 + + 当 `with_replacement` 设为 `False` ，功能与Python里的 `itertools.combinations` 类似，若设为 `True` ，功能与 `itertools.combinations_with_replacement` 一致。 + + 参数： + - **x** (Tensor) - 一维Tensor。 + - **r** (int，可选) - 进行组合的元素个数。默认值：2。 + - **with_replacement** (bool，可选) - 是否允许组合存在重复值。默认值：False。 + + 返回： + Tensor，包含输入Tensor元素的左右组合值。 + + 异常： + - **TypeError** - 如果 `x` 不是Tensor。 + - **TypeError** - 如果 `r` 不是int类型。 + - **TypeError** - 如果 `with_replacement` 不是bool类型。 + - **ValueError** - 如果 `x` 不是一维。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_count_nonzero.rst b/docs/api/api_python/ops/mindspore.ops.func_count_nonzero.rst index daa6da09661..dd1f3160a43 100644 --- a/docs/api/api_python/ops/mindspore.ops.func_count_nonzero.rst +++ b/docs/api/api_python/ops/mindspore.ops.func_count_nonzero.rst @@ -3,18 +3,19 @@ mindspore.ops.count_nonzero .. py:function:: mindspore.ops.count_nonzero(x, axis=(), keep_dims=False, dtype=mstype.int32) - 计算输入Tensor指定轴上的非零元素的数量。 + 计算输入Tensor指定轴上的非零元素的数量。如果没有指定维度，则计算Tensor中所有非零元素的数量。 + + .. note:: + `dims` 的值范围是[-x_dims，x_dims）。其中， `x_dims` 是输入 `x` 的维度。 参数： - - **x** (Tensor) - 输入数据用于统计非零元素。 :math:`(N,*)` ，其中 :math:`*` 表示任意数量的附加维度。 - - **axis** (Union[int, tuple(int), list(int)]) - 指定计算的维度。只允许为常量。默认值：()，在所有维度进行计算。 - - **keep_dims** (bool) - 如果为True，则保留计算的维度，且长度为1。如果为False，则不要保留这些维度。默认值：False。 - - **dtype** (Union[Number, mindspore.bool\_]) - 输出Tensor的数据类型。只允许为常量。默认值：mindspore.int32。 + - **x** (Tensor) - 要计算的输入，可以是任意维度的Tensor。将输入张量的shape设为 :math:`(x_1, x_2, ..., x_N)` 。 + - **dims** (Union[int, list(int), tuple(int)]，可选) - 要沿其计算非零值数量的维度。默认值：None。 返回： - Tensor，非零元素的数量。数据类型由 `dtype` 所指定。 + 一个N维Tensor，表示输入Tensor在 `dims` 上的非零元素数量。 `dims` 指定的维度将被规约掉。例如，如果 `x` 的大小为 :math:`(2, 3, 4)` ， `dims` 为 :math:`[0, 1]` ，则y_shape将为 :math:`(4,)` 。 异常： - - **TypeError** - `axis` 不是int、tuple或者list。 - - **ValueError** - `axis` 不在[-x.ndim, x.ndim)范围内。 - + - **TypeError** - 如果 `x` 的数据类型不受支持。 + - **TypeError** - 如果 `dims` 的数据类型不是int。 + - **ValueError** - 如果 `dims` 中的任何值不在 :math:`[-x_dims，x_dims)` 范围内。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_diag_embed.rst b/docs/api/api_python/ops/mindspore.ops.func_diag_embed.rst new file mode 100644 index 00000000000..da0b5ec4cb0 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_diag_embed.rst @@ -0,0 +1,35 @@ +mindspore.ops.diag_embed +========================= + +.. py:function:: mindspore.ops.diag_embed(x, offset=0, dim1=-2, dim2=-1) + + 生成一个Tensor，其对角线值由 `x` 中的值填充，其余位置置0。如果 `x` 的shape为 :math:`[x_{0}, x_{1}, ..., x_{n-1}, x_{n}]` ，则输出 + shape为将 :math:`x_{n}+|offset|` 插入 :math:`[x_{0}, x_{1}, ..., x_{n-1}]` 的 `dim1` 和 `dim2` 维后得到的向量。 + + 参数： + - **x** (Tensor) - 对角线填充值。 + - **offset** (int，可选) - 对角线偏离值。 :math:`offset=0` 为主对角线。 + + - 如果 :math:`offset>0` ，填充主对角线上方第 `offset` 条对角线。 + - 如果 :math:`offset<0` ，填充主对角线下方第 `offset` 条对角线。 + + 默认值：0。 + + - **dim1** (int，可选) - 填充对角线的第一个维度。默认值：-2。 + - **dim2** (int，可选) - 填充对角线的第二个维度。默认值：-1。 + + 返回： + Tensor，数据类型与 `x` 一致，但输出shape维度比 `x` 高一维。 + + - 如果 `keepdims` 为True，则输出shape为： :math:`(x_1, x_2, ..., x_{axis-1}, 1, x_{axis+1}, ..., x_N)` 。 + - 否则输出shape为： :math:`(x_1, x_2, ..., x_{axis-1}, x_{axis+1}, ..., x_N)` 。 + + 异常： + - **TypeError** - `x` 不是Tensor。 + - **TypeError** - `x` 的数据类型不被支持。 + - **TypeError** - `offset` 不是int类型。 + - **TypeError** - `dim1` 或 `dim2` 不是int类型。 + - **ValueError** - `x` 的维度不是1D-6D。 + - **ValueError** - `dim1` 不在[-len(x.shape), len(x.shape))范围内。 + - **ValueError** - `dim2` 不在[-len(x.shape), len(x.shape))范围内。 + - **ValueError** - `dim1` 和 `dim2` 相等。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_dstack.rst b/docs/api/api_python/ops/mindspore.ops.func_dstack.rst new file mode 100644 index 00000000000..facb4b16e02 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_dstack.rst @@ -0,0 +1,20 @@ +mindspore.ops.dstack +==================== + +.. py:function:: mindspore.ops.dstack(inputs) + + 将多个Tensor沿着深度方向进行堆叠。 + + 相当于将输入沿着第三个轴进行拼接。 + 1-D Tensor :math:`(N,)` 重新排列为 :math:`(1,N,1)` ，2-D Tensor :math:`(M,N)` 重新排列为 :math:`(M,N,1)` 。 + + 参数： + - **inputs** (Union(List[Tensor], Tuple[Tensor])) - 一个Tensor序列。除了第三个轴外，所有的 + Tensor必须有相同的shape。如果是1-D或2-D的Tensor，则它们的shape必须相同。 + + 返回： + 堆叠后的Tensor，其维度至少为3。输出shape与 `numpy.dstack()` 类似。 + + 异常： + - **TypeError** - 如果 `inputs` 不是list或tuple。 + - **ValueError** - 如果 `inputs` 为空。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_fmax.rst b/docs/api/api_python/ops/mindspore.ops.func_fmax.rst new file mode 100644 index 00000000000..a650fe9f185 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_fmax.rst @@ -0,0 +1,26 @@ +mindspore.ops.fmax +================== + +.. py:function:: mindspore.ops.fmax(x1, x2) + + 逐元素计算输入Tensor的最大值。 + + .. math:: + output_i = max(x1_i, x2_i) + + .. note:: + - 输入 `x1` 和 `x2` 遵循隐式转换法则使数据类型一致。 + - 输入 `x1` 和 `x2` 的shape必须能相互广播。 + - 如果其中一个比较值是NaN，则返回另一个比较值。 + + 参数： + - **x1** (Tensor) - 第一个输入Tensor，支持的数据类型有： float16、float32、 float64、 int32、 int64。 + - **x2** (Tensor) - 第二个输入Tensor，支持的数据类型有： float16、 float32、 float64、 int32、 int64。 + + 返回： + Tensor。其shape与两个输入广播之后的shape相同，数据类型为隐式转换后精度较高的数据类型。 + + 异常： + - **TypeError** - `x1` 或 `x2` 不是Tensor。 + - **TypeError** - `x1` 或 `x2` 的数据类型不是以下数据类型之一：float16、 float32、 float64、 int32、 int64。 + - **ValueError** - `x1` 和 `x2` 的shape不能广播。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_fmin.rst b/docs/api/api_python/ops/mindspore.ops.func_fmin.rst new file mode 100644 index 00000000000..537cda506a3 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_fmin.rst @@ -0,0 +1,26 @@ +mindspore.ops.fmin +================== + +.. py:function:: mindspore.ops.fmin(x1, x2) + + 逐元素计算输入Tensor的最小值。 + + .. math:: + output_i = min(x1_i, x2_i) + + .. note:: + - 输入 `x1` 和 `x2` 遵循隐式转换法则使数据类型一致。 + - 输入 `x1` 和 `x2` 的shape必须能相互广播。 + - 如果其中一个比较值是NaN，则返回另一个比较值。 + + 参数： + - **x1** (Tensor) - 第一个输入Tensor，支持的数据类型有： float16、float32、 float64、 int32、 int64。 + - **x2** (Tensor) - 第二个输入Tensor，支持的数据类型有： float16、 float32、 float64、 int32、 int64。 + + 返回： + Tensor。其shape与两个输入广播之后的shape相同，数据类型为隐式转换后精度较高的数据类型。 + + 异常： + - **TypeError** - `x1` 或 `x2` 不是Tensor。 + - **TypeError** - `x1` 或 `x2` 的数据类型不是以下数据类型之一：float16、 float32、 float64、 int32、 int64。 + - **ValueError** - `x1` 和 `x2` 的shape不能广播。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_nanquantile.rst b/docs/api/api_python/ops/mindspore.ops.func_nanquantile.rst new file mode 100644 index 00000000000..7624ca0727e --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_nanquantile.rst @@ -0,0 +1,34 @@ +mindspore.ops.nanquantile +========================= + +.. py:function:: mindspore.ops.nanquantile(x, q, axis=None, keepdims=False) + + 此接口为mindspore.ops.quantile()的变体，计算的时候会忽略NaN值。如果进行规约计算维度的所有值都是NaN，则返回的分位数为NaN。 + + 详情请参考 :func:`mindspore.ops.quantile` 。 + + 参数： + - **x** (Tensor) - 输入Tensor。其shape为 :math:`(x_1, x_2, ..., x_R)` 。支持的数据类型为：float32、float64。 + - **q** (Union[float, Tensor]) - 标量或1D Tensor。其值范围在[0, 1]，支持的数据类型为：float32、float64。 + - **axis** (int，可选) - 要减少的维度。默认情况下 `axis` 为None，导致输入Tensor在计算前被展平。默认值：None。 + - **keepdims** (bool，可选) - 输出Tensor是否保留维度。默认值：False。 + + 返回： + 输入Tensor，数据类型与 `input` 一致。 + + 假设 `x` 的shape为 :math:`(m, x_0, x_1, ..., x_i, ..., X_R)` ， `axis` = :math:`i` ，m为 `q` 中的总元素个数。 + + - 如果 `q` 为标量且 `keepdims` 为True，则输出shape为 :math:`(x_0, x_1, ..., 1, ..., X_R)` 。 + - 如果 `q` 为标量且 `keepdims` 为False，则输出shape为 :math:`(x_0, x_1, ..., X_R)` 。 + - 如果 `q` 为1D Tensor且 `keepdims` 为True，则输出shape为 :math:`(m, x_0, x_1, ..., 1, ..., X_R)` 。 + - 如果 `q` 为1D Tensor且 `keepdims` 为False，则输出shape为 :math:`(m, x_0, x_1, ..., X_R)` 。 + + 异常： + - **TypeError** - `x` 不是Tensor。 + - **TypeError** - `q` 不是Tensor或float类型。 + - **TypeError** - `x` 的数据类型float32或float64。 + - **TypeError** - `q` 的数据类型float32或float64。 + - **TypeError** - `x` 和 `q` 的数据类型不一致。 + - **ValueError** - `q` 的值不在[0, 1]范围内。 + - **ValueError** - `axis` 的值不在有效范围内。 + diff --git a/docs/api/api_python/ops/mindspore.ops.func_polygamma.rst b/docs/api/api_python/ops/mindspore.ops.func_polygamma.rst new file mode 100644 index 00000000000..652fe5c1d51 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_polygamma.rst @@ -0,0 +1,24 @@ +mindspore.ops.polygamma +======================= + +.. py:function:: mindspore.ops.polygamma(a, x) + + 计算关于 `x` 的多伽马函数的 :math:`a` 阶导数。 + + .. math:: + \psi^{(a)}(x) = \frac{d^{(a)}}{dx^{(a)}} \psi(x) + + 其中\psi(x)为digamma函数。 + + 参数： + - **a** (tuple) - 多伽马函数求导的阶数，支持的数据类型为int32和int64， `a` 的shape为 :math:`()` 。 + - **x** (Tensor) - 用于计算多伽马函数的Tensor。 + + 返回： + Tensor。数据类型与 `x` 一致。 + + 异常： + - **TypeError** - `x` 不是Tensor。 + - **TypeError** - `x` 的数据类型不是float16、float32或float64。 + - **TypeError** - `a` 的数据类型不是int32或int64。 + - **TypeError** - `a` 的shape不是 :math:`()` 。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_quantile.rst b/docs/api/api_python/ops/mindspore.ops.func_quantile.rst new file mode 100644 index 00000000000..4dad13dabf7 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_quantile.rst @@ -0,0 +1,31 @@ +mindspore.ops.quantile +====================== + +.. py:function:: mindspore.ops.quantile(x, q, axis=None, keepdims=False) + + 计算 `x` 中所有元素的第 `q` 分位数，如果第 `q` 分位数位于两个数据点之间，则返使用线性插值计算结果。 + + 参数： + - **x** (Tensor) - 输入Tensor。其shape为 :math:`(x_1, x_2, ..., x_R)` 。支持的数据类型为：float32、float64。 + - **q** (Union[float, Tensor]) - 标量或1D Tensor。其值范围在[0, 1]，支持的数据类型为：float32、float64。 + - **axis** (int，可选) - 要减少的维度。默认情况下 `axis` 为None，导致输入Tensor在计算前被展平。默认值：None。 + - **keepdims** (bool，可选) - 输出Tensor是否保留维度。默认值：False。 + + 返回： + 输入Tensor，数据类型与 `input` 一致。 + + 假设 `x` 的shape为 :math:`(m, x_0, x_1, ..., x_i, ..., X_R)` ， `axis` = :math:`i` ，m为 `q` 中的总元素个数。 + + - 如果 `q` 为标量且 `keepdims` 为True，则输出shape为 :math:`(x_0, x_1, ..., 1, ..., X_R)` 。 + - 如果 `q` 为标量且 `keepdims` 为False，则输出shape为 :math:`(x_0, x_1, ..., X_R)` 。 + - 如果 `q` 为1D Tensor且 `keepdims` 为True，则输出shape为 :math:`(m, x_0, x_1, ..., 1, ..., X_R)` 。 + - 如果 `q` 为1D Tensor且 `keepdims` 为False，则输出shape为 :math:`(m, x_0, x_1, ..., X_R)` 。 + + 异常： + - **TypeError** - `x` 不是Tensor。 + - **TypeError** - `q` 不是Tensor或float类型。 + - **TypeError** - `x` 的数据类型float32或float64。 + - **TypeError** - `q` 的数据类型float32或float64。 + - **TypeError** - `x` 和 `q` 的数据类型不一致。 + - **ValueError** - `q` 的值不在[0, 1]范围内。 + - **ValueError** - `axis` 的值不在有效范围内。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_sort.rst b/docs/api/api_python/ops/mindspore.ops.func_sort.rst new file mode 100644 index 00000000000..59da1629f05 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_sort.rst @@ -0,0 +1,24 @@ +mindspore.ops.sort +================== + +.. py:function:: mindspore.ops.sort(input_x, axis=-1, descending=False) + + 按指定顺序对输入Tensor的指定维上的元素进行排序。 + + 参数： + - **input_x** (Tensor) - 进行排序的Tensor，shape为 :math:`(N,*)` ，其中 :math:`*` 表示任意数量的的额外维度。 + - **axis** (int，可选) - 进行排序的维度。默认值：-1。 + - **descending** (bool，可选) - 按降序还是升序。如果为True，则元素按降序排列，否则按升序排列。默认值：False。 + + .. warning:: + 目前能良好支持的数据类型有：Float16、UInt8、Int8、Int16、Int32、Int64。如果使用Float32，可能产生精度误差。 + + 返回： + - **y1** (Tensor) - 排序后的值，其shape和数据类型与输入一致。 + - **y2** (Tensor) - 返回值在原输入Tensor里对应的索引，数据类型为int32。 + + 异常： + - **TypeError** - `axis` 不是int类型。 + - **TypeError** - `descending` 不是bool类型。 + - **TypeError** - `input_x` 不是Float16、Float32、UInt8、Int8、Int16、Int32或Int64。 + - **ValueError** - `axis` 不在[-len(input_x.shape), len(input_x.shape))范围内。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_tril_indices.rst b/docs/api/api_python/ops/mindspore.ops.func_tril_indices.rst new file mode 100644 index 00000000000..8ec404cde1a --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_tril_indices.rst @@ -0,0 +1,26 @@ +mindspore.ops.tril_indices +========================== + +.. py:function:: mindspore.ops.tril_indices(row, col, offset=0, dtype=mstype.int64) + + 计算 `row` * `col` 行列矩阵的下三角元素的索引，并将它们作为一个 2xN 的Tensor返回。张量的第一行包含行坐标，第二行包含列坐标。坐标按行排序，然后按列排序。 + + 矩阵的下三角部分包括对角线及其以下的所有元素。 + + .. note:: + 在CUDA上运行的时候， `row` * `col` 必须小于2^59以防止计算时溢出。 + + 参数： + - **row** (int) - 2-D 矩阵的行数。 + - **col** (int) - 2-D 矩阵的列数。 + - **offset** (int, 可选) - 对角线偏移量。默认值：0。 + - **dtype** (:class:`mindspore.dtype` ，可选) - 指定输出Tensor数据类型，支持的数据类型为 `mstype.int32` 和 `mstype.int64` ，默认值： `mstype.int64` 。 + + 返回： + - **y** (Tensor) - 矩阵的下三角形部分的索引。数据类型由 `dtype` 指定，shape为 :math:`(2, tril\_size)` ，其中， `tril_size` 为下三角矩阵的元素总数。 + + 异常： + - **TypeError** - 如果 `row` 、 `col` 或 `offset` 不是int。 + - **TypeError** - 如果 `dtype` 的类型不是int32或int64。 + - **ValueError** - 如果 `row` 或者 `col` 小于零。 + diff --git a/docs/api/api_python/ops/mindspore.ops.func_triu_indices.rst b/docs/api/api_python/ops/mindspore.ops.func_triu_indices.rst new file mode 100644 index 00000000000..f9446063c8c --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_triu_indices.rst @@ -0,0 +1,25 @@ +mindspore.ops.triu_indices +========================== + +.. py:function:: mindspore.ops.triu_indices(row, col, offset=0, dtype=mstype.int64) + + 计算 `row` * `col` 行列矩阵的上三角元素的索引，并将它们作为一个 2xN 的Tensor返回。张量的第一行包含行坐标，第二行包含列坐标。坐标按行排序，然后按列排序。 + + 矩阵的上三角部分包括对角线及其以上的所有元素。 + + .. note:: + 在CUDA上运行的时候， `row` * `col` 必须小于2^59以防止计算时溢出。 + + 参数： + - **row** (int) - 2-D 矩阵的行数。 + - **col** (int) - 2-D 矩阵的列数。 + - **offset** (int，可选) - 对角线偏移量。默认值：0。 + - **dtype** (:class:`mindspore.dtype` ，可选) - 指定输出Tensor数据类型，支持的数据类型为 `mstype.int32` 和 `mstype.int64` ，默认值： `mstype.int64` 。 + + 返回： + - **y** (Tensor) - 矩阵的下三角形部分的索引。数据类型由 `dtype` 指定，shape为 :math:`(2, tril\_size)` ，其中， `tril_size` 为上三角矩阵的元素总数。 + + 异常： + - **TypeError** - 如果 `row` 、 `col` 或 `offset` 不是int。 + - **TypeError** - 如果 `dtype` 的类型不是int32或int64。 + - **ValueError** - 如果 `row` 或者 `col` 小于零。 diff --git a/docs/api/api_python/ops/mindspore.ops.func_vstack.rst b/docs/api/api_python/ops/mindspore.ops.func_vstack.rst new file mode 100644 index 00000000000..a8b4f01f4a4 --- /dev/null +++ b/docs/api/api_python/ops/mindspore.ops.func_vstack.rst @@ -0,0 +1,20 @@ +mindspore.ops.vstack +==================== + +.. py:function:: mindspore.ops.vstack(inputs) + + 将多个Tensor沿着竖直方向进行堆叠。 + + 相当于将输入沿着第一个轴进行拼接。 + 1-D Tensor :math:`(N,)` 重新排列为 :math:`(1, N)` ，然后沿着第一个轴进行拼接。 + + 参数： + - **inputs** (Union(List[tensor], Tuple[tensor])) - 一个1-D或2-D Tensor序列。除了第一个轴外，所有的 + Tensor必须有相同的shape。如果是1-DTensor，则它们的shape必须相同。 + + 返回： + 堆叠后的Tensor，其维度至少为3。输出shape与 `numpy.vstack()` 类似。 + + 异常： + - **TypeError** - 如果 `inputs` 不是list或tuple。 + - **ValueError** - 如果 `inputs` 为空。 diff --git a/docs/api/api_python_en/mindspore.nn.rst b/docs/api/api_python_en/mindspore.nn.rst index e7cde17ca53..6f6fe63dd08 100644 --- a/docs/api/api_python_en/mindspore.nn.rst +++ b/docs/api/api_python_en/mindspore.nn.rst @@ -365,6 +365,7 @@ Image Processing Layer mindspore.nn.PixelShuffle mindspore.nn.PixelUnshuffle mindspore.nn.ResizeBilinear + mindspore.nn.Upsample Tools ----- diff --git a/docs/api/api_python_en/mindspore.ops.primitive.rst b/docs/api/api_python_en/mindspore.ops.primitive.rst index dd11566d2c8..4522d68d12e 100644 --- a/docs/api/api_python_en/mindspore.ops.primitive.rst +++ b/docs/api/api_python_en/mindspore.ops.primitive.rst @@ -480,6 +480,7 @@ Array Operation mindspore.ops.Col2Im mindspore.ops.Concat mindspore.ops.ConjugateTranspose + mindspore.ops.CountNonZero mindspore.ops.Cummax mindspore.ops.Cummin mindspore.ops.CumProd diff --git a/docs/api/api_python_en/mindspore.ops.rst b/docs/api/api_python_en/mindspore.ops.rst index 7ab6dbd1ab6..fe2a70e7a4a 100644 --- a/docs/api/api_python_en/mindspore.ops.rst +++ b/docs/api/api_python_en/mindspore.ops.rst @@ -189,6 +189,9 @@ Element-wise Operations mindspore.ops.atan mindspore.ops.atan2 mindspore.ops.atanh + mindspore.ops.atleast_1d + mindspore.ops.atleast_2d + mindspore.ops.atleast_3d mindspore.ops.bessel_i0 mindspore.ops.bessel_i0e mindspore.ops.bessel_i1 @@ -209,11 +212,13 @@ Element-wise Operations mindspore.ops.ceil mindspore.ops.clamp mindspore.ops.clip + mindspore.ops.combinations mindspore.ops.copysign mindspore.ops.cos mindspore.ops.cosh mindspore.ops.cosine_similarity mindspore.ops.cov + mindspore.ops.diag_embed mindspore.ops.diff mindspore.ops.deg2rad mindspore.ops.digamma @@ -257,10 +262,13 @@ Element-wise Operations mindspore.ops.mul mindspore.ops.multiply mindspore.ops.mvlgamma + mindspore.ops.nanquantile mindspore.ops.neg mindspore.ops.negative + mindspore.ops.polygamma mindspore.ops.positive mindspore.ops.pow + mindspore.ops.quantile mindspore.ops.rad2deg mindspore.ops.ravel mindspore.ops.real @@ -284,6 +292,8 @@ Element-wise Operations mindspore.ops.tan mindspore.ops.tanhshrink mindspore.ops.trapz + mindspore.ops.tril_indices + mindspore.ops.triu_indices mindspore.ops.true_divide mindspore.ops.trunc mindspore.ops.truncate_div @@ -302,12 +312,15 @@ Reduction Functions mindspore.ops.all mindspore.ops.amax mindspore.ops.amin + mindspore.ops.aminmax mindspore.ops.any mindspore.ops.argmax mindspore.ops.argmin mindspore.ops.cummax mindspore.ops.cummin mindspore.ops.cumsum + mindspore.ops.fmax + mindspore.ops.fmin mindspore.ops.logsumexp mindspore.ops.max mindspore.ops.mean @@ -485,6 +498,7 @@ Array Operation mindspore.ops.diagonal mindspore.ops.dyn_shape mindspore.ops.dsplit + mindspore.ops.dstack mindspore.ops.einsum mindspore.ops.expand mindspore.ops.expand_dims @@ -530,6 +544,7 @@ Array Operation mindspore.ops.shuffle mindspore.ops.size mindspore.ops.slice + mindspore.ops.sort mindspore.ops.space_to_batch_nd mindspore.ops.sparse_segment_mean mindspore.ops.split @@ -562,6 +577,7 @@ Array Operation mindspore.ops.unstack mindspore.ops.view_as_real mindspore.ops.vsplit + mindspore.ops.vstack mindspore.ops.where mindspore.ops.cross mindspore.ops.cumprod diff --git a/mindspore/python/mindspore/nn/layer/basic.py b/mindspore/python/mindspore/nn/layer/basic.py index 3d8b2cbee0d..a2f6c6b2672 100644 --- a/mindspore/python/mindspore/nn/layer/basic.py +++ b/mindspore/python/mindspore/nn/layer/basic.py @@ -359,28 +359,34 @@ class Dropout3d(Cell): class Upsample(Cell): r""" - Samples the input tensor to the given size or scale_factor by using one of the upsampling algorithms. + Samples the input tensor to the given `size` or `scale_factor` by using one of the upsampling algorithms. + + Either `size` or `scale_factor` must be spetified, but they cannot be specified at the same time. Args: - size (Union(int, tuple[int], list[int])): A tuple or list of 1, 2, or 3 int elements - `([new\_depth], [new\_height], new\_width)`, the new size of the tensor. - One and only one of size and scale_factor can be set to None. Default: None. - scale_factor (Union(float, tuple[float], list[float])): The scale factor of new size of the tensor. + size (Union(int, tuple[int], list[int]), optional): The sample size of the tensor. + A tuple or list of 1, 2, or 3 int elements + :math:`([new\_depth], [new\_height], new\_width)`. + One and only one of `size` and `scale_factor` can be set to None. Default: None. + scale_factor (Union(float, tuple[float], list[float]), optional): The scale factor of new size of the tensor. The value should be positive integer. - One and only one of size and scale_factor can be set to None. - Default: None. Currently only None is supported. - mode (str): One of 'nearest', 'linear' (3D only), 'bilinear', 'bicubic' (4D only) and 'trilinear' (5D only). + One and only one of `size` and `scale_factor` can be set to None. + Currently only None is supported. Default: None. + mode (str, optional): Specified upsampling algorithms. + Must be one of 'nearest', 'linear' (3D only), 'bilinear', 'bicubic' (4D only) and 'trilinear' (5D only). Default: 'nearest'. - align_corners (bool): If true, rescale input by `(new\_height - 1) / (height - 1)`, which exactly - aligns the corners of data and resized data. If false, rescale by `new\_height / height`. - Default: False. + align_corners (bool, optional): If true, rescale input by + :math:`(new\_height - 1) / (height - 1)`, which exactly + aligns the corners of data and resized data. If false, rescale by :math:`new\_height / height`. + Default: None, in which case `align_corners` is not specified, Fasle is assign to it. Inputs: - - **x** (Tensor) - Tensor to be resized. Input tensor must be a 3-D, 4-D, or 5-D tensor with shape - `(batch, channels, [optional depth], [optional height], width)`, with data type of float. + - **x** (Tensor) - Tensor to be resized. Input tensor must be a 3-D, 4-D, or 5-D. It has a data format: + :math:`(batch, channels, depth(4-D or 5-D only), height(5-D only), width)`, + with data type of float16 or float32. Outputs: - Tensor, resized, 3-D, 4-D, or 5-D, the data type is the same as `x`. + Tensor, 3-D, 4-D, or 5-D, the data type is the same as `x`. Raises: TypeError: If `x` is not Tensor. @@ -391,8 +397,8 @@ class Upsample(Cell): TypeError: If dtype of `x` is neither float16 nor float32. ValueError: If `size` and `scale_factor` are both None or not None. ValueError: If shape of `x` or `size` and `mode` are not match. - ValueError: If `scale_factor` is an int which is less than 0. - ValueError: If `size` is a list or tuple whose length is not match `mode`. + ValueError: If `scale_factor` is negative. + ValueError: If length of `size` does not match `mode`. Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` diff --git a/mindspore/python/mindspore/ops/function/__init__.py b/mindspore/python/mindspore/ops/function/__init__.py index 041d0c203a8..31380d9d6bb 100644 --- a/mindspore/python/mindspore/ops/function/__init__.py +++ b/mindspore/python/mindspore/ops/function/__init__.py @@ -155,7 +155,7 @@ from .array_func import ( searchsorted, aminmax, count_nonzero, - sort, + sort ) from .parameter_func import ( assign, diff --git a/mindspore/python/mindspore/ops/function/array_func.py b/mindspore/python/mindspore/ops/function/array_func.py index c54a5d299e6..c7cf07c40fb 100644 --- a/mindspore/python/mindspore/ops/function/array_func.py +++ b/mindspore/python/mindspore/ops/function/array_func.py @@ -3072,23 +3072,23 @@ def sort(input_x, axis=-1, descending=False): Args: input_x(Tensor): The input tensor to sort. The shape is :math:`(N,*)` where :math:`*` means, any number of additional dimensions. - axis (int): The dimension to sort along. Default: -1. - descending (bool): Controls the sort order. If descending is True then the elements - are sorted in descending order by value. Default: False. + axis (int, optional): The dimension to sort along. Default: -1. + descending (bool, optional): Controls the sort order. If `descending` is True, the elements + are sorted in descending order, or else sorted in ascending order. Default: False. .. warning:: - Currently, the data types of Float16, UInt8, Int8, Int16, Int32, Int64 are supported. + Currently, the data types of Float16, UInt8, Int8, Int16, Int32, Int64 are well supported. If use Float32, it may cause loss of accuracy. Returns: - y1(Tensor) - A tensor whose values are the sorted values, with the same shape and data type as input. - y2(Tensor) - The indices of the elements in the original input tensor. Data type is int32. + y1(Tensor): A tensor whose values are the sorted values, with the same shape and data type as input. + y2(Tensor): The indices of the elements in the original input tensor. Data type is int32. Raises: TypeError: If `axis` is not an int. TypeError: If `descending` is not a bool. - TypeError: If dtype of `x` is neither float16, float32, uint8, int8, int16, int32, int64. - ValueError: If `axis` is not in range of [-len(x.shape), len(x.shape)). + TypeError: If dtype of `input_x` is neither float16, float32, uint8, int8, int16, int32, int64. + ValueError: If `axis` is not in range of [-len(input_x.shape), len(input_x.shape)). Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` @@ -5543,27 +5543,24 @@ def min(x, axis=0, keep_dims=False): def aminmax(x, *, axis=0, keepdims=False): """ - Calculates the minimum value and maximum values. - - Calculates the minimum value and maximum values along with the given axis for the input tensor. - It returns the minimum values and maximum values. - - .. warning:: - - The value range of "axis" is [-rank, rank). "rank" is the dimension length of "x". + It returns the minimum and maximum value along the given axis of input tensor. Args: x (Tensor): The input tensor, can be any dimension. Set the shape of input tensor as :math:`(x_1, x_2, ..., x_N)` . - axis (int): The dimension to reduce. Default: 0. - keepdims (bool): Whether to reduce dimension, if true the output will keep the same dimension as the input, - the output will reduce dimension if false. Default: False. + + Keyword Args: + axis (int, optional): The dimension to reduce. The value range of `axis` is [-rank, rank), + where "rank" is the dimension of `x`. Default: 0. + keepdims (bool, optional): Whether to maintain dimension. When set to True, the output will keep the same + dimension as the input, or the dimension specified by `axis` is reduced. Default: False. Returns: - tuple (Tensor), tuple of 2 tensors, containing the minimum value and maximum value of the input tensor. + tuple (Tensor), containing the minimum value and maximum value of the input tensor. - - If `keepdims` is true, the shape of output tensors is + - If `keepdims` is True, the shape of output tensors is :math:`(x_1, x_2, ..., x_{axis-1}, 1, x_{axis+1}, ..., x_N)`. - Otherwise, the shape is + - If `keepdims` is False, the shape of output tensors is :math:`(x_1, x_2, ..., x_{axis-1}, x_{axis+1}, ..., x_N)`. Raises: @@ -6369,27 +6366,28 @@ def moveaxis(x, source, destination): def count_nonzero(x, dims=None): """ - Counts the number of non-zero values in the input tensor along the given dims. - If no dim is specified then all non-zeros in the tensor are counted. + Calculates the total number of non-zero entries in the input tensor along the + specified dimensions. If no dimensions are given, then the function will + count all non-zero entries in the tensor. Note: - The value range of "dims" is [-x_dims, x_dims). "x_dims" is the dimension length of input "x". + The value range of `dims` is [-x_dims, x_dims), `x_dims` is the dimension length of input "x". Args: - x (Tensor): Input to be computed, a N-D Tensor, can be any dimension. Set the shape of input tensor as + x (Tensor): Input to be computed, Tensor of any dimension. Set the shape of input tensor as :math:`(x_1, x_2, ..., x_N)` . - dims (int, list[int], tuple[int]): The dimension to count the number of non-zero values along. + dims (Union[int, list(int), tuple(int)], optional): The dimension to count the number of non-zero values along. Default: None. Returns: - A N-D Tensor, represents the number of the nonzero elements of the input tensor along the dims. - Reduces x_shape along the dimensions given in dims. For example, if the size of x is (2, 3, 4), - dims is [0, 1], y_shape will be (4,). + A N-D Tensor, represents the number of the nonzero elements of the input tensor along the `dims`. + Reduces x_shape along the dimensions given in `dims`. For example, if the size of `x` is :math:`(2, 3, 4)`, + `dims` is :math:`[0, 1]`, y_shape will be :math:`(4,)`. Raises: - TypeError: If the data type of `x` is not support. + TypeError: If the data type of `x` is not supported. TypeError: If the data type of `dims` is not int. - ValueError: If any of the values of `dims` is not in [-x_dims, x_dims). + ValueError: If any of the values of `dims` is not in range :math:`[-x_dims, x_dims)`. Supported Platforms: ``CPU`` diff --git a/mindspore/python/mindspore/ops/function/math_func.py b/mindspore/python/mindspore/ops/function/math_func.py index 1e676a478bf..8949bd8895c 100644 --- a/mindspore/python/mindspore/ops/function/math_func.py +++ b/mindspore/python/mindspore/ops/function/math_func.py @@ -2550,9 +2550,12 @@ def atan2(input, other): It returns :math:`\theta\ \in\ [-\pi, \pi]` such that :math:`input = r*\sin(\theta), other = r*\cos(\theta)`, where :math:`r = \sqrt{input^2 + other^2}`. - Args of `input` and `other` comply with the implicit type conversion rules to make the data types consistent. - If they have different data types, the lower precision data type will be converted to relatively the - highest precision data type. + .. note:: + - Arg `input` and `other` comply with the implicit type conversion rules to make the data types consistent. + If they have different data types, the lower precision data type will be converted to relatively the + highest precision data type. + - The inputs must be two tensors or one tensor and one scalar. + - When the inputs are one tensor and one scalar, the scalar could only be a constant. Args: input (Tensor, Number.number): The input tensor or scalar. @@ -4206,28 +4209,26 @@ def fmax(x1, x2): r""" Computes the maximum of input tensors element-wise. - Note: - - Inputs of `x1` and `x2` comply with the implicit type conversion rules to make the data types consistent. - - The inputs must be two tensors. - - Types of them are one of the following: float16, float32, float64, int32, int64. - - Shapes of them are supposed to be broadcast. - - If one of the elements to be compared is NaN, another element is returned. - .. math:: output_i = max(x1_i, x2_i) + Note: + - Inputs of `x1` and `x2` comply with the implicit type conversion rules to make the data types consistent. + - Shapes of `x1` and `x2` should be able to broadcast. + - If one of the elements to be compared is NaN, another element is returned. + Args: - x1 (Tensor): The first input is a tensor whose data type is number. - x2 (Tensor): The second input is is a tensor whose data type is number. + x1 (Tensor): The first tensor. The supported dtypes are: float16, float32, float64, int32, int64. + x2 (Tensor): The second tensor. The supported dtypes are: float16, float32, float64, int32, int64. Returns: A Tensor, the shape is the same as the one after broadcasting, and the data type is the one with higher precision or higher digits among the two inputs. Raises: - TypeError: If `x1` and `x2` is not Tensor. - TypeError: If dtype of `x1` and 'x2' is not one of: float16, float32, float64, int32, int64. - ValueError: If `x1` and `x2` are not the same shape after broadcast. + TypeError: If `x1` or `x2` is not Tensor. + TypeError: If dtype of `x1` or `x2` is not one of: float16, float32, float64, int32, int64. + ValueError: If the shape of `x1` and `x2` can not broadcast. Supported Platforms: ``CPU`` @@ -4298,28 +4299,26 @@ def fmin(x1, x2): r""" Computes the minimum of input tensors element-wise. - Note: - - Inputs of `x1` and `x2` comply with the implicit type conversion rules to make the data types consistent. - - The inputs must be two tensors. - - Types of them are one of the following: float16, float32, float64, int32, int64. - - Shapes of them are supposed to be broadcast. - - If one of the elements to be compared is NaN, another element is returned. - .. math:: output_i = min(x1_i, x2_i) + Note: + - Inputs of `x1` and `x2` comply with the implicit type conversion rules to make the data types consistent. + - Shapes of `x1` and `x2` should be able to broadcast. + - If one of the elements to be compared is NaN, another element is returned. + Args: - x1 (Tensor): The first input is a tensor whose data type is number. - x2 (Tensor): The second input is is a tensor whose data type is number. + x1 (Tensor): The first tensor. The supported dtypes are: float16, float32, float64, int32, int64. + x2 (Tensor): The second tensor. The supported dtypes are: float16, float32, float64, int32, int64. Returns: A Tensor, the shape is the same as the one after broadcasting, and the data type is the one with higher precision or higher digits among the two inputs. Raises: - TypeError: If `x1` and `x2` is not Tensor. - TypeError: If dtype of `x1` and 'x2' is not one of: float16, float32, float64, int32, int64. - ValueError: If `x1` and `x2` are not the same shape after broadcast. + TypeError: If `x1` or `x2` is not Tensor. + TypeError: If dtype of `x1` or `x2` is not one of: float16, float32, float64, int32, int64. + ValueError: If the shape of `x1` and `x2` can not broadcast. Supported Platforms: ``CPU`` @@ -5968,18 +5967,18 @@ def block_diag(*inputs): def atleast_1d(inputs): r""" - Converts `inputs` to arrays with at least one dimension. + Reshapes Tensor in `inputs`, every Tensor has at least one dimension after this operation. - Scalar `inputs` are converted to 1-dimensional arrays, whilst higher-dimensional `inputs` are preserved. + Scalar is converted to a 1-D Tensor, input tensor with one or more dimensions will be returned as it is. Args: - inputs (Union[Tensor, List[Tensor]]): One or more input tensors. + inputs (Union[Tensor, list[Tensor]]): One or more input tensors. Returns: - Tensor or list of tensors, each with ``a.ndim >= 1``. + Tensor or list[Tensor]. If returned a list, every element `a` in that list satisfies: `a`.ndim >= 1. Raises: - TypeError: If the input is not a tensor or a list of tensors. + TypeError: If the `input` is not a tensor or a list of tensors. Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` @@ -6007,14 +6006,14 @@ def atleast_1d(inputs): def dstack(inputs): r""" - Stacks tensors in sequence depth wise (along the third axis). + Stacks tensors in sequence depth wise. This is equivalent to concatenation along the third axis. 1-D tensors :math:`(N,)` should be reshaped to :math:`(1,N,1)`. 2-D tensors :math:`(M,N)` should be reshaped to :math:`(M,N,1)` before concatenation. Args: - inputs (Union(List[tensor], Tuple[tensor])): A sequence of tensors. + inputs (Union(List[Tensor], Tuple[Tensor])): A sequence of tensors. The tensors must have the same shape along all but the third axis. 1-D or 2-D tensors must have the same shape. @@ -6030,13 +6029,16 @@ def dstack(inputs): ``Ascend`` ``GPU`` ``CPU`` Examples: - >>> x1 = Tensor([1., 2., 3.]) - >>> x2 = Tensor([4., 5., 6.]) + >>> x1 = Tensor(np.arange(1, 7).reshape(2, 3)) + >>> x2 = Tensor(np.arange(7, 13).reshape(2, 3)) >>> out = ops.dstack([x1, x2]) >>> print(out.asnumpy()) - [[[1. 4.] - [2. 5.] - [3. 6.]]] + [[[ 1. 7.] + [ 2. 8.] + [ 3. 9.]] + [[ 4. 10.] + [ 5. 11.] + [ 6. 12.]]] """ if not isinstance(inputs, (tuple, list)): raise TypeError(f"For 'dstack', 'diff', 'inputs' must be list or tuple of tensors, but got {type(inputs)}") @@ -6134,11 +6136,12 @@ def diff(x, n=1, axis=-1, prepend=None, append=None): def tril_indices(row, col, offset=0, dtype=mstype.int64): r""" - Returns the indices of the lower triangular part of a row-by- col matrix in a 2-by-N Tensor, - where the first row contains row coordinates of all indices and the second row contains column coordinates. - Indices are ordered based on rows and then columns. + Calculates the indices of the lower triangular elements in a `row` * `col` matrix + and returns them as a 2-by-N Tensor. The first row of the Tensor contains + row coordinates, and the second row contains column coordinates. The coordinates are + sorted by row and then by column. - The lower triangular part of the matrix is defined as the elements on and below the diagonal. + The lower triangular part of the matrix consists of all elements on and below the diagonal. Note: When running on CUDA, row * col must be less than 2^59 to prevent overflow during calculation. @@ -6146,9 +6149,9 @@ def tril_indices(row, col, offset=0, dtype=mstype.int64): Args: row (int): number of rows in the 2-D matrix. col (int): number of columns in the 2-D matrix. - offset (int): diagonal offset from the main diagonal. Default: 0. + offset (int, optional): diagonal offset from the main diagonal. Default: 0. dtype (:class:`mindspore.dtype`): The specified type of output tensor. - An optional data type of `mindspore.int32` and `mindspore.int64`. Default: `mindspore.int32`. + An optional data type of `mindspore.int32` and `mindspore.int64`. Default: `mindspore.int64`. Returns: - **y** (Tensor) - indices of the elements in lower triangular part of matrix. The type is specified by `dtype`. @@ -6166,8 +6169,8 @@ def tril_indices(row, col, offset=0, dtype=mstype.int64): Examples: >>> output = ops.tril_indices(4, 3, -1, mindspore.int64) >>> print(output) - [[1 2 2 3 3 3] - [0 0 1 0 1 2]] + [[2 3 3] + [0 0 1]] >>> print(output.dtype) Int64 """ @@ -6178,11 +6181,12 @@ def tril_indices(row, col, offset=0, dtype=mstype.int64): def triu_indices(row, col, offset=0, dtype=mstype.int64): r""" - Returns the indices of the upper triangular part of a row by col matrix in a 2-by-N Tensor, - where the first row contains row coordinates of all indices and the second row contains column coordinates. - Indices are ordered based on rows and then columns. + Calculates the indices of the upper triangular elements in a `row` * `col` matrix + and returns them as a 2-by-N Tensor. The first row of the Tensor contains + row coordinates, and the second row contains column coordinates. The coordinates are + sorted by row and then by column. - The upper triangular part of the matrix is defined as the elements on and above the diagonal. + The upper triangular part of the matrix consists of all elements on and above the diagonal. Note: When running on CUDA, row * col must be less than 2^59 to prevent overflow during calculation. @@ -6190,9 +6194,9 @@ def triu_indices(row, col, offset=0, dtype=mstype.int64): Args: row (int): number of rows in the 2-D matrix. col (int): number of columns in the 2-D matrix. - offset (int): diagonal offset from the main diagonal. Default: 0. + offset (int, optional): diagonal offset from the main diagonal. Default: 0. dtype (:class:`mindspore.dtype`): The specified type of output tensor. - An optional data type of `mindspore.int32` and `mindspore.int64`. Default: `mindspore.int32`. + An optional data type of `mindspore.int32` and `mindspore.int64`. Default: `mindspore.int64`. Returns: - **y** (Tensor) - indices of the elements in upper triangular part of matrix. The type is specified by `dtype`. @@ -6208,7 +6212,7 @@ def triu_indices(row, col, offset=0, dtype=mstype.int64): ``GPU`` ``CPU`` Examples: - >>> output = ops.triu_indices(5, 4, 2, mindspore.int64) + >>> output = ops.triu_indices(4, 4, 2, mindspore.int64) >>> print(output) [[0 0 1] [2 3 3]] @@ -6222,17 +6226,18 @@ def triu_indices(row, col, offset=0, dtype=mstype.int64): def atleast_2d(inputs): r""" - Reshapes `inputs` as arrays with at least two dimensions. - Input tensor with two or more dimensions will be returned as is. + Reshapes Tensor in `inputs`, every Tensor has at least 2 dimension after this operation. + + Scalar or 1-D Tensor is converted to 2-D Tensor, tensor with higher dimensions will be returned as it is. Args: - inputs (Union[tensor, List[tensor]]): one or more input tensors. + inputs (Union[Tensor, list[Tensor]]): One or more input tensors. Returns: - Tensor or list of tensors, each with ``a.ndim >= 2``. + Tensor or list[Tensor]. If returned a list, every element `a` in that list satisfies: `a`.ndim >= 2. Raises: - TypeError: If the input is not a tensor or a list of tensors. + TypeError: If the `input` is not a tensor or a list of tensors. Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` @@ -6300,19 +6305,21 @@ def cartesian_prod(*inputs): def atleast_3d(inputs): r""" - Reshapes `inputs` as arrays with at least three dimensions. - Input tensor with three or more dimensions will be returned as is. + Reshapes Tensor in `inputs`, every Tensor has at least 2 dimension after this operation. + + Scalar, 1-D or 2-D Tensor is converted to 2-D Tensor, + tensor with higher dimensions will be returned as it is. Args: - inputs (Union[Tensor, List[Tensor]]): One or more input tensors. + inputs (Union[Tensor, list[Tensor]]): One or more input tensors. Returns: - Tensor or list of tensors, each with ``a.ndim >= 3``. For example, - a 1-D array of shape `(N,)` becomes a tensor of shape `(1, N, 1)`, and - a 2-D array of shape `(M, N)` becomes a tensor of shape `(M, N, 1)`. + Tensor or list[Tensor]. If returned a list, every element `a` in that list satisfies: `a`.ndim >= 3. + For example, a 1-D Tensor of shape :math:`(N,)` becomes a Tensor of shape :math:`(1, N, 1)`, and + a 2-D Tensor of shape :math:`(M, N)` becomes a tensor of shape :math:`(M, N, 1)`. Raises: - TypeError: If the input is not a tensor or a list of tensors. + TypeError: If the `input` is not a tensor or a list of tensors. Supported Platforms: ``Ascend`` ``GPU`` ``CPU`` @@ -6397,7 +6404,8 @@ def vstack(inputs): Stacks tensors in sequence vertically. This is equivalent to concatenation along the first axis. - 1-D tensors should firstly be reshaped to :math:`(1, N)`, and then be concatenated along the first axis. + 1-D tensors :math:`(N)` should firstly be reshaped to :math:`(1, N)`, + and then be concatenated along the first axis. Args: inputs (Union(List[tensor], Tuple[tensor])): A sequence of 1-D or 2-D tensors. @@ -6409,7 +6417,7 @@ def vstack(inputs): The output shape is similar to the output of `numpy.vstack()` function. Raises: - TypeError: If `inputs` is not list. + TypeError: If `inputs` is not list or tuple. ValueError: If `inputs` is empty. Supported Platforms: @@ -6417,12 +6425,12 @@ def vstack(inputs): Examples: >>> import mindspore.numpy as np - >>> x1 = np.array([1, 2, 3]) - >>> x2 = np.array([4, 5, 6]) + >>> x1 = np.array([3, 1, 4]) + >>> x2 = np.array([1, 5, 9]) >>> out = ops.vstack([x1, x2]) >>> print(out) - [[1 2 3] - [4 5 6]] + [[3 1 4] + [1 5 9]] """ if not isinstance(inputs, (tuple, list)): msg = f"List or tuple of tensors are required, but got {type(inputs)}" @@ -6452,20 +6460,24 @@ def vstack(inputs): def combinations(x, r=2, with_replacement=False): r""" - When `with_replacement` is set to `False`, the behavior is similar to python's + Returns all r-length subsequences of input Tensor. + + When `with_replacement` is set to `False`, it works similar to Python's `itertools.combinations`, and when `with_replacement` is set to `True`, it behaves like `itertools.combinations_with_replacement`. Args: x (Tensor): One-dimensional tensors. - r (int, optional): Number of elements. Default: 2. + r (int, optional): Number of elements to perform combination. Default: 2. with_replacement (bool, optional): Allow duplication or not. Default: False. Returns: - Tensor, equivalent to resulting list. + Tensor, contains all possible combinations of elements sampled from input Tensor. Raises: TypeError: If `x` is not a tensor. + TypeError: If `x` is not an int. + TypeError: If `with_replacement` is not bool. ValueError: If `x` is not one-dimensional. Supported Platforms: @@ -7676,7 +7688,7 @@ def stft(x, n_fft, hop_length=None, win_length=None, window=None, center=True, n_fft (int): The size of Fourier transform. hop_length (int, optional): The distance between neighboring sliding window frames. Default: None(treated as equal to :math:`floor(n_fft / 4)`). - hop_length (int, optional): the size of window frame and STFT filter. + win_length (int, optional): the size of window frame and STFT filter. Default: None(treated as equal to `n_fft`). window (Tensor, optional): the optional window function, 1-D tensor of size `win_length`. Default: None(treated as window of all :math:`1` s). If `win_length` < `n_fft`, @@ -8040,22 +8052,22 @@ def bmm(input_x, mat2): def quantile(x, q, axis=None, keepdims=False): r""" - Computes the q-th quantiles of all elements in the input tensor, doing a linear interpolation when the - q-th quantile lies between two data points. + Computes the q-th quantiles of all elements in `x`, when the + q-th quantile lies between two data points, a linear interpolation is implemented between them. Args: x (Tensor): The shape of tensor is :math:`(x_1, x_2, ..., x_R)`. - Supported dtypes: float32, float64. - q (float or Tensor): A scalar or 1D tensor of quantile values in the range [0, 1]. - Supported dtypes: float32, float64. - axis (int): The dimension to reduce. Default: None. By default, - axis is None resulting in the input tensor being flattened before computation. - keepdims (bool): Whether the output tensor has dim retained or not. Default: False. + Supported dtypes: float32, float64. + q (Union[float, Tensor]): A scalar or 1D tensor of quantile values in the range [0, 1]. + Supported dtypes: float32, float64. + axis (int, optional): The dimension to reduce. By default, `axis` is None resulting in the + input tensor being flattened before computation. Default: None. + keepdims (bool, optional): Whether the output tensor has dim retained or not. Default: False. Returns: - Tensor, has the same dtype as the `input`. + Tensor, has the same dtype as the `x`. - Assume the input shape is :math:`(m, x_0, x_1, ..., x_i, ..., X_R)`, axis = :math:`i` and m is + Suppose the shape of `x` is :math:`(m, x_0, x_1, ..., x_i, ..., X_R)`, `axis` = :math:`i` and m is the element count of input `q`. - If `q` is scalar and `keepdims` is True, the shape of output is :math:`(x_0, x_1, ..., 1, ..., X_R)`. @@ -8066,9 +8078,9 @@ def quantile(x, q, axis=None, keepdims=False): Raises: TypeError: If `x` is not a Tensor. TypeError: If `q` is not a Tensor or float. - TypeError: If dtype of `input` is not float32 or float64. + TypeError: If dtype of `x` is not float32 or float64. TypeError: If dtype of `q` is not float32 or float64. - TypeError: If dtype of `input` and the dtype of `q` is different. + TypeError: If dtype of `x` and the dtype of `q` is different. ValueError: If the `q` values not in the range [0, 1]. ValueError: If the `axis` values out of range. @@ -8094,25 +8106,25 @@ def quantile(x, q, axis=None, keepdims=False): def nanquantile(x, q, axis=None, keepdims=False): r""" - This is a variant of mindspore.ops.quantile() that 'ignores' NaN values, - computing the quantiles q as if NaN values in input did not exist. - If all values in a reduced row are NaN then the quantiles for that reduction will be NaN. + This operator is derived from mindspore.ops.quantile() that 'ignores' NaN values. + It computes quantiles as though the input has no NaN values. If all values in a + reduced dimension are NaN then the quantiles for that reduction will be NaN. - Refer to :func:`mindspore.ops.quantile` for more detail. + Refer to :func:`mindspore.ops.quantile` for more details. Args: x (Tensor): The shape of tensor is :math:`(x_1, x_2, ..., x_R)`. - Supported dtypes: float32, float64. - q (float or Tensor): A scalar or 1D tensor of quantile values in the range [0, 1]. - Supported dtypes: float32, float64. - axis (int): The dimension to reduce. Default: None. By default, - axis is None resulting in the input tensor being flattened before computation. - keepdims (bool): Whether the output tensor has dim retained or not. Default: False. + Supported dtypes: float32, float64. + q (Union[float, Tensor]): A scalar or 1D tensor of quantile values in the range [0, 1]. + Supported dtypes: float32, float64. + axis (int, optional): The dimension to reduce. By default, `axis` is None resulting in the + input tensor being flattened before computation. Default: None. + keepdims (bool, optional): Whether the output tensor has dim retained or not. Default: False. Returns: - Tensor, has the same dtype as the `input`. + Tensor, has the same dtype as the `x`. - Assume the input shape is :math:`(m, x_0, x_1, ..., x_i, ..., X_R)`, axis = :math:`i` and m is + Suppose the shape of `x` is :math:`(m, x_0, x_1, ..., x_i, ..., X_R)`, `axis` = :math:`i` and m is the element count of input `q`. - If `q` is scalar and `keepdims` is True, the shape of output is :math:`(x_0, x_1, ..., 1, ..., X_R)`. @@ -8123,10 +8135,10 @@ def nanquantile(x, q, axis=None, keepdims=False): Raises: TypeError: If `x` is not a Tensor. TypeError: If `q` is not a Tensor or float. - TypeError: If dtype of `input` is not float32 or float64. + TypeError: If dtype of `x` is not float32 or float64. TypeError: If dtype of `q` is not float32 or float64. - TypeError: If dtype of `input` and the dtype of `q` is different. - ValueError: If the `q` values not in the range [0, 1] + TypeError: If dtype of `x` and the dtype of `q` is different. + ValueError: If the `q` values not in the range [0, 1]. ValueError: If the `axis` values out of range. Supported Platforms: @@ -9635,41 +9647,32 @@ def polygamma(a, x): .. math:: \psi^{(a)}(x) = \frac{d^{(a)}}{dx^{(a)}} \psi(x) + where \psi(x) is the digamma function. + Args: - a (Tensor): the order of the polygamma function, types: int32, int64, the shape of a is 0. - x (Tensor): the tensor to compute the polygamma function. + a (Tensor): The order of the polygamma function. + Supported dtypes: int32, int64. The shape of `a` is :math:`()`. + x (Tensor): The tensor to compute the `a^{th}` derivative of the polygamma function with. Returns: Tensor, has the same dtype as `x`. Raises: - TypeError: If x is not a Tensor. - TypeError: If dtype of input x is not one of: float16, float32, float64. - TypeError: If dtype of input a is not one of: int32, int64. - TypeError: If shape of input a is not 0. + TypeError: If `x` is not a Tensor. + TypeError: If dtype of `x` is not one of: float16, float32, float64. + TypeError: If dtype of `a` is not one of: int32, int64. + TypeError: If shape of `a` is not :math:`()`. Supported Platforms: ``GPU`` ``CPU`` Examples: - >>> x = Tensor(np.array([1.0, -0.5]), mindspore.float32) + >>> x = Tensor(np.array([3.14, -2.71]), mindspore.float64) >>> a = Tensor(np.array(1), mindspore.int64) >>> polygamma = ops.Polygamma() >>> output = polygamma(a, x) >>> print(output) - [1.644934 8.934802] - >>> a = Tensor(np.array(2), mindspore.int64) - >>> output = polygamma(a, x) - >>> print(output) - [-2.404114 -0.8287967] - >>> a = Tensor(np.array(3), mindspore.int64) - >>> output = polygamma(a, x) - >>> print(output) - [ 6.4939404 193.40909 ] - >>> a = Tensor(np.array(4), mindspore.int64) - >>> output = polygamma(a, x) - >>> print(output) - [-24.886265 -3.4742498] + [ 0.3745, 15.4988] """ polygamma_op = _get_cache_prim(P.Polygamma)() return polygamma_op(a, x) @@ -9907,11 +9910,13 @@ def diag_embed(x, offset=0, dim1=-2, dim2=-1): Args: x (Tensor): Values to fill diagonal. - offset (int): Offset of the diagonal. :math:`offset=0` refers to the main diagonal. If :math:`offset>0`, - fill the diagonals that are `offset` units upward from the main diagonal. If :math:`offset<0`, fill the - diagonals that are `offset` units downward from the main diagonal. Default: 0. - dim1 (int): The first dimension in `x` with respect to which to fill diagonal. Default: -2. - dim2 (int): The second dimension in `x` with respect to which to fill diagonal. Default: -1. + offset (int, optional): Offset of the diagonal. :math:`offset=0` refers to the main diagonal. Default: 0. + + - If :math:`offset>0`, fill the diagonals that are `offset` units upward from the main diagonal. + - If :math:`offset<0`, fill the diagonals that are `offset` units downward from the main diagonal. + + dim1 (int, optional): The first dimension in `x` with respect to which to fill diagonal. Default: -2. + dim2 (int, optional): The second dimension in `x` with respect to which to fill diagonal. Default: -1. Returns: Tensor, has the same dtype as `x`, but the shape of output is one dimension higher than the `x`. @@ -9920,9 +9925,8 @@ def diag_embed(x, offset=0, dim1=-2, dim2=-1): TypeError: If `x` is not a Tensor. TypeError: If dtype of `x` is not supported. TypeError: If `offset` is not an int. - TypeError: If `dim1` is not an int. - TypeError: If `dim2` is not an int. - ValueError: If the dimension of input is not 1-6D. + TypeError: If `dim1` or `dim2` is not an int. + ValueError: If the dimension of `x` is not 1D-6D. ValueError: If `dim1` is not in range of [-len(x.shape), len(x.shape)). ValueError: If `dim2` is not in range of [-len(x.shape), len(x.shape)). ValueError: If `dim1` and `dim2` are identical. diff --git a/mindspore/python/mindspore/ops/operations/array_ops.py b/mindspore/python/mindspore/ops/operations/array_ops.py index 9a814f3a0fb..f71a9722b83 100755 --- a/mindspore/python/mindspore/ops/operations/array_ops.py +++ b/mindspore/python/mindspore/ops/operations/array_ops.py @@ -7996,10 +7996,10 @@ class Bincount(Primitive): class CountNonZero(Primitive): """ - Counts the number of non-zero values in the input tensor along the given dims. - If no dim is specified then all non-zeros in the tensor are counted. + Calculates the total number of non-zero entries in the input tensor along the + specified dimensions. - Refer to :func:`mindspore.ops.count_nonzero` for more detail. + Refer to :func:`mindspore.ops.count_nonzero` for more details. Supported Platforms: ``CPU`` diff --git a/mindspore/python/mindspore/ops/operations/math_ops.py b/mindspore/python/mindspore/ops/operations/math_ops.py index 2824ce9317f..b5e8be249df 100644 --- a/mindspore/python/mindspore/ops/operations/math_ops.py +++ b/mindspore/python/mindspore/ops/operations/math_ops.py @@ -7298,33 +7298,10 @@ class NextAfter(Primitive): class TrilIndices(Primitive): r""" - Returns the indices of the lower triangular part of a `row` -by- `col` matrix in a Tensor. - The Tensor has a shape :math:`(2, tril\_size)` where :math:`tril\_size` is the number of - elements in the lower triangular matrix. The first row contains row coordinates of - all indices and the second row contains column coordinates. - Indices are ordered based on rows and then columns. + Calculates the indices of the lower triangular elements in a `row` * `col` matrix + and returns them as a 2-by-N Tensor. - The lower triangular part of the matrix is defined as the elements on and below the diagonal. - - Note: - When running on CUDA, row * col must be less than 2^59 to prevent overflow during calculation. - - Args: - row (int): number of rows in the 2-D matrix. - col (int): number of columns in the 2-D matrix. - offset (int, optional): diagonal offset from the main diagonal. Default: 0. - dtype (:class:`mindspore.dtype`, optional): The specified type of output tensor. - An optional data type of `mstype.int32` and `mstype.int64`. Default: `mstype.int32`. - - Outputs: - - **y** (Tensor) - indices of the elements in lower triangular part of matrix. The type specified by `dtype`. - The shape of output is :math:`(2, tril\_size)`, where :math:`tril\_size` is the number of elements in the - lower triangular matrix. - - Raises: - TypeError: If `row`, `col` or `offset` is not an int. - TypeError: If `dtype` is neither int32 nor int64. - ValueError: If `row` or `col` < 0. + Refer to :func:`mindspore.ops.tril_indices` for more details. Supported Platforms: ``GPU`` ``CPU`` @@ -7527,33 +7504,10 @@ class Orgqr(Primitive): class TriuIndices(Primitive): r""" - Returns the indices of the upper triangular part of a `row` -by- `col` matrix in a Tensor. - The Tensor has a shape :math:`(2, tril\_size)` where :math:`tril\_size` is the number of - elements in the upper triangular matrix. The first row contains row coordinates of - all indices and the second row contains column coordinates. - Indices are ordered based on rows and then columns. + Calculates the indices of the upper triangular elements in a `row` * `col` matrix + and returns them as a 2-by-N Tensor. - The upper triangular part of the matrix is defined as the elements on and above the diagonal. - - Note: - When running on CUDA, row * col must be less than 2^59 to prevent overflow during calculation. - - Args: - row (int): number of rows in the 2-D matrix. - col (int): number of columns in the 2-D matrix. - offset (int, optional): diagonal offset from the main diagonal. Default: 0. - dtype (:class:`mindspore.dtype`, optional): The specified type of output tensor. - An optional data type of `mstype.int32` and `mstype.int64`. Default: `mstype.int32`. - - Outputs: - - **y** (Tensor) - indices of the elements in lower triangular part of matrix. The type specified by `dtype`. - The shape of output is :math:`(2, tril\_size)`, where :math:`tril\_size` is the number of elements in the - lower triangular matrix. - - Raises: - TypeError: If `row`, `col` or `offset` is not an int. - TypeError: If `dtype` is neither int32 nor int64. - ValueError: If `row` or `col` < 0. + Refer to :func:`mindspore.ops.triu_indices` for more details. Supported Platforms: ``GPU`` ``CPU``