add cn for set_default_dtype/get_default_dtype/scatter/matmul (#2473)

* add cn for set_default_dtype/get_default_dtype/scatter/matmul

doc/fluid/api_cn/api_tree_cn.rst

@@ -26,5 +26,6 @@ API接口
     regularizer_cn.rst
     transpiler_cn.rst
     unique_name_cn.rst
+    static_cn.rst
 
 

doc/fluid/api_cn/framework_cn/get_default_dtype_cn.rst

-get
+.. _cn_api_paddle_framework_get_default_dtype:
+
+get_default_dtype
 -------------------------------
-**版本升级，文档正在开发中**
+
+.. py:function:: paddle.get_default_dtype()
+
+
+得到当前全局的dtype。 该值初始是float32。
+
+
+参数:
+
+     无
+
+返回: string，这个全局dtype仅支持float16、float32、float64
+
+**代码示例**：
+
+.. code-block:: python
+
+    import paddle
+    paddle.get_default_dtype()

doc/fluid/api_cn/framework_cn/set_default_dtype_cn.rst

-set
+.. _cn_api_paddle_framework_set_default_dtype:
+
+set_default_dtype
 -------------------------------
-**版本升级，文档正在开发中**
+
+.. py:function:: paddle.set_default_dtype(d)
+
+
+设置默认的全局dtype。 默认的全局dtype最初是float32。
+
+
+参数:
+
+     - **d** (string|np.dtype) - 设为默认值的dtype。 它仅支持float16，float32和float64。
+
+返回: 无
+
+**代码示例**：
+
+.. code-block:: python
+
+    import paddle
+    paddle.set_default_dtype("float32")

doc/fluid/api_cn/index_cn.rst

@@ -126,3 +126,4 @@ Note。
     regularizer_cn.rst
     transpiler_cn.rst
     unique_name_cn.rst
+    static_cn.rst

doc/fluid/api_cn/paddle_cn/scatter_cn.rst

-.. _cn_api_paddle_cn_scatter:
-
 scatter
 -------------------------------
-:doc_source: paddle.fluid.layers.scatter
-
+:doc_source: paddle.tensor.scatter
\ No newline at end of file
-

doc/fluid/api_cn/static_cn.rst

+=======================
+paddle.static
+=======================
+
+
+
+
+..  toctree::
+    :maxdepth: 1
+
+    static_cn/data_cn.rst
+

doc/fluid/api_cn/static_cn/data_cn.rst

+.. _cn_api_static_cn_data:
+
+data
+-------------------------------
+
+
+.. py:function:: paddle.static.data(name, shape, dtype=None, lod_level=0)
+
+
+
+
+该OP会在全局block中创建变量（Variable），该全局变量可被计算图中的算子（operator）访问。该变量可作为占位符用于数据输入。例如用执行器（Executor）feed数据进该变量,当 ``dtype`` 为None时， ``dtype`` 将通过 ``padle.get_default_dtype()`` 获取全局类型。
+
+
+参数：
+    - **name** (str)- 被创建的变量的名字，具体用法请参见 :ref:`api_guide_Name` 。
+    - **shape** (list|tuple)- 声明维度信息的list或tuple。可以在某个维度上设置None或-1，以指示该维度可以是任何大小。例如，将可变batchsize设置为None或-1。
+    - **dtype** (np.dtype|str，可选)- 数据类型，支持bool，float16，float32，float64，int8，int16，int32，int64，uint8。默认值为None。当 ``dtype`` 为None时， ``dtype`` 将通过 ``padle.get_default_dtype()`` 获取全局类型。
+    - **lod_level** (int，可选)- LoDTensor变量的LoD level数，LoD level是PaddlePaddle的高级特性，一般任务中不会需要更改此默认值，关于LoD level的详细适用场景和用法请见 :ref:`cn_user_guide_lod_tensor` 。默认值为0。
+
+返回：全局变量，可进行数据访问
+
+返回类型：Variable
+
+**代码示例**：
+
+.. code-block:: python
+
+    import numpy as np
+    import paddle.fluid as fluid
+    import paddle
+    # Creates a variable with fixed size [3, 2, 1]
+    # User can only feed data of the same shape to x
+    # the dtype is not set, so it will set "float32" by
+    # paddle.get_default_dtype(). You can use paddle.get_default_dtype() to 
+    # change the global dtype
+    x = paddle.static.data(name='x', shape=[3, 2, 1])
+    # Creates a variable with changeable batch size -1.
+    # Users can feed data of any batch size into y,
+    # but size of each data sample has to be [2, 1]
+    y = paddle.static.data(name='y', shape=[-1, 2, 1], dtype='float32')
+    z = x + y
+    # In this example, we will feed x and y with np-ndarray "1"
+    # and fetch z, like implementing "1 + 1 = 2" in PaddlePaddle
+    feed_data = np.ones(shape=[3, 2, 1], dtype=np.float32)
+    exe = fluid.Executor(fluid.CPUPlace())
+    out = exe.run(fluid.default_main_program(),
+                  feed={
+                      'x': feed_data,
+                      'y': feed_data
+                  },
+                  fetch_list=[z.name])
+    # np-ndarray of shape=[3, 2, 1], dtype=float32, whose elements are 2
+    print(out)

doc/fluid/api_cn/tensor_cn/matmul_cn.rst

@@ -3,84 +3,91 @@
 matmul
 -------------------------------
 
-.. py:function:: paddle.matmul(x, y, transpose_x=False, transpose_y=False, alpha=1.0, name=None)
+.. py:function:: paddle.matmul(x, y, transpose_x=False, transpose_y=False, name=None)
 
-:alias_main: paddle.matmul
-:alias: paddle.matmul,paddle.tensor.matmul,paddle.tensor.linalg.matmul
+该op是计算两个Tensor的乘积，遵循完整的广播规则，关于广播规则，请参考 :ref:`use_guide_broadcasting` 。
+并且其行为与 ``numpy.matmul`` 一致。目前，输入张量的维数可以是任意数量， ``matmul``  可以用于
+实现 ``dot`` ， ``matmul`` 和 ``batchmatmul`` 。实际行为取决于输入 ``x`` 、输入 ``y`` 、 ``transpose_x`` ，
+``transpose_y`` 。具体如下：
 
+- 如果 ``transpose`` 为真，则对应 Tensor 的后两维会转置。如果Tensor的一维，则转置无效。假定 ``x`` 是一个 shape=[D] 的一维 Tensor，则 ``x`` 视为 [1, D]。然而， ``y`` 是一个shape=[D]的一维Tensor，则视为[D, 1]。
 
+乘法行为取决于 ``x`` 和 ``y`` 的尺寸。 具体如下：
 
-输入 ``x`` 和输入 ``y`` 矩阵相乘。
+- 如果两个张量均为一维，则获得点积结果。
 
-两个输入的形状可为任意维度，但当任一输入维度大于3时，两个输入的维度必须相等。
-实际的操作取决于 ``x`` 、 ``y`` 的维度和 ``transpose_x`` 、 ``transpose_y`` 的布尔值。具体如下：
+- 如果两个张量都是二维的，则获得矩阵与矩阵的乘积。
 
-- 如果 ``transpose`` 为真，则对应 Tensor 的后两维会转置。假定 ``x`` 是一个 shape=[D] 的一维 Tensor，则 ``x`` 非转置形状为 [1, D]，转置形状为 [D, 1]。转置之后的输入形状需满足矩阵乘法要求，即 `x_width` 与 `y_height` 相等。
+- 如果 ``x`` 是1维的，而 ``y`` 是2维的，则将1放在 ``x`` 维度之前，以进行矩阵乘法。矩阵相乘后，将删除前置尺寸。
 
-- 转置后，输入的两个 Tensor 维度将为 2-D 或 n-D，将根据下列规则矩阵相乘：
-    - 如果两个矩阵都是 2-D，则同普通矩阵一样进行矩阵相乘。
-    - 如果任意一个矩阵是 n-D，则将其视为带 batch 的二维矩阵乘法。
+- 如果 ``x`` 是2维的，而 ``y`` 是1维的，获得矩阵与向量的乘积。
 
-- 如果原始 Tensor x 或 y 的秩为 1 且未转置，则矩阵相乘后的前置或附加维度 1 将移除。
+- 如果两个输入至少为一维，且至少一个输入为N维（其中N> 2），则将获得批矩阵乘法。 如果第一个自变量是一维的，则将1放在其维度的前面，以便进行批量矩阵的乘法运算，然后将其删除。 如果第二个参数为一维，则将1附加到其维度后面，以实现成批矩阵倍数的目的，然后将其删除。 根据广播规则广播非矩阵维度（不包括最后两个维度）。 例如，如果输入 ``x`` 是（j，1，n，m）Tensor，另一个 ``y`` 是（k，m，p）Tensor，则out将是（j，k，n，p）张量。
 
-参数：
-    - **x** (Variable) : 输入变量，类型为 Tensor 或 LoDTensor，数据类型为float32， float64，GPU设备下支持float16。
-    - **y** (Variable) : 输入变量，类型为 Tensor 或 LoDTensor，数据类型为float32， float64，GPU设备下支持float16。
+参数
+:::::::::
+    - **x** (Tensor) : 输入变量，类型为 Tensor，数据类型为float32， float64。
+    - **y** (Tensor) : 输入变量，类型为 Tensor，数据类型为float32， float64。
     - **transpose_x** (bool，可选) : 相乘前是否转置 x，默认值为False。
     - **transpose_y** (bool，可选) : 相乘前是否转置 y，默认值为False。
-    - **alpha** (float，可选) : 输出比例，默认为 3.0。
     - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
 
 返回：
-    - Variable (Tensor / LoDTensor)，矩阵相乘后的结，数据类型和输入数据类型一致。
+:::::::::
 
-返回类型：
-    - Variable（变量）。
+    - Tensor，矩阵相乘后的结果，数据类型和输入数据类型一致。
 
-::
-
-    * 例 1:
-
-    x: [B, ..., M, K], y: [B, ..., K, N]
-    # paddle.matmul(x, y)  # out: [B, ..., M, N]
-
-    * 例 2:
-
-    x: [B, M, K], y: [B, K, N]
-    # paddle.matmul(x, y)  # out: [B, M, N]
-
-    * 例 3:
-
-    x: [B, M, K], y: [K, N]
-    # paddle.matmul(x, y)  # out: [B, M, N]
-
-    * 例 4:
-
-    x: [M, K], y: [K, N]
-    # paddle.matmul(x, y)  # out: [M, N]
-
-    * 例 5:
-
-    x: [B, M, K], y: [K]
-    # paddle.matmul(x, y)  # out: [B, M]
-
-    * 例 6:
-
-    x: [K], y: [K]
-    # paddle.matmul(x, y)  # out: [1]
-
-    * 例 7:
-
-    x: [M], y: [N]
-    # paddle.matmul(x, y, True, True)  # out: [M, N]
-
-
-**代码示例**：
+代码示例
+::::::::::
 
 .. code-block:: python
 
-    import paddle.fluid as fluid
-    x = fluid.data(name='x', shape=[2, 3], dtype='float32')
-    y = fluid.data(name='y', shape=[3, 2], dtype='float32')
-    out = paddle.matmul(x, y, True, True)
+    import paddle
+    import numpy as np
+    paddle.disable_static()
+
+    # vector * vector
+    x_data = np.random.random([10]).astype(np.float32)
+    y_data = np.random.random([10]).astype(np.float32)
+    x = paddle.to_tensor(x_data)
+    y = paddle.to_tensor(y_data)
+    z = paddle.matmul(x, y)
+    print(z.numpy().shape)
+    # [1]
+
+    # matrix * vector
+    x_data = np.random.random([10, 5]).astype(np.float32)
+    y_data = np.random.random([5]).astype(np.float32)
+    x = paddle.to_tensor(x_data)
+    y = paddle.to_tensor(y_data)
+    z = paddle.matmul(x, y)
+    print(z.numpy().shape)
+    # [10]
+
+    # batched matrix * broadcasted vector
+    x_data = np.random.random([10, 5, 2]).astype(np.float32)
+    y_data = np.random.random([2]).astype(np.float32)
+    x = paddle.to_tensor(x_data)
+    y = paddle.to_tensor(y_data)
+    z = paddle.matmul(x, y)
+    print(z.numpy().shape)
+    # [10, 5]
+
+    # batched matrix * batched matrix
+    x_data = np.random.random([10, 5, 2]).astype(np.float32)
+    y_data = np.random.random([10, 2, 5]).astype(np.float32)
+    x = paddle.to_tensor(x_data)
+    y = paddle.to_tensor(y_data)
+    z = paddle.matmul(x, y)
+    print(z.numpy().shape)
+    # [10, 5, 5]
+    
+    # batched matrix * broadcasted matrix
+    x_data = np.random.random([10, 1, 5, 2]).astype(np.float32)
+    y_data = np.random.random([1, 3, 2, 5]).astype(np.float32)
+    x = paddle.to_tensor(x_data)
+    y = paddle.to_tensor(y_data)
+    z = paddle.matmul(x, y)
+    print(z.numpy().shape)
+    # [10, 3, 5, 5]
 

doc/fluid/api_cn/tensor_cn/scatter_cn.rst

-.. _cn_api_tensor_cn_scatter:
+.. _cn_api_paddle_cn_scatter:
 
 scatter
 -------------------------------
-:doc_source: paddle.fluid.layers.scatter
+.. py:function:: paddle.scatter(x, index, updates, overwrite=True, name=None)
 
 
+通过基于 ``updates`` 来更新选定索引 ``index`` 上的输入来获得输出。具体行为如下：
+
+    .. code-block:: python
+    
+        import numpy as np
+        #input:
+        x = np.array([[1, 1], [2, 2], [3, 3]])
+        index = np.array([2, 1, 0, 1])
+        # shape of updates should be the same as x
+        # shape of updates with dim > 1 should be the same as input
+        updates = np.array([[1, 1], [2, 2], [3, 3], [4, 4]])
+        overwrite = False
+        # calculation:
+        if not overwrite:
+            for i in range(len(index)):
+                x[index[i]] = np.zeros((2))
+        for i in range(len(index)):
+            if (overwrite):
+                x[index[i]] = updates[i]
+            else:
+                x[index[i]] += updates[i]
+        # output:
+        out = np.array([[3, 3], [6, 6], [1, 1]])
+        out.shape # [3, 2]
+
+**Notice：**
+因为 ``updates`` 的应用顺序是不确定的，因此，如果索引 ``index`` 包含重复项，则输出将具有不确定性。
+
+
+参数：
+    - **x** (Tensor) - ndim> = 1的输入N-D张量。 数据类型可以是float32，float64。
+    - **index** （Tensor）- 一维Tensor。 数据类型可以是int32，int64。 ``index`` 的长度不能超过 ``updates`` 的长度，并且 ``index`` 中的值不能超过输入的长度。
+    - **updates** （Tensor）- 根据 ``index`` 使用 ``update`` 参数更新输入 ``x`` 。 形状应与输入 ``x`` 相同，并且dim>1的dim值应与输入 ``x`` 相同。
+    - **overwrite** （bool，可选）- 指定索引 ``index`` 相同时，更新输出的方式。如果为True，则使用覆盖模式更新相同索引的输出，如果为False，则使用累加模式更新相同索引的输出。默认值为True。
+    - **name** （str，可选）- 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。
+
+返回：Tensor，与x有相同形状和数据类型。
+
+
+**代码示例：**
+    .. code-block:: python
+        
+        import paddle
+        import numpy as np
+        paddle.disable_static()
+        x_data = np.array([[1, 1], [2, 2], [3, 3]]).astype(np.float32)
+        index_data = np.array([2, 1, 0, 1]).astype(np.int64)
+        updates_data = np.array([[1, 1], [2, 2], [3, 3], [4, 4]]).astype(np.float32)
+        
+        x = paddle.to_tensor(x_data)
+        index = paddle.to_tensor(index_data)
+        updates = paddle.to_tensor(updates_data)
+
+        output1 = paddle.scatter(x, index, updates, overwrite=False)
+        # [[3., 3.],
+        #  [6., 6.],
+        #  [1., 1.]]
+        output2 = paddle.scatter(x, index, updates, overwrite=True)
+        # CPU device:
+        # [[3., 3.],
+        #  [4., 4.],
+        #  [1., 1.]]
+        # GPU device maybe have two results because of the repeated numbers in index
+        # result 1:
+        # [[3., 3.],
+        #  [4., 4.],
+        #  [1., 1.]]
+        # result 2:
+        # [[3., 3.],
+        #  [2., 2.],
+        #  [1., 1.]]