From 3170c5279b5ddc3bae201c5d8e570e2fd3947e7f Mon Sep 17 00:00:00 2001
From: chengmo <chengmo@baidu.com>
Date: Thu, 14 May 2020 12:08:09 +0800
Subject: [PATCH] cherry & add index_sample op cn doc

---
 doc/fluid/api/layers.rst                      |  1 +
 .../api_cn/layers_cn/index_sample_cn.rst      | 70 +++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 doc/fluid/api_cn/layers_cn/index_sample_cn.rst

diff --git a/doc/fluid/api/layers.rst b/doc/fluid/api/layers.rst
index 9244c5c11..7d437ee27 100644
--- a/doc/fluid/api/layers.rst
+++ b/doc/fluid/api/layers.rst
@@ -156,6 +156,7 @@ fluid.layers
     layers/image_resize_short.rst
     layers/increment.rst
     layers/index_select.rst
+    layers/index_sample.rst
     layers/inplace_abn.rst
     layers/instance_norm.rst
     layers/interpolate.rst
diff --git a/doc/fluid/api_cn/layers_cn/index_sample_cn.rst b/doc/fluid/api_cn/layers_cn/index_sample_cn.rst
new file mode 100644
index 000000000..bf6d693d2
--- /dev/null
+++ b/doc/fluid/api_cn/layers_cn/index_sample_cn.rst
@@ -0,0 +1,70 @@
+.. _cn_api_tensor_search_index_sample:
+
+index_sample
+-------------------------------
+
+.. py:function:: paddle.fluid.layers.index_sample(x, index)
+
+该OP实现对输入 ``x`` 中的元素进行批量抽样，取 ``index`` 指定的对应下标的元素，按index中出现的先后顺序组织，填充为一个新的张量。
+
+该OP中 ``x`` 与 ``index`` 都是 ``2-D`` 张量。 ``index`` 的第一维度与输入 ``x`` 的第一维度必须相同， ``index`` 的第二维度没有大小要求，可以重复索引相同下标元素。
+        
+**参数**：
+    - **x** （Variable）– 输入的二维张量，数据类型为 int32，int64，float32，float64。
+    - **index** （Variable）– 包含索引下标的二维张量。数据类型为 int32，int64。
+
+**返回**：
+    -**Variable** ，数据类型与输入 ``x`` 相同，维度与 ``index`` 相同。
+     
+**代码示例**：
+
+.. code-block:: python
+
+        import paddle
+        import paddle.fluid as fluid
+        import numpy as np
+
+        data = np.array([[1.0, 2.0, 3.0, 4.0],
+                            [5.0, 6.0, 7.0, 8.0],
+                            [9.0, 10.0, 11.0, 12.0]]).astype('float32')
+
+        data_index = np.array([[0, 1, 2],
+                                [1, 2, 3],
+                                [0, 0, 0]]).astype('int32')
+
+        target_data = np.array([[100, 200, 300, 400],
+                                [500, 600, 700, 800],
+                                [900, 1000, 1100, 1200]]).astype('int32')
+
+
+        with fluid.dygraph.guard():
+            x = fluid.dygraph.to_variable(data)
+            index = fluid.dygraph.to_variable(data_index)
+            target = fluid.dygraph.to_variable(target_data)
+
+            out_z1 = fluid.layers.index_sample(x, index)
+            print(out_z1.numpy())
+            #[[1. 2. 3.]
+            # [6. 7. 8.]
+            # [9. 9. 9.]]
+
+            # 巧妙用法：使用topk op产出的top元素的下标
+            # 在另一个tensor中索引对应位置的元素
+            top_value, top_index = fluid.layers.topk(x, k=2)
+            out_z2 = fluid.layers.index_sample(target, top_index)
+            print(top_value.numpy())
+            #[[ 4.  3.]
+            # [ 8.  7.]
+            # [12. 11.]]
+
+            print(top_index.numpy())
+            #[[3 2]
+            # [3 2]
+            # [3 2]]
+
+            print(out_z2.numpy())
+            #[[ 400  300]
+            # [ 800  700]
+            # [1200 1100]]
+
+
-- 
GitLab