From 48049078dffb2937158172d9a3481a6c97554468 Mon Sep 17 00:00:00 2001 From: Li Fuchen Date: Fri, 8 May 2020 15:23:39 +0800 Subject: [PATCH] add cn doc of trace API & diag_embed API (#2039) * add cn doc of trace API * add cn doc of diag_embed API --- doc/fluid/api_cn/nn_cn/diag_embed_cn.rst | 74 +++++++++++++++++++++++- doc/fluid/api_cn/tensor_cn.rst | 3 +- doc/fluid/api_cn/tensor_cn/trace_cn.rst | 48 +++++++++++++++ 3 files changed, 122 insertions(+), 3 deletions(-) create mode 100644 doc/fluid/api_cn/tensor_cn/trace_cn.rst diff --git a/doc/fluid/api_cn/nn_cn/diag_embed_cn.rst b/doc/fluid/api_cn/nn_cn/diag_embed_cn.rst index d72fea585..bc3b5dbc8 100644 --- a/doc/fluid/api_cn/nn_cn/diag_embed_cn.rst +++ b/doc/fluid/api_cn/nn_cn/diag_embed_cn.rst @@ -1,3 +1,73 @@ -diag +.. _cn_api_functional_diag_embed: + +diag_embed ------------------------------- -**版本升级，文档正在开发中** + +.. py:function:: paddle.functional.diag_embed(input, offset=0, dim1=-2, dim2=-1): + + 该 OP 创建一个 Tensor，其在指定的 2D 平面（由 ``dim1`` 和 ``dim2`` 指定）上的对角线由输入 ``input`` 填充。 + 默认的，指定的 2D 平面由返回 Tensor 的最后两维组成。 + + 参数 ``offset`` 确定在指定的二维平面中填充对角线的位置： + + - 如果 offset = 0，则填充主对角线。 + - 如果 offset > 0，则填充主对角线右上的对角线。 + - 如果 offset < 0，则填充主对角线左下的对角线。 + +参数： + - **input** （Variable|numpy.ndarray）- 输入变量，至少为 1D 数组，支持数据类型为 float32，float64，int32，int64。 + - **offset** （int ，可选）- 从指定的二维平面中获取对角线的位置，默认值为 0，既主对角线。 + - **dim1** （int ， 可选）- 填充对角线的二维平面的第一维，默认值为 -2。 + - **dim2** （int ， 可选）- 填充对角线的二维平面的第二维，默认值为 -1。 + +返回： 指定二维平面填充了对角线的 Tensor。数据类型和输入数据类型一致。 + +返回类型： 变量（Variable） + +**代码示例** + +.. code-block:: python + + import paddle.nn.functional as F + import paddle.fluid.dygraph as dg + import numpy as np + + diag_embed = np.random.randn(2, 3).astype('float32') + # [[ 0.7545889 , -0.25074545, 0.5929117 ], + # [-0.6097662 , -0.01753256, 0.619769 ]] + with dg.guard(): + data1 = F.diag_embed(diag_embed) + data1.numpy() + # [[[ 0.7545889 , 0. , 0. ], + # [ 0. , -0.25074545, 0. ], + # [ 0. , 0. , 0.5929117 ]], + + # [[-0.6097662 , 0. , 0. ], + # [ 0. , -0.01753256, 0. ], + # [ 0. , 0. , 0.619769 ]]] + + data2 = F.diag_embed(diag_embed, offset=-1, dim1=0, dim2=2) + data2.numpy() + # [[[ 0. , 0. , 0. , 0. ], + # [ 0.7545889 , 0. , 0. , 0. ], + # [ 0. , -0.25074545, 0. , 0. ], + # [ 0. , 0. , 0.5929117 , 0. ]], + # + # [[ 0. , 0. , 0. , 0. ], + # [-0.6097662 , 0. , 0. , 0. ], + # [ 0. , -0.01753256, 0. , 0. ], + # [ 0. , 0. , 0.619769 , 0. ]]] + + data3 = F.diag_embed(diag_embed, offset=1, dim1=0, dim2=2) + data3.numpy() + # [[[ 0. , 0.7545889 , 0. , 0. ], + # [ 0. , -0.6097662 , 0. , 0. ]], + # + # [[ 0. , 0. , -0.25074545, 0. ], + # [ 0. , 0. , -0.01753256, 0. ]], + # + # [[ 0. , 0. , 0. , 0.5929117 ], + # [ 0. , 0. , 0. , 0.619769 ]], + # + # [[ 0. , 0. , 0. , 0. ], + # [ 0. , 0. , 0. , 0. ]]] diff --git a/doc/fluid/api_cn/tensor_cn.rst b/doc/fluid/api_cn/tensor_cn.rst index 4b9ab5106..05525b8f4 100644 --- a/doc/fluid/api_cn/tensor_cn.rst +++ b/doc/fluid/api_cn/tensor_cn.rst @@ -68,6 +68,7 @@ paddle.tensor tensor_cn/tanh_cn.rst tensor_cn/t_cn.rst tensor_cn/tensordot_cn.rst + tensor_cn/trace_cn.rst tensor_cn/transpose_cn.rst tensor_cn/tril_cn.rst tensor_cn/triu_cn.rst @@ -76,4 +77,4 @@ paddle.tensor tensor_cn/var_cn.rst tensor_cn/where_cn.rst tensor_cn/zeros_cn.rst - tensor_cn/zeros_like_cn.rst + tensor_cn/zeros_like_cn.rst \ No newline at end of file diff --git a/doc/fluid/api_cn/tensor_cn/trace_cn.rst b/doc/fluid/api_cn/tensor_cn/trace_cn.rst new file mode 100644 index 000000000..af92e6784 --- /dev/null +++ b/doc/fluid/api_cn/tensor_cn/trace_cn.rst @@ -0,0 +1,48 @@ +.. _cn_api_tensor_trace: + +trace +------------------------------- + +.. py:function:: paddle.trace(input, offset=0, dim1=0, dim2=1) + +该 OP 计算输入 Tensor 在指定平面上的对角线元素之和，并输出相应的计算结果。 + +如果输入是 2D Tensor，则返回对角线元素之和。 + +如果输入的维度大于 2D，则返回一个由对角线元素之和组成的数组，其中对角线从由 dim1 和 dim2 指定的二维平面中获得。默认由输入的前两维组成获得对角线的 2D 平面。 + +参数 ``offset`` 确定从指定的二维平面中获取对角线的位置： + + - 如果 offset = 0，则取主对角线。 + - 如果 offset > 0，则取主对角线右上的对角线。 + - 如果 offset < 0，则取主对角线左下的对角线。 + +参数： + - **input** （Variable）- 输入变量，至少为 2D 数组，支持数据类型为 float32，float64，int32，int64。 + - **offset** （int ，可选）- 从指定的二维平面中获取对角线的位置，默认值为 0，既主对角线。 + - **dim1** （int ， 可选）- 获取对角线的二维平面的第一维，默认值为 0。 + - **dim2** （int ， 可选）- 获取对角线的二维平面的第二维，默认值为 1。 + +返回： 指定二维平面的对角线元素之和。数据类型和输入数据类型一致。 + +返回类型： 变量（Variable） + +**代码示例** + +.. code-block:: python + + import paddle.tensor as tensor + import paddle.fluid.dygraph as dg + import numpy as np + + case1 = np.random.randn(2, 3).astype('float32') + case2 = np.random.randn(3, 10, 10).astype('float32') + case3 = np.random.randn(3, 10, 5, 10).astype('float32') + + with dg.guard(): + case1 = dg.to_variable(case1) + case2 = dg.to_variable(case2) + case3 = dg.to_variable(case3) + data1 = tensor.trace(case1) # data1.shape = [1] + data2 = tensor.trace(case2, offset=1, dim1=1, dim2=2) # data2.shape = [3] + data3 = tensor.trace(case3, offset=-3, dim1=1, dim2=-1) # data2.shape = [3, 5] -- GitLab