From be5b298b320923622019a3c58b1b840f76880fec Mon Sep 17 00:00:00 2001 From: wangchaochaohu Date: Tue, 25 Aug 2020 09:56:16 +0800 Subject: [PATCH] refine the doc for gather_nd test=develop (#2468) --- doc/fluid/api/tensor/gather_nd.rst | 10 ++- doc/fluid/api_cn/layers_cn/gather_nd_cn.rst | 13 ++-- doc/fluid/api_cn/tensor_cn/gather_nd_cn.rst | 71 ++++++++++++++++++++- 3 files changed, 81 insertions(+), 13 deletions(-) diff --git a/doc/fluid/api/tensor/gather_nd.rst b/doc/fluid/api/tensor/gather_nd.rst index 8669e3ff9..93c95cb49 100644 --- a/doc/fluid/api/tensor/gather_nd.rst +++ b/doc/fluid/api/tensor/gather_nd.rst @@ -1,7 +1,11 @@ -.. _api_tensor_cn_gather_nd: +.. THIS FILE IS GENERATED BY `gen_doc.{py|sh}` + !DO NOT EDIT THIS FILE MANUALLY! + +.. _api_tensor_manipulation_gather_nd: gather_nd -------------------------------- -:doc_source: paddle.fluid.layers.gather_nd +---------- +.. autofunction:: paddle.tensor.manipulation.gather_nd + :noindex: diff --git a/doc/fluid/api_cn/layers_cn/gather_nd_cn.rst b/doc/fluid/api_cn/layers_cn/gather_nd_cn.rst index 6c810ad73..8a570ff2e 100644 --- a/doc/fluid/api_cn/layers_cn/gather_nd_cn.rst +++ b/doc/fluid/api_cn/layers_cn/gather_nd_cn.rst @@ -5,11 +5,6 @@ gather_nd .. py:function:: paddle.fluid.layers.gather_nd(input, index, name=None) -:alias_main: paddle.gather_nd -:alias: paddle.gather_nd,paddle.tensor.gather_nd,paddle.tensor.manipulation.gather_nd -:old_api: paddle.fluid.layers.gather_nd - - 该OP是 :code:`gather` 的高维推广，并且支持多轴同时索引。 :code:`index` 是一个K维度的张量，它可以认为是从 :code:`input` 中取K-1维张量，每一个元素是一个切片： @@ -56,18 +51,18 @@ gather_nd 参数： - - **input** (Variable) - 输入张量，数据类型可以是int32，int64，float32，float64, bool。 - - **index** (Variable) - 输入的索引张量，数据类型为非负int32或非负int64。它的维度 :code:`index.rank` 必须大于1，并且 :code:`index.shape[-1] <= input.rank` 。 - - **name** (string) - 该层的名字，默认值为None，表示会自动命名。 + - **input** (Tensor) - 输入Tensor，数据类型可以是int32，int64，float32，float64, bool。 + - **index** (Tensor) - 输入的索引Tensor，其数据类型为int32或者int64。它的维度 :code:`index.rank` 必须大于1，并且 :code:`index.shape[-1] <= input.rank` 。 + - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 返回：shape为index.shape[:-1] + input.shape[index.shape[-1]:]的Tensor|LoDTensor，数据类型与 :code:`input` 一致。 -返回类型：Variable **代码示例**： .. code-block:: python + import paddle import paddle.fluid as fluid x = fluid.layers.data(name='x', shape=[3, 4, 5], dtype='float32') index = fluid.layers.data(name='index', shape=[2, 2], dtype='int32') diff --git a/doc/fluid/api_cn/tensor_cn/gather_nd_cn.rst b/doc/fluid/api_cn/tensor_cn/gather_nd_cn.rst index 6a06e0724..8aa603b1e 100644 --- a/doc/fluid/api_cn/tensor_cn/gather_nd_cn.rst +++ b/doc/fluid/api_cn/tensor_cn/gather_nd_cn.rst @@ -2,6 +2,75 @@ gather_nd ------------------------------- -:doc_source: paddle.fluid.layers.gather_nd +.. py:function:: paddle.gather_nd(x, index, name=None) + + +该OP是 :code:`gather` 的高维推广，并且支持多轴同时索引。 :code:`index` 是一个K维度的张量，它可以认为是从 :code:`x` 中取K-1维张量，每一个元素是一个切片： + +.. math:: + output[(i_0, ..., i_{K-2})] = x[index[(i_0, ..., i_{K-2})]] + +显然， :code:`index.shape[-1] <= x.rank` 并且输出张量的维度是 :code:`index.shape[:-1] + x.shape[index.shape[-1]:]` 。 + +示例： + +:: + + 给定: + x = [[[ 0, 1, 2, 3], + [ 4, 5, 6, 7], + [ 8, 9, 10, 11]], + [[12, 13, 14, 15], + [16, 17, 18, 19], + [20, 21, 22, 23]]] + x.shape = (2, 3, 4) + + - 案例 1: + index = [[1]] + + gather_nd(x, index) + = [x[1, :, :]] + = [[12, 13, 14, 15], + [16, 17, 18, 19], + [20, 21, 22, 23]] + + - 案例 2: + + index = [[0,2]] + gather_nd(x, index) + = [x[0, 2, :]] + = [8, 9, 10, 11] + + - 案例 3: + + index = [[1, 2, 3]] + gather_nd(x, index) + = [x[1, 2, 3]] + = [23] + + +参数： + - **x** (Tensor) - 输入Tensor，数据类型可以是int32，int64，float32，float64, bool。 + - **index** (Tensor) - 输入的索引Tensor，其数据类型int32或者int64。它的维度 :code:`index.rank` 必须大于1，并且 :code:`index.shape[-1] <= x.rank` 。 + - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + +返回：shape为index.shape[:-1] + x.shape[index.shape[-1]:]的Tensor，数据类型与 :code:`x` 一致。 + + +**代码示例**： + +.. code-block:: python + + import paddle + import numpy as np + + paddle.disable_static() + np_x = np.array([[[1, 2], [3, 4], [5, 6]], + [[7, 8], [9, 10], [11, 12]]]) + np_index = [[0, 1]] + x = paddle.to_tensor(np_x) + index = paddle.to_tensor(np_index) + + output = paddle.gather_nd(x, index) #[[3, 4]] -- GitLab