!45628 add some operators documents.

Merge pull request !45628 from yangshuo/code_docs_api
2022-11-21 08:42:56 +00:00 · 2022-11-21 08:42:56 +00:00 · 198db29f7e
parent 3f5b9c2eec 3c055537c7
commit 198db29f7e
10 changed files with 194 additions and 8 deletions
--- a/docs/api/api_python/mindspore.ops.rst
+++ b/docs/api/api_python/mindspore.ops.rst
@ -54,6 +54,7 @@ MindSpore中 `mindspore.ops` 接口与上一版本相比，新增、删除和支
    mindspore.ops.Conv3D
    mindspore.ops.Conv3DTranspose
    mindspore.ops.CTCGreedyDecoder
+    mindspore.ops.Dilation2D
    mindspore.ops.Dropout
    mindspore.ops.Dropout2D
    mindspore.ops.Dropout3D
@ -208,6 +209,7 @@ MindSpore中 `mindspore.ops` 接口与上一版本相比，新增、删除和支
    mindspore.ops.CheckValid
    mindspore.ops.CombinedNonMaxSuppression
    mindspore.ops.CropAndResize
+    mindspore.ops.ExtractGlimpse
    mindspore.ops.ExtractVolumePatches
    mindspore.ops.HSVToRGB
    mindspore.ops.IOU
@ -291,6 +293,7 @@ MindSpore中 `mindspore.ops` 接口与上一版本相比，新增、删除和支
    mindspore.ops.Conj
    mindspore.ops.Cos
    mindspore.ops.Cosh
+    mindspore.ops.Digamma
    mindspore.ops.Div
    mindspore.ops.DivNoNan
    mindspore.ops.Einsum
@ -352,6 +355,7 @@ Reduction算子
    mindspore.ops.ArgMaxWithValue
    mindspore.ops.Argmin
    mindspore.ops.ArgMinWithValue
+    mindspore.ops.EuclideanNorm
    mindspore.ops.ReduceAll
    mindspore.ops.ReduceAny
    mindspore.ops.ReduceMax
@ -473,6 +477,8 @@ Array操作
    mindspore.ops.DepthToSpace
    mindspore.ops.DiagPart
    mindspore.ops.DType
+    mindspore.ops.Eig
+    mindspore.ops.Expand
    mindspore.ops.ExpandDims
    mindspore.ops.FFTWithSize
    mindspore.ops.FloatStatus
--- a/docs/api/api_python/ops/mindspore.ops.Digamma.rst
+++ b/docs/api/api_python/ops/mindspore.ops.Digamma.rst
@ -0,0 +1,22 @@
+mindspore.ops.Digamma
+======================
+
+.. py:class:: mindspore.ops.Digamma
+
+    计算输入的lgamma函数的导数。
+
+    .. math::
+        P(x) = grad(ln(gamma(x)))
+
+    .. warning::
+        此算子为实验性算子，将来可能面临更改或删除。
+
+    输入:
+        - **x** (Tensor) - 输入Tensor。数据类型为 `float16` 、 `float32` 或者 `float64` 。
+
+    输出:
+        Tensor, 和输入 `x` 具有相同的数据类型。
+
+    异常:
+        - **TypeError** - 如果输入 `x` 不是Tensor。
+        - **TypeError** - 输入输入 `x` 的数据类型不是 `float16` 、 `float32` 或者 `float64` 。
--- a/docs/api/api_python/ops/mindspore.ops.Dilation2D.rst
+++ b/docs/api/api_python/ops/mindspore.ops.Dilation2D.rst
@ -0,0 +1,58 @@
+mindspore.ops.Dilation2D
+=========================
+
+.. py:class:: mindspore.ops.Dilation2D(stride, dilation, pad_mode="SAME", data_format="NCHW")
+
+    计算4-D和3-D输入Tensor的灰度膨胀。
+
+    对输入的shape为 :math:`(N, C_{in}, H_{in}, W_{in})` ，应用2-D膨胀，其中，
+
+    :math:`N` 为batch大小， :math:`H` 为高度， :math:`W`为宽度， :math:`C` 为通道数量。
+
+    给定kernel size :math:`ks = (h_{ker}, w_{ker})`, stride :math:`s = (s_0, s_1)`，和
+
+    dilation :math:`d = (d_0, d_1)` ，计算如下:
+
+    .. math::
+        \text{output}(N_i, C_j, h, w) = \max_{m=0, \ldots, h_{ker}-1} \max_{n=0, \ldots, w_{ker}-1}
+        \text{input}(N_i, C_j, s_0 \times h + d_0 \times m, s_1 \times w + d_1 \times n) + \text{filter}(C_j, m, n)
+
+    .. warning::
+        - 此算子为实验性算子。
+        - 如果输入数据类型为float32，算子仍然按float16模式执行。
+
+    参数：
+        - **stride** (Union(int，tuple[int])) - kernel移动的距离。
+          如果为一个int整数，则表示了height和width共同的步长。
+          如果为两个int整数的元组，则分别表示height和width的步长。
+          如果为四个int整数的元组，则说明数据格式为 `NCHW` ，表示 `[1, 1, stride_height, stride_width]` 。
+        - **dilation** (Union(int，tuple[int])) - 数据类型为int，或者包含2个整数的元组，或者包含4个整数的元组，指定用于扩张卷积的膨胀速率。
+          如果设置为 :math:`k > 1` ，则每次抽样点跳过 :math:`k - 1` 个像素点。
+          其值必须大于等于1，并且以输入的宽度和高度为边界。
+        - **pad_mode** (str，可选) - 指定填充模式，可选模式有"same", "valid"，默认值："same"。大小写均支持。
+
+          - same：采用完全方式。输出的宽度和高度和输入的一样。
+
+          - valid：采用丢弃的方式。没有填充时候输出为最大的高度和宽度。额外的像素点将被丢弃。
+
+        - **data_format** (str，可选) - 数据格式的值。目前只支持`NCHW`，默认值: `NCHW` 。
+
+    输入：
+        - **x** (Tensor) - 输入数据。一个四维Tensor，数据类型为float16、float32，shape必须为
+          :math:`(N, C_{in}, H_{in}, W_{in})` 。
+        - **filter** (Tensor) - 一个三维Tensor，数据类型和输入 `x` 相同，shape必须为
+          :math:`(C_{in}, H_{filter}, W_{filter})` 。
+
+    输出：
+        Tensor，其值已经过dilation2D。shape为 :math:`(N, C_{out}, H_{out}, W_{out})`，未必和输入 `x` shape相同，数据类型和输入 `x` 相同。
+
+    异常：
+        - **TypeError** - 如果输入 `x` 或者 `filter` 的数据类型不是uint8、uint16、uint32、uint64、int8、int16、
+          int32、int64、float16、float32、float64。
+        - **TypeError** - 如果参数 `stride` 或者 `dilation` 不是一个整数或者包含两个整数的元组或者包含四个整数的元组。
+        - **ValueError** - 如果参数 `stride` 或者 `dilation` 是一个元组，并且它的长度不是2或者4。
+        - **ValueError** - 如果参数 `stride` 或者 `dilation` 是一个包含四个整数的元组，它的shape不是 `(1, 1, height, width)`。
+        - **ValueError** - 如果参数 `stride` 的取值范围不是`[1, 255]`。
+        - **ValueError** - 如果参数 `dilation` 的值小于1。
+        - **ValueError** - 如果参数 `pad_mode` 不是 `same` 、 `valid` 、 `SAME` 或者 `VALID`。
+        - **ValueError** - 如果参数 `data_format` 不是字符串`NCHW`。
--- a/docs/api/api_python/ops/mindspore.ops.Eig.rst
+++ b/docs/api/api_python/ops/mindspore.ops.Eig.rst
@ -0,0 +1,24 @@
+mindspore.ops.Eig
+==================
+
+.. py:class:: mindspore.ops.Eig(compute_v=False)
+
+    计算输入方阵（batch方阵）的特征值和特征向量。
+
+    参数：
+        - **compute_v** (bool，可选) - 如果为True，同时计算特征值和特征向量，如果为False，只计算特征值，默认值：False。
+
+    输入:
+        - **x** (Tensor) - 方阵。shape为 :math:`(*, N, N)`，数据类型支持
+          float32、float64、complex64、complex128。
+
+    输出:
+        - **eigen_values** (Tensor) - shape为 :math:`(*, N)`，其中的每个向量代表对应矩阵的特征值，特征值之间没有顺序关系。
+        - **eigen_vectors** (Tensor) - 如果 `compute_v` 为False，此为空Tensor，否则，为shape :math:`(*, N, N)` 的Tensor。
+          其列表示相应特征值的规范化（单位长度）特征向量。
+
+    异常：
+        - **TypeError** - 如果 `compute_v` 数据类型不是一个bool。
+        - **TypeError** - 如果 `x` 的数据类型不是： float32、float64、complex64或者complex128。
+        - **TypeError** - 如果 `x` 不是一个Tensor。
+        - **ValueError** - 如果 `x` 不是一个方阵（batch方阵）。
--- a/docs/api/api_python/ops/mindspore.ops.EuclideanNorm.rst
+++ b/docs/api/api_python/ops/mindspore.ops.EuclideanNorm.rst
@ -0,0 +1,22 @@
+mindspore.ops.EuclideanNorm
+============================
+
+.. py:class:: mindspore.ops.EuclideanNorm(keep_dims=False):
+
+    计算Tensor维度上元素的欧几里得范数，根据给定的轴对输入进行规约操作。
+
+    参数：
+        - **keep_dims** （bool，可选） - 如果为True，被规约的轴保留为1，如果为False，不保留给定的这些轴，默认值：False。
+
+    输入：
+        - **x** (Tensor) - 输入Tensor，将被规约，数据类型为：float16、float32、float64、int8、int16、
+          int32、int64、complex64、complex128、uint8、uint16、uint32、uint64。
+        - **axes** (Tensor) - 将进行规约的轴。数据类型为：int32、int64。取值范围为： `[-rank(x), rank(x))`。
+
+    输出：
+        Tensor，与输入 `x` 具有相同的数据类型。
+
+    异常：
+        - **TypeError** - 如果 `keep_dims` 不是一个bool值。
+        - **TypeError** - 如果 `x` 不是一个Tensor。
+        - **ValueError** - 如果 `axes` 超出取值范围。
--- a/docs/api/api_python/ops/mindspore.ops.Expand.rst
+++ b/docs/api/api_python/ops/mindspore.ops.Expand.rst
@ -0,0 +1,8 @@
+mindspore.ops.Expand
+=====================
+
+.. py:class:: mindspore.ops.Expand
+
+    返回一个当前张量的新视图，其中单维度扩展到更大的尺寸。
+
+    更多细节请参考 :func:`mindspore.ops.expand`。
--- a/docs/api/api_python/ops/mindspore.ops.ExtractGlimpse.rst
+++ b/docs/api/api_python/ops/mindspore.ops.ExtractGlimpse.rst
@ -0,0 +1,39 @@
+mindspore.ops.ExtractGlimpse
+=============================
+
+.. py:class:: mindspore.ops.ExtractGlimpse(centered=True, normalized=True, uniform_noise=True, noise="uniform")
+
+    从输入图像Tensor中提取glimpse，并返回一个窗口。
+
+    .. note::
+        如果窗口和输入图像Tensor没有重叠，用随机噪声进行填充。
+
+    参数：
+        - **centered** (bool，可选) - 可选的bool，指示偏移坐标是否相对于图像居中，如果为True，表示
+          (0,0)偏移是相对于输入图像的中心的；如果为False，则(0,0)偏移量对应于输入图像的左上角。默认为True。
+        - **normalized** (bool，可选) - 可选的bool，指示偏移坐标是否归一化。默认为True。
+        - **uniform_noise** (bool，可选) - 可选的bool，指示是否应该使用均匀分布或高斯分布生成噪声。默认为True。
+        - **noise** (str，可选) - 可选string，其值可以为： `uniform` 、 `gaussian` 和 `zero` 。
+          窗口由输入大小和偏移决定，如果窗口与输入部分没有重叠，则填充随机噪声。当 `noise` 为 `uniform` 或者 `gaussian` ，
+          其填充结果是变量。当 `noise`为 `zero` ，则 `uniform_noise` 必须为False，这样填充的噪声才是0，保证了结果的正确。
+          当 `uniform_noise` 为True， `noise` 仅可以为 `uniform` 。当 `uniform_noise` 为False， `noise`可以为 `uniform` 、 `gaussian` 和 `zero` 。
+          默认为 `uniform` 。
+
+    输入：
+        - **x** (Tensor) - 一个 `4-D` 的Tensor，shape为 `[batch_size, height, width, channels]` ，dtype为float32。
+        - **size** (Tensor) - 一个包含2个元素的 `1-D` Tensor，包含了提取glimpses的大小。
+          `glimpse` 的高度必须首先指定，然后是其宽度，数据类型为int32，其大小必须大于0。
+        - **offsets** (Tensor) - 一个 `2-D` 的Tensor，shape为[batch_size, 2]，包含了每个窗口中心点的y、x位置，数据类型为float32。
+
+    输出：
+        一个 `4-D` 的Tensor，shape为 `[batch_size, glimpse_height, glimpse_width, channels]` ，数据类型为float32。
+
+    异常：
+        - **TypeError** - 如果 `centered` 不是一个bool。
+        - **TypeError** - 如果 `normalize` 不是一个bool。
+        - **TypeError** - 如果 `uniform_noise` 不是一个bool。
+        - **ValueError** - 如果 `noise` 不是 `uniform` 、 `gaussian` 或者 `zero`。
+        - **ValueError** - 如果 `size` 的值不是常数。
+        - **ValueError** - 如果输入 `x` 和 `offsets` 的batch_size不一致。
+        - **ValueError** - 如果 `offsets[1]` 不是2。
+        - **ValueError** - 如果输入 `x` 不是一个Tensor。
--- a/docs/api/api_python_en/mindspore.ops.rst
+++ b/docs/api/api_python_en/mindspore.ops.rst
@ -54,6 +54,7 @@ Neural Network
    mindspore.ops.Conv3D
    mindspore.ops.Conv3DTranspose
    mindspore.ops.CTCGreedyDecoder
+    mindspore.ops.Dilation2D
    mindspore.ops.Dropout
    mindspore.ops.Dropout2D
    mindspore.ops.Dropout3D
@ -207,6 +208,7 @@ Image Processing
    mindspore.ops.CheckValid
    mindspore.ops.CombinedNonMaxSuppression
    mindspore.ops.CropAndResize
+    mindspore.ops.ExtractGlimpse
    mindspore.ops.ExtractVolumePatches
    mindspore.ops.HSVToRGB
    mindspore.ops.IOU
@ -290,6 +292,7 @@ Element-wise Operator
    mindspore.ops.Conj
    mindspore.ops.Cos
    mindspore.ops.Cosh
+    mindspore.ops.Digamma
    mindspore.ops.Div
    mindspore.ops.DivNoNan
    mindspore.ops.Einsum
@ -351,6 +354,7 @@ Reduction Operator
    mindspore.ops.ArgMaxWithValue
    mindspore.ops.Argmin
    mindspore.ops.ArgMinWithValue
+    mindspore.ops.EuclideanNorm
    mindspore.ops.ReduceAll
    mindspore.ops.ReduceAny
    mindspore.ops.ReduceMax
@ -472,6 +476,8 @@ Array Operation
    mindspore.ops.DepthToSpace
    mindspore.ops.DiagPart
    mindspore.ops.DType
+    mindspore.ops.Eig
+    mindspore.ops.Expand
    mindspore.ops.ExpandDims
    mindspore.ops.FFTWithSize
    mindspore.ops.FloatStatus
--- a/mindspore/python/mindspore/ops/operations/image_ops.py
+++ b/mindspore/python/mindspore/ops/operations/image_ops.py
@ -184,15 +184,15 @@ class ExtractGlimpse(Primitive):
        If the window and input image tensor not overlap, random noise is filled.

    Args:
-        centered (bool): An optional `bool`. Defaults to `True`. Indicates if the offset coordinates
+        centered (bool): An optional `bool`. Indicates if the offset coordinates
            are centered relative to the image, in which case the (0, 0) offset is relative to the center of
            the center of the input images. If false, the (0, 0) offset corresponds to the upper left corner
-            of the input images.
-        normalized (bool): An optional `bool`. Defaults to `True`. indicates if the offset
-            coordinates are normalized.
-        uniform_noise (bool): An optional `bool`. Defaults to `True`. indicates if the noise should be
-            generated using a uniform distribution or a Gaussian distribution.
-        noise (str): An optional string that defaults to `uniform`. The value can be 'uniform', 'gaussian'
+            of the input images. Defaults to `True`.
+        normalized (bool): An optional `bool`. indicates if the offset
+            coordinates are normalized. Defaults to `True`.
+        uniform_noise (bool): An optional `bool`. indicates if the noise should be
+            generated using a uniform distribution or a Gaussian distribution. Defaults to `True`.
+        noise (str): An optional string. The value can be 'uniform', 'gaussian'
            and 'zero'. The window is determined by size and offsets.
            When the window and input image tensor not overlap, random noise is filled.
            The result is variable when noise is equal to 'uniform' and 'gaussian'.
@ -200,6 +200,7 @@ class ExtractGlimpse(Primitive):
            filling noise will be zero so that the result is fixed.
            When uniform_noise is 'True', the value of noise only can be 'uniform'.
            When uniform_noise is 'False', the value of noise can be 'uniform', 'gaussian' and 'zero'.
+            Defaults to `uniform`.

    Inputs:
        - **x** (Tensor) - A 4-D float tensor of shape [batch_size, height, width, channels].
--- a/mindspore/python/mindspore/ops/operations/nn_ops.py
+++ b/mindspore/python/mindspore/ops/operations/nn_ops.py
@ -8256,7 +8256,7 @@ class Dilation2D(Primitive):
        \text{input}(N_i, C_j, s_0 \times h + d_0 \times m, s_1 \times w + d_1 \times n) + \text{filter}(C_j, m, n)

    .. warning::
-        This operator is an experimental operator, which has some accuracy problems for some inputs.
+        This operator is an experimental operator.
        If the input data type is float32, this operator is still executed in float16 mode.

    Args: