diff --git a/doc/fluid/api_cn/api_tree_cn.rst b/doc/fluid/api_cn/api_tree_cn.rst index 8ecb54b90632c9215ec2df9989f35b32f9755929..44e357bfc8dd9d8d5db80602e4795bab80d93ff4 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 2a3de92563fc77e44e372830f03f2405fc05104b..cedfe95fb87a30c2038e33484298affc4439c047 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 3d7928489a3288e0865dda6e89804d7e997d0d21..9c6c6fe948acb39b526261c9ef92b8eaf4b59858 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 e16af08e929a0efb68e1cfea3d7008779162dd1a..aa4b8184bd052c40723d1118868c69ef1e65fc4e 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 3452d4cf92e5d9e1501eeeb5403ffc0187c74652..619013d41ee2601a6b22ea153239f2a56294960e 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 0000000000000000000000000000000000000000..7e747678bd0c6dab3d0e2bfa6c078249fdc0cefb --- /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 0000000000000000000000000000000000000000..860068cbaf6259ccac54f619fdfbf3b48e3d3c87 --- /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 7df1247c2c4e891904f41f36becfbe73ce5cffe1..c12ac055bb88cb94f32f91554f72684a3852da70 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 0a3171d388c4068b84799447886f403f1de7be7d..43a9aad6d7d9f4d06a6cd3f544ed13af6428c1bd 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.]]