From 57018cb669ecaba8901df956054853f42890bf9d Mon Sep 17 00:00:00 2001 From: wangshuide2020 Date: Mon, 20 Dec 2021 15:33:20 +0800 Subject: [PATCH] optimize the documentation of chinese API of ELU, ReLU, Tril, etc. --- docs/api/api_python/nn/mindspore.nn.ELU.rst | 9 +-- .../api_python/nn/mindspore.nn.Flatten.rst | 10 ++-- .../api/api_python/nn/mindspore.nn.L1Loss.rst | 17 +++--- ...akyrelu.rst => mindspore.nn.LeakyReLU.rst} | 21 +++---- .../api_python/nn/mindspore.nn.Moments.rst | 57 +++++++++---------- docs/api/api_python/nn/mindspore.nn.ReLU.rst | 8 +-- .../nn/mindspore.nn.SmoothL1Loss.rst | 25 ++++---- .../api_python/nn/mindspore.nn.Softmax.rst | 14 ++--- docs/api/api_python/nn/mindspore.nn.Tril.rst | 16 ++++-- 9 files changed, 92 insertions(+), 85 deletions(-) rename docs/api/api_python/nn/{mindspore.nn.leakyrelu.rst => mindspore.nn.LeakyReLU.rst} (53%) diff --git a/docs/api/api_python/nn/mindspore.nn.ELU.rst b/docs/api/api_python/nn/mindspore.nn.ELU.rst index de32a990bdf..20fb95d57e3 100644 --- a/docs/api/api_python/nn/mindspore.nn.ELU.rst +++ b/docs/api/api_python/nn/mindspore.nn.ELU.rst @@ -10,10 +10,11 @@ mindspore.nn.ELU .. math:: E_{i} = \begin{cases} - x, &\text{if } x \geq 0; \cr - \text{alpha} * (\exp(x_i) - 1), &\text{otherwise.} + x_i, &\text{if } x_i \geq 0; \cr + \alpha * (\exp(x_i) - 1), &\text{otherwise.} \end{cases} + 其中，:math:`x_i` 表示输入的元素，:math:`\alpha` 表示 `alpha` 参数。 ELU相关图参见 `ELU `_ 。 @@ -23,11 +24,11 @@ mindspore.nn.ELU **输入：** - - **x** （Tensor） - 用于计算ELU的Tensor，数据类型为float16或float32。shape为 :math:`(N,*)` ， :math:`*` 表示任意的附加维度数。 + - **x** （Tensor） - 用于计算ELU的任意维度的Tensor，数据类型为float16或float32。 **输出：** - Tensor，具有与 `x` 相同的数据类型和shape。 + Tensor，数据类型和shape与 `x` 相同。 **异常：** diff --git a/docs/api/api_python/nn/mindspore.nn.Flatten.rst b/docs/api/api_python/nn/mindspore.nn.Flatten.rst index f3191470d82..4f7454391b0 100644 --- a/docs/api/api_python/nn/mindspore.nn.Flatten.rst +++ b/docs/api/api_python/nn/mindspore.nn.Flatten.rst @@ -3,15 +3,15 @@ mindspore.nn.Flatten .. py:class:: mindspore.nn.Flatten - 对输入Tensor的第0维的batch size之外的维度进行展平操作。 + 对输入Tensor的第0维之外的维度进行展平操作。 **输入：** - - **x** (Tensor) - 要展平的输入Tensor。shape为 :math:`(N,*)`，其中 :math:`*` 表示任意的附加维度数。数据类型为Number。 + - **x** (Tensor) - 要展平的输入Tensor。shape为 :math:`(N, *)`，其中 :math:`*` 表示任意的附加维度。数据类型为 `number `_。 **输出：** - Tensor，shape为 :math:`(N,X)`，其中 :math:`X` 是输入 `x` 的shape除N之外的其余维度的乘积。 + Tensor，shape为 :math:`(N, X)`，其中 :math:`X` 是输入 `x` 的shape除N之外的其余维度的乘积。 **异常：** @@ -30,7 +30,7 @@ mindspore.nn.Flatten [[1.2 1.2 2.1 2.1] [2.2 2.2 3.2 3.2]] >>> print(f"Before flatten the x shape is {x.shape}.") - 展平前x的shape为(2, 2, 2) + Before flatten the x shape is (2, 2, 2) >>> print(f"After flatten the output shape is {output.shape}.") - 展平后输出的shape为(2, 4) + After flatten the output shape is (2, 4) \ No newline at end of file diff --git a/docs/api/api_python/nn/mindspore.nn.L1Loss.rst b/docs/api/api_python/nn/mindspore.nn.L1Loss.rst index 7fe560ee595..19d19a60c4c 100644 --- a/docs/api/api_python/nn/mindspore.nn.L1Loss.rst +++ b/docs/api/api_python/nn/mindspore.nn.L1Loss.rst @@ -3,9 +3,9 @@ mindspore.nn.L1Loss .. py:class:: mindspore.nn.L1Loss(reduction='mean') - L1Loss用于测量 :math:`x` 和 :math:`y` 元素之间的平均绝对误差（MAE），其中 :math:`x` 是输入Tensor和 :math:`y` 是标签Tensor。 + L1Loss用于计算预测值和目标值之间的平均绝对误差。 - 假设 :math:`x` 和 :math:`y` 为一维Tensor，长度 :math:`N` ，则计算 :math:`x` 和 :math:`y` 的unreduced loss（即reduction参数设置为"none"）的公式如下： + 假设 :math:`x` 和 :math:`y` 为一维Tensor，长度 :math:`N` ，则计算 :math:`x` 和 :math:`y` 的loss而不进行降维操作（即reduction参数设置为"none"）的公式如下： .. math:: \ell(x, y) = L = \{l_1,\dots,l_N\}^\top, \quad \text{with } l_n = \left| x_n - y_n \right|, @@ -21,20 +21,21 @@ mindspore.nn.L1Loss **参数：** - **reduction** (str) - 应用于loss的reduction类型。取值为"mean"，"sum"，或"none"。默认值："mean"。 + **reduction** (str) - 应用于loss的reduction类型。取值为"mean"，"sum"，或"none"。默认值："mean"。如果 `reduction` 为'mean'或'sum'，则输出一个标量Tensor；如果 `reduction` 为'none'，则输出Tensor的shape为广播后的shape。 **输入：** - - **logits** (Tensor) - shape为 :math:`(N, *)` 的tensor，其中 :math:`*` 表示任意的附加维度。 - - **labels** (Tensor) - shape为 :math:`(N, *)` 的tensor，在通常情况下与 `logits` 的shape相同。但是如果 `logits` 和 `labels` 的shape不同，需要保证他们之间可以互相广播。 + - **logits** (Tensor) - 预测值，任意维度的Tensor。 + - **labels** (Tensor) - 目标值，通常情况下与 `logits` 的shape相同。但是如果 `logits` 和 `labels` 的shape不同，需要保证他们之间可以互相广播。 **输出：** - Tensor，为loss float tensor，如果 `reduction` 为'mean'或'sum'，则shape为零；如果 `reduction` 为'none'，则输出的shape为广播的shape。 + Tensor，类型为float。 **异常：** **ValueError** - `reduction` 不为"mean"、"sum"或"none"。 + **ValueError** - `logits` 和 `labels` 的shape不同，且不能互相广播。 **支持平台：** @@ -42,14 +43,14 @@ mindspore.nn.L1Loss **样例：** - >>> #用例1：logits.shape = labels.shape = (3,) + >>> # case1：logits.shape = labels.shape = (3,) >>> loss = nn.L1Loss() >>> logits = Tensor(np.array([1, 2, 3]), mindspore.float32) >>> labels = Tensor(np.array([1, 2, 2]), mindspore.float32) >>> output = loss(logits, labels) >>> print(output) 0.33333334 - >>> #用例2：logits.shape = (3,), labels.shape = (2, 3) + >>> # case2：logits.shape = (3,), labels.shape = (2, 3) >>> loss = nn.L1Loss(reduction='none') >>> logits = Tensor(np.array([1, 2, 3]), mindspore.float32) >>> labels = Tensor(np.array([[1, 1, 1], [1, 2, 2]]), mindspore.float32) diff --git a/docs/api/api_python/nn/mindspore.nn.leakyrelu.rst b/docs/api/api_python/nn/mindspore.nn.LeakyReLU.rst similarity index 53% rename from docs/api/api_python/nn/mindspore.nn.leakyrelu.rst rename to docs/api/api_python/nn/mindspore.nn.LeakyReLU.rst index d0dd8b06aa4..72cc29fc5eb 100644 --- a/docs/api/api_python/nn/mindspore.nn.leakyrelu.rst +++ b/docs/api/api_python/nn/mindspore.nn.LeakyReLU.rst @@ -5,12 +5,13 @@ mindspore.nn.LeakyReLU Leaky ReLU激活函数。 - LeakyReLU与ReLU相似，但LeakyReLU有一个斜率，使其在x<0时不等于0，该激活函数定义如下： + 该激活函数定义如下： .. math:: \text{leaky_relu}(x) = \begin{cases}x, &\text{if } x \geq 0; \cr - \text{alpha} * x, &\text{otherwise.}\end{cases} + {\alpha} * x, &\text{otherwise.}\end{cases} + 其中，:math:`\alpha` 表示 `alpha` 参数。 更多细节详见 `Rectifier Nonlinearities Improve Neural Network Acoustic Models `_。 @@ -20,11 +21,11 @@ mindspore.nn.LeakyReLU **输入：** - **x** （Tensor） - LeakyReLU的输入。shape为 :math:`(N, *)` ，其中 :math:`*` 表示任意的附加维度数。 + **x** （Tensor） - 计算LeakyReLU的任意维度的Tensor。 **输出：** - Tensor，shape和数据类型与 `x` 的相同。 + Tensor，数据类型和shape与 `x` 相同。 **异常：** @@ -36,9 +37,9 @@ mindspore.nn.LeakyReLU **样例：** - >>> x = Tensor(np.array([[-1.0, 4.0, -8.0], [2.0, -5.0, 9.0]]), mindspore.float32) - >>> leaky_relu = nn.LeakyReLU() - >>> output = leaky_relu(x) - >>> print(output) - [[-0.2 4. -1.6] - [ 2. -1. 9. ]] \ No newline at end of file + >>> x = Tensor(np.array([[-1.0, 4.0, -8.0], [2.0, -5.0, 9.0]]), mindspore.float32) + >>> leaky_relu = nn.LeakyReLU() + >>> output = leaky_relu(x) + >>> print(output) + [[-0.2 4. -1.6] + [ 2. -1. 9. ]] \ No newline at end of file diff --git a/docs/api/api_python/nn/mindspore.nn.Moments.rst b/docs/api/api_python/nn/mindspore.nn.Moments.rst index fdb5cbb5c55..d887dc0c64e 100644 --- a/docs/api/api_python/nn/mindspore.nn.Moments.rst +++ b/docs/api/api_python/nn/mindspore.nn.Moments.rst @@ -3,18 +3,16 @@ mindspore.nn.Moments .. py:class:: mindspore.nn.Moments(axis=None, keep_dims=None) - 计算 `x` 的均值和方差。 - - 均值和方差是通过聚合 `x` 在 `axis` 上的值来计算的。特别的，如果 `x` 是1-D的Tensor， `axis` 等于0，这相当于计算向量的均值和方差。 + 沿指定轴 `axis` 计算输入 `x` 的均值和方差。 **参数：** - - **axis** (Union[int, tuple(int), None]) - 沿指定 `axis` 计算均值和方差，值为None时代表计算 `x` 所有值的均值和方差。默认值：None。 - - **keep_dims** (Union[bool, None]) - 如果为True，计算结果会保留 `axis` 的维度，即均值和方差的维度与输入的相同。如果为False或None，则会消减 `axis` 的维度。默认值：None。 + - **axis** (Union[int, tuple(int), None]) - 沿指定轴 `axis` 计算均值和方差，值为None时代表计算 `x` 所有值的均值和方差。默认值：None。 + - **keep_dims** (Union[bool, None]) - 如果为True，计算结果会保留 `axis` 的维度，即均值和方差的维度与输入的相同。如果为False或None，则会降低 `axis` 的维度。默认值：None。 **输入：** - - **x** (Tensor) - 用于计算均值和方差的Tensor。数据类型仅支持float16和float32。shape为 :math:`(N,*)`， 其中 :math:`*` 表示任意的附加维度数。 + - **x** (Tensor) - 用于计算均值和方差的任意维度的Tensor。数据类型仅支持float16和float32。 **输出：** @@ -33,38 +31,37 @@ mindspore.nn.Moments **样例：** - >>> x = Tensor(np.array([[[[1, 2, 3, 4], [3, 4, 5, 6]]]]), mindspore.float32) + >>> # case1: axis = 0, keep_dims=True + >>> x = Tensor(np.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]]), mindspore.float32) >>> net = nn.Moments(axis=0, keep_dims=True) >>> output = net(x) >>> print(output) - (Tensor(shape=[1, 1, 2, 4], dtype=Float32, value= - [[[[ 1.00000000e+00, 2.00000000e+00, 3.00000000e+00, 4.00000000e+00], - [ 3.00000000e+00, 4.00000000e+00, 5.00000000e+00, 6.00000000e+00]]]]), - Tensor(shape=[1, 1, 2, 4], dtype=Float32, value= - [[[[ 0.00000000e+00, 0.00000000e+00, 0.00000000e+00, 0.00000000e+00], - [ 0.00000000e+00, 0.00000000e+00, 0.00000000e+00, 0.00000000e+00]]]])) + (Tensor(shape=[1, 2, 2], dtype=Float32, value= + [[[ 3.00000000e+00, 4.00000000e+00], + [ 5.00000000e+00, 6.00000000e+00]]]), Tensor(shape=[1, 2, 2], dtype=Float32, value= + [[[ 4.00000000e+00, 4.00000000e+00], + [ 4.00000000e+00, 4.00000000e+00]]])) + >>> # case2: axis = 1, keep_dims=True >>> net = nn.Moments(axis=1, keep_dims=True) >>> output = net(x) >>> print(output) - (Tensor(shape=[1, 1, 2, 4], dtype=Float32, value= - [[[[ 1.00000000e+00, 2.00000000e+00, 3.00000000e+00, 4.00000000e+00], - [ 3.00000000e+00, 4.00000000e+00, 5.00000000e+00, 6.00000000e+00]]]]), - Tensor(shape=[1, 1, 2, 4], dtype=Float32, value= - [[[[ 0.00000000e+00, 0.00000000e+00, 0.00000000e+00, 0.00000000e+00], - [ 0.00000000e+00, 0.00000000e+00, 0.00000000e+00, 0.00000000e+00]]]])) - >>> net = nn.Moments(axis=2, keep_dims=True) + (Tensor(shape=[2, 1, 2], dtype=Float32, value= + [[[ 2.00000000e+00, 3.00000000e+00]], + [[ 6.00000000e+00, 7.00000000e+00]]]), Tensor(shape=[2, 1, 2], dtype=Float32, value= + [[[ 1.00000000e+00, 1.00000000e+00]], + [[ 1.00000000e+00, 1.00000000e+00]]])) + >>> # case3: axis = 2, keep_dims=None(default) + >>> net = nn.Moments(axis=2) >>> output = net(x) >>> print(output) - (Tensor(shape=[1, 1, 1, 4], dtype=Float32, value= - [[[[ 2.00000000e+00, 3.00000000e+00, 4.00000000e+00, 5.00000000e+00]]]]), - Tensor(shape=[1, 1, 1, 4], dtype=Float32, value= - [[[[ 1.00000000e+00, 1.00000000e+00, 1.00000000e+00, 1.00000000e+00]]]])) - >>> net = nn.Moments(axis=3, keep_dims=True) + (Tensor(shape=[2, 2], dtype=Float32, value= + [[ 1.50000000e+00, 3.50000000e+00], + [ 5.50000000e+00, 7.50000000e+00]]), Tensor(shape=[2, 2], dtype=Float32, value= + [[ 2.50000000e-01, 2.50000000e-01], + [ 2.50000000e-01, 2.50000000e-01]])) + >>> # case4: axis = None(default), keep_dims=None(default) + >>> net = nn.Moments() >>> output = net(x) >>> print(output) - (Tensor(shape=[1, 1, 2, 1], dtype=Float32, value= - [[[[ 2.50000000e+00], - [ 4.50000000e+00]]]]), Tensor(shape=[1, 1, 2, 1], dtype=Float32, value= - [[[[ 1.25000000e+00], - [ 1.25000000e+00]]]])) + (Tensor(shape=[], dtype=Float32, value= 4.5), Tensor(shape=[], dtype=Float32, value= 5.25)) \ No newline at end of file diff --git a/docs/api/api_python/nn/mindspore.nn.ReLU.rst b/docs/api/api_python/nn/mindspore.nn.ReLU.rst index 9ba02b13887..910da76d43d 100644 --- a/docs/api/api_python/nn/mindspore.nn.ReLU.rst +++ b/docs/api/api_python/nn/mindspore.nn.ReLU.rst @@ -5,7 +5,7 @@ mindspore.nn.ReLU 修正线性单元激活函数（Rectified Linear Unit activation function）。 - 按元素返回 :math:`\max(x,\ 0)` 。特别说明，负数输出值会被修改为0，正数输出不受影响。 + 逐元素求 :math:`\max(x,\ 0)` 。特别说明，负数输出值会被修改为0，正数输出不受影响。 .. math:: @@ -15,15 +15,15 @@ mindspore.nn.ReLU **输入：** - - **x** (Tensor) - 用于计算ReLU的Tensor。数据类型为Number。shape为 :math:`(N,*)` ，其中 :math:`*` 表示任意的附加维度数。 + - **x** (Tensor) - 用于计算ReLU的任意维度的Tensor。数据类型为 `number `_。 **输出：** - Tensor，具有与 `x` 相同的数据类型和shape。 + Tensor，数据类型和shape与 `x` 相同。 **异常：** - - **TypeError** - `x` 的数据类型不是Number。 + - **TypeError** - `x` 的数据类型不是number。 **支持平台：** diff --git a/docs/api/api_python/nn/mindspore.nn.SmoothL1Loss.rst b/docs/api/api_python/nn/mindspore.nn.SmoothL1Loss.rst index 88e3a8d3789..064459861f7 100644 --- a/docs/api/api_python/nn/mindspore.nn.SmoothL1Loss.rst +++ b/docs/api/api_python/nn/mindspore.nn.SmoothL1Loss.rst @@ -3,38 +3,41 @@ mindspore.nn.SmoothL1Loss .. py:class:: mindspore.nn.SmoothL1Loss(beta=1.0) - 创建一个标准来计算loss函数，如果输入的绝对误差小于 `beta` 则用平方项，否则用绝对误差项。 + SmoothL1损失函数，如果预测值和目标值的逐个元素绝对误差小于设定阈值 `beta` 则用平方项，否则用绝对误差项。 - SmoothL1Loss可以看成 :class:`mindspore.nn.L1Loss` 的修改版本，也可以看成 :class:`mindspore.nn.L1Loss` 和 :class:`mindspore.ops.L2Loss` 的组合。 :class:`mindspore.nn.L1Loss` 计算两个输入Tensor之间的绝对误差，而 :class:`mindspore.ops.L2Loss` 计算两个输入Tensor之间的平方误差。 :class:`mindspore.ops.L2Loss` 通常更快收敛，但对离群值的鲁棒性较差。 - - 给定两个输入 :math:`x,\ y`，长度为 :math:`N`， unreduced SmoothL1Loss定义如下： + 给定两个输入 :math:`x,\ y`，SmoothL1Loss定义如下： .. math:: L_{i} = \begin{cases} - \frac{0.5 (x_i - y_i)^{2}}{\text{beta}}, & \text{if } |x_i - y_i| < \text{beta} \\ - |x_i - y_i| - 0.5 \text{beta}, & \text{otherwise.} + \frac{0.5 (x_i - y_i)^{2}}{\beta}, & \text{if } |x_i - y_i| < {\beta} \\ + |x_i - y_i| - 0.5 {\beta}, & \text{otherwise.} \end{cases} - 其中， :math:`\text{beta}` 控制loss函数从二次变为线性。 默认值为1.0。 :math:`N` 为batch size。该函数返回一个unreduced loss Tensor。 + 其中，:math:`{\beta}` 代表阈值 `beta` 。 + + .. note:: + SmoothL1Loss可以看成 :class:`mindspore.nn.L1Loss` 的修改版本，也可以看成 :class:`mindspore.nn.L1Loss` 和 :class:`mindspore.ops.L2Loss` 的组合。 :class:`mindspore.nn.L1Loss` 计算两个输入Tensor之间的绝对误差，而 :class:`mindspore.ops.L2Loss` 计算两个输入Tensor之间的平方误差。 :class:`mindspore.ops.L2Loss` 通常更快收敛，但对离群值的鲁棒性较差。该损失函数具有较好的鲁棒性。 **参数：** - **beta** (float) - 用于控制loss函数从二次变为线性的参数。默认值：1.0。 + **beta** (float) - 损失函数计算在L1Loss和L2Loss间变换的阈值。默认值：1.0。 **输入：** - - **logits** (Tensor) - 预测值，shape为 :math:`(N, *)` 的Tensor，其中 :math:`*` 表示任意的附加维度数。数据类型必须为float16或float32。 - - **labels** (Tensor) - 目标值，shape为 :math:`(N, *)` 的Tensor，数据类型和shape与 `logits` 相同。 + - **logits** (Tensor) - 预测值，任意维度Tensor。数据类型必须为float16或float32。 + - **labels** (Tensor) - 目标值，数据类型和shape与 `logits` 相同的Tensor。 **输出：** - Tensor，shape和数据类型与 `logits` 相同。 + Tensor，数据类型和shape与 `logits` 相同。 **异常：** - **TypeError** - `beta` 不是float。 + - **TypeError** - `logits` 或 `labels` 不是Tensor。 - **TypeError** - `logits` 或 `labels` 的数据类型既不是float16，也不是float32。 + - **TypeError** - `logits` 或 `labels` 的数据类型不相同。 - **ValueError** - `beta` 小于或等于0。 - **ValueError** - `logits` 的shape与 `labels` 不同。 diff --git a/docs/api/api_python/nn/mindspore.nn.Softmax.rst b/docs/api/api_python/nn/mindspore.nn.Softmax.rst index 3e06f462bce..084ea4d75b7 100644 --- a/docs/api/api_python/nn/mindspore.nn.Softmax.rst +++ b/docs/api/api_python/nn/mindspore.nn.Softmax.rst @@ -3,22 +3,20 @@ mindspore.nn.Softmax .. py:class:: mindspore.nn.Softmax(axis=-1) - Softmax激活函数。 + Softmax函数，它是二分类函数 :class:`mindspore.nn.Sigmoid` 在多分类上的推广，目的是将多分类的结果以概率的形式展现出来。 - 计算n维输入Tensor的Softmax函数。 - - 对输入Tensor在 `axis` 上的元素计算其指数函数值，然后归一化到[0, 1]范围，总和为1。 + 对输入Tensor在轴 `axis` 上的元素计算其指数函数值，然后归一化到[0, 1]范围，总和为1。 Softmax定义为： .. math:: \text{softmax}(x_{i}) = \frac{\exp(x_i)}{\sum_{j=0}^{n-1}\exp(x_j)}, - 其中， :math:`x_{i}` 是输入Tensor在 `axis` 上的第 :math:`i` 个元素。 + 其中， :math:`x_{i}` 是输入Tensor在轴 `axis` 上的第 :math:`i` 个元素。 **参数：** - **axis** (Union[int, tuple[int]]) - 指定Softmax运算的axis，-1表示最后一个维度。默认值：-1。 + **axis** (Union[int, tuple[int]]) - 指定Softmax运算的轴axis，假设输入 `x` 的维度为x.ndim，则axis的范围为 `[-x.ndim, x.ndim)` ，-1表示最后一个维度。默认值：-1。 **输入：** @@ -26,7 +24,7 @@ mindspore.nn.Softmax **输出：** - Tensor，shape和数据类型与 `x` 相同，取值范围[0,1]。 + Tensor，数据类型和shape与 `x` 相同，取值范围为[0, 1]。 **异常：** @@ -41,9 +39,11 @@ mindspore.nn.Softmax **样例：** + >>> # axis = -1(default), and the sum of return value is 1.0. >>> x = Tensor(np.array([-1, -2, 0, 2, 1]), mindspore.float16) >>> softmax = nn.Softmax() >>> output = softmax(x) >>> print(output) [0.03168 0.01166 0.0861 0.636 0.2341 ] + >>> assert(1.0 == output.sum()) \ No newline at end of file diff --git a/docs/api/api_python/nn/mindspore.nn.Tril.rst b/docs/api/api_python/nn/mindspore.nn.Tril.rst index d055bf3d4c2..80ace5c44e7 100644 --- a/docs/api/api_python/nn/mindspore.nn.Tril.rst +++ b/docs/api/api_python/nn/mindspore.nn.Tril.rst @@ -3,20 +3,20 @@ mindspore.nn.Tril .. py:class:: mindspore.nn.Tril - 返回一个Tensor，其中第 `k` 个对角线以上的元素被置为零。 + 返回一个Tensor，指定主对角线以上的元素被置为零。 - 矩阵的下三角把矩阵分成对角线上和对角线下的元素。 + 将矩阵元素沿主对角线分为上三角和下三角（包含对角线）。 - 参数 `k` 控制着矩阵的对角线。如果 `k` 为0，则保留主对角线上和下面的所有元素。正值包括主对角线上方尽可能多的对角线，类似地，负值排除主对角线下方尽可能多的对角线。 + 参数 `k` 控制对角线的选择。若 `k` 为0，则沿主对角线分割并保留下三角所有元素。若 `k` 为正值，则沿主对角线向上选择对角线 `k` ，并保留下三角所有元素。若 `k` 为负值，则沿主对角线向下选择对角线 `k` ，并保留下三角所有元素。 **输入：** - - **x** (Tensor)：输入Tensor。数据类型为Number。shape为 :math:`(N,*)`，其中 :math:`*` 表示任意的附加维度数。 - - **k** (Int)：对角线的索引。默认值：0。 + - **x** (Tensor)：输入Tensor。数据类型为`number `_。 + - **k** (int)：对角线的索引。默认值：0。假设输入的矩阵的维度分别为d1，d2，则k的范围应在[-min(d1, d2)+1, min(d1, d2)-1]，超出该范围时输出值与输入 `x` 一致。 **输出：** - Tensor，shape和数据类型与 `x` 相同。 + Tensor，数据类型和shape与 `x` 相同。 **异常：** @@ -29,6 +29,7 @@ mindspore.nn.Tril **样例：** + >>> # case1: k = 0 >>> x = Tensor(np.array([[ 1, 2, 3, 4], ... [ 5, 6, 7, 8], ... [10, 11, 12, 13], @@ -40,6 +41,7 @@ mindspore.nn.Tril [ 5 6 0 0] [10 11 12 0] [14 15 16 17]] + >>> # case2: k = 1 >>> x = Tensor(np.array([[ 1, 2, 3, 4], ... [ 5, 6, 7, 8], ... [10, 11, 12, 13], @@ -51,6 +53,7 @@ mindspore.nn.Tril [ 5 6 7 0] [10 11 12 13] [14 15 16 17]] + >>> # case3: k = 2 >>> x = Tensor(np.array([[ 1, 2, 3, 4], ... [ 5, 6, 7, 8], ... [10, 11, 12, 13], @@ -62,6 +65,7 @@ mindspore.nn.Tril [ 5 6 7 8] [10 11 12 13] [14 15 16 17]] + >>> # case4: k = -1 >>> x = Tensor(np.array([[ 1, 2, 3, 4], ... [ 5, 6, 7, 8], ... [10, 11, 12, 13],