From 83a83978f64b3cc0bbe971e0a4c79ced3c0f549e Mon Sep 17 00:00:00 2001 From: ShenLiang <1422485404@qq.com> Date: Thu, 27 Aug 2020 13:04:43 +0800 Subject: [PATCH] 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 | 1 + .../framework_cn/get_default_dtype_cn.rst | 24 +++- .../framework_cn/set_default_dtype_cn.rst | 24 +++- doc/fluid/api_cn/index_cn.rst | 1 + doc/fluid/api_cn/paddle_cn/scatter_cn.rst | 6 +- doc/fluid/api_cn/static_cn.rst | 12 ++ doc/fluid/api_cn/static_cn/data_cn.rst | 54 ++++++++ doc/fluid/api_cn/tensor_cn/matmul_cn.rst | 129 +++++++++--------- doc/fluid/api_cn/tensor_cn/scatter_cn.rst | 75 +++++++++- 9 files changed, 254 insertions(+), 72 deletions(-) create mode 100644 doc/fluid/api_cn/static_cn.rst create mode 100644 doc/fluid/api_cn/static_cn/data_cn.rst diff --git a/doc/fluid/api_cn/api_tree_cn.rst b/doc/fluid/api_cn/api_tree_cn.rst index 8ecb54b90..44e357bfc 100644 --- a/doc/fluid/api_cn/api_tree_cn.rst +++ b/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 diff --git a/doc/fluid/api_cn/framework_cn/get_default_dtype_cn.rst b/doc/fluid/api_cn/framework_cn/get_default_dtype_cn.rst index 2a3de9256..cedfe95fb 100644 --- a/doc/fluid/api_cn/framework_cn/get_default_dtype_cn.rst +++ b/doc/fluid/api_cn/framework_cn/get_default_dtype_cn.rst @@ -1,3 +1,23 @@ -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() diff --git a/doc/fluid/api_cn/framework_cn/set_default_dtype_cn.rst b/doc/fluid/api_cn/framework_cn/set_default_dtype_cn.rst index 3d7928489..9c6c6fe94 100644 --- a/doc/fluid/api_cn/framework_cn/set_default_dtype_cn.rst +++ b/doc/fluid/api_cn/framework_cn/set_default_dtype_cn.rst @@ -1,3 +1,23 @@ -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") diff --git a/doc/fluid/api_cn/index_cn.rst b/doc/fluid/api_cn/index_cn.rst index e16af08e9..aa4b8184b 100644 --- a/doc/fluid/api_cn/index_cn.rst +++ b/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 diff --git a/doc/fluid/api_cn/paddle_cn/scatter_cn.rst b/doc/fluid/api_cn/paddle_cn/scatter_cn.rst index 3452d4cf9..619013d41 100644 --- a/doc/fluid/api_cn/paddle_cn/scatter_cn.rst +++ b/doc/fluid/api_cn/paddle_cn/scatter_cn.rst @@ -1,7 +1,3 @@ -.. _cn_api_paddle_cn_scatter: - scatter ------------------------------- -:doc_source: paddle.fluid.layers.scatter - - +:doc_source: paddle.tensor.scatter \ No newline at end of file diff --git a/doc/fluid/api_cn/static_cn.rst b/doc/fluid/api_cn/static_cn.rst new file mode 100644 index 000000000..7e747678b --- /dev/null +++ b/doc/fluid/api_cn/static_cn.rst @@ -0,0 +1,12 @@ +======================= +paddle.static +======================= + + + + +.. toctree:: + :maxdepth: 1 + + static_cn/data_cn.rst + diff --git a/doc/fluid/api_cn/static_cn/data_cn.rst b/doc/fluid/api_cn/static_cn/data_cn.rst new file mode 100644 index 000000000..860068cba --- /dev/null +++ b/doc/fluid/api_cn/static_cn/data_cn.rst @@ -0,0 +1,54 @@ +.. _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) diff --git a/doc/fluid/api_cn/tensor_cn/matmul_cn.rst b/doc/fluid/api_cn/tensor_cn/matmul_cn.rst index 7df1247c2..c12ac055b 100644 --- a/doc/fluid/api_cn/tensor_cn/matmul_cn.rst +++ b/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] diff --git a/doc/fluid/api_cn/tensor_cn/scatter_cn.rst b/doc/fluid/api_cn/tensor_cn/scatter_cn.rst index 0a3171d38..43a9aad6d 100644 --- a/doc/fluid/api_cn/tensor_cn/scatter_cn.rst +++ b/doc/fluid/api_cn/tensor_cn/scatter_cn.rst @@ -1,7 +1,78 @@ -.. _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.]] -- GitLab