diff --git a/docs/api/paddle/abs_cn.rst b/docs/api/paddle/abs_cn.rst index 83fa2c88d48..73f4958f216 100644 --- a/docs/api/paddle/abs_cn.rst +++ b/docs/api/paddle/abs_cn.rst @@ -3,7 +3,7 @@ abs ------------------------------- -.. py:function:: paddle.abs(x, name=None) +.. py:function:: paddle.abs(x, name=None, *, out=None) @@ -15,9 +15,13 @@ abs 参数 ::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float16、float32、float64、complex64、complex128。 + - **x** (Tensor) - 输入的 Tensor，数据类型为：int32、int64、float16、float32、float64、complex64、complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: 输出 Tensor，与 ``x`` 维度相同、数据类型相同。 diff --git a/docs/api/paddle/addmv_cn.rst b/docs/api/paddle/addmv_cn.rst index 924d005eb91..b05f6bd573b 100644 --- a/docs/api/paddle/addmv_cn.rst +++ b/docs/api/paddle/addmv_cn.rst @@ -3,7 +3,7 @@ addmv ------------------------------- -.. py:function:: paddle.addmv(input, mat, vec, beta=1, alpha=1, name=None, *, out=None) +.. py:function:: paddle.addmv(input, mat, vec, beta=1, alpha=1, *, out=None) 执行矩阵 ``mat`` 和向量 ``vec`` 的矩阵-向量乘法，并将其加到输入 Tensor 上。 @@ -16,7 +16,6 @@ addmv - **vec** (Tensor) - 待乘的向量。 - **beta** (float，可选) - input 的乘数，默认值为 1。 - **alpha** (float，可选) - mat @ vec 的乘数，默认值为 1。 - - **name** (str，可选) - 操作名称，默认值为 None。 关键字参数 ::::::::: diff --git a/docs/api/paddle/addr_cn.rst b/docs/api/paddle/addr_cn.rst index e7d781d63ec..402d40606d7 100644 --- a/docs/api/paddle/addr_cn.rst +++ b/docs/api/paddle/addr_cn.rst @@ -3,7 +3,7 @@ addr ------------------------------- -.. py:function:: paddle.addr(input, vec1, vec2, beta=1, alpha=1, name=None, *, out=None) +.. py:function:: paddle.addr(input, vec1, vec2, beta=1, alpha=1, *, out=None) 执行向量 ``vec1`` 和向量 ``vec2`` 的外积，并将其加到输入矩阵上。 @@ -16,7 +16,6 @@ addr - **vec2** (Tensor) - 第二个向量。 - **beta** (float，可选) - input 的乘数，默认值为 1。 - **alpha** (float，可选) - 外积的乘数，默认值为 1。 - - **name** (str，可选) - 操作名称，默认值为 None。 关键字参数 ::::::::: diff --git a/docs/api/paddle/bitwise_left_shift_cn.rst b/docs/api/paddle/bitwise_left_shift_cn.rst index 7d92b7c5ac0..b4e71dcca15 100644 --- a/docs/api/paddle/bitwise_left_shift_cn.rst +++ b/docs/api/paddle/bitwise_left_shift_cn.rst @@ -3,7 +3,7 @@ bitwise_left_shift ------------------------------- -.. py:function:: paddle.bitwise_left_shift(x, y, is_arithmetic=True, out=None, name=None) +.. py:function:: paddle.bitwise_left_shift(x, y, is_arithmetic=True, name=None, *, out=None) 对 Tensor ``x`` 和 ``y`` 逐元素进行 ``按位算术(或逻辑)左移`` 运算。 @@ -45,15 +45,20 @@ bitwise_left_shift ``paddle.bitwise_left_shift`` 遵守 broadcasting，如您想了解更多，请参见 `Tensor 介绍`_ . .. _Tensor 介绍: ../../guides/beginner/tensor_cn.html#id7 + 参数 :::::::::::: - **x** （Tensor）- 输入的 N-D ``Tensor``，数据类型为：uint8，int8，int16，int32，int64。别名 ``input``。 - **y** （Tensor）- 输入的 N-D ``Tensor``，数据类型为：uint8，int8，int16，int32，int64。别名 ``other``。 - - **is_arithmetic** （bool） - 用于表明是否执行算术位移，True 表示算术位移，False 表示逻辑位移。默认值为 True，表示算术位移。 - - **out** （Tensor，可选）- 输出的结果 ``Tensor``，是与输入数据类型相同的 N-D ``Tensor``。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + - **is_arithmetic** （bool，可选） - 用于表明是否执行算术位移，True 表示算术位移，False 表示逻辑位移。默认值为 True，表示算术位移。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选）- 输出的结果 ``Tensor``，是与输入数据类型相同的 N-D ``Tensor``。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: diff --git a/docs/api/paddle/bitwise_right_shift_cn.rst b/docs/api/paddle/bitwise_right_shift_cn.rst index c76150d23f6..35db366c70e 100644 --- a/docs/api/paddle/bitwise_right_shift_cn.rst +++ b/docs/api/paddle/bitwise_right_shift_cn.rst @@ -3,7 +3,7 @@ bitwise_right_shift ------------------------------- -.. py:function:: paddle.bitwise_right_shift(x, y, is_arithmetic=True, out=None, name=None) +.. py:function:: paddle.bitwise_right_shift(x, y, is_arithmetic=True, name=None, *, out=None) 对 Tensor ``x`` 和 ``y`` 逐元素进行 ``按位算术(或逻辑)右移`` 运算。 @@ -14,15 +14,20 @@ bitwise_right_shift ``paddle.bitwise_right_shift`` 遵守 broadcasting，如您想了解更多，请参见 `Tensor 介绍`_ . .. _Tensor 介绍: ../../guides/beginner/tensor_cn.html#id7 + 参数 :::::::::::: - **x** （Tensor）- 输入的 N-D ``Tensor``，数据类型为：uint8，int8，int16，int32，int64。别名 ``input``。 - **y** （Tensor）- 输入的 N-D ``Tensor``，数据类型为：uint8，int8，int16，int32，int64。别名 ``other``。 - - **is_arithmetic** （bool） - 用于表明是否执行算术位移，True 表示算术位移，False 表示逻辑位移。默认值为 True，表示算术位移。 - - **out** （Tensor，可选）- 输出的结果 ``Tensor``，是与输入数据类型相同的 N-D ``Tensor``。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + - **is_arithmetic** （bool，可选） - 用于表明是否执行算术位移，True 表示算术位移，False 表示逻辑位移。默认值为 True，表示算术位移。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选）- 输出的结果 ``Tensor``，是与输入数据类型相同的 N-D ``Tensor``。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``按位算术(逻辑)右移`` 运算后的结果 ``Tensor``，数据类型与 ``x`` 相同。 diff --git a/docs/api/paddle/bmm_cn.rst b/docs/api/paddle/bmm_cn.rst index f982f6099d9..4b469e8ce60 100644 --- a/docs/api/paddle/bmm_cn.rst +++ b/docs/api/paddle/bmm_cn.rst @@ -3,7 +3,7 @@ bmm ------------------------------- -.. py:function:: paddle.bmm(x, y, name=None, *, out=None) +.. py:function:: paddle.bmm(x, y, out_dtype=None, name=None, *, out=None) @@ -17,8 +17,9 @@ bmm 参数 ::::::::: - - **x** (Tensor) - 输入变量，类型为 Tensor。别名 ``input``。 - - **y** (Tensor) - 输入变量，类型为 Tensor。别名 ``other``。 + - **x** (Tensor) - 第一个输入 Tensor。别名 ``input``。 + - **y** (Tensor) - 第二个输入 Tensor。别名 ``mat2``。 + - **out_dtype** (paddle.dtype|None，可选) - 输出的数据类型。目前仅支持在动态图中将 CUDA 上数据类型为 float16 或 bfloat16 的输入转换为 ``paddle.float32`` 输出，两个输入 Tensor 的数据类型必须相同。为保持向后兼容性，当恰好传入三个位置参数且第三个参数为字符串时，该参数会被视为 ``name``。如需以位置参数传入 ``out_dtype``，请使用 ``paddle.float32`` 等数据类型对象；若使用字符串数据类型，请通过 ``out_dtype="float32"`` 传入。当第 4 个位置参数提供 ``name`` 时，字符串数据类型也可作为第 3 个位置参数传入，例如 ``paddle.bmm(x, y, "float32", "my_name")``。默认值为 None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 @@ -28,7 +29,7 @@ bmm 返回 ::::::::: -Tensor，矩阵相乘后的结果。 +Tensor，批量矩阵相乘后的结果。未指定 ``out_dtype`` 时，输出的数据类型与输入相同。 代码示例 ::::::::: diff --git a/docs/api/paddle/bucketize_cn.rst b/docs/api/paddle/bucketize_cn.rst index 6edc06694fd..81e174e965e 100644 --- a/docs/api/paddle/bucketize_cn.rst +++ b/docs/api/paddle/bucketize_cn.rst @@ -3,18 +3,22 @@ bucketize ------------------------------- -.. py:function:: paddle.bucketize(x, sorted_sequence, out_int32=False, right=False, name=None) +.. py:function:: paddle.bucketize(x, sorted_sequence, out_int32=False, right=False, name=None, *, out=None) 将根据给定的一维 Tensor ``sorted_sequence`` 返回输入 ``x`` 对应的桶索引。 参数 :::::::::: - - **x** (Tensor) - 输入的 N 维 Tensor，支持的数据类型：int32、int64、float32、float64。 - - **sorted_sequence** (Tensor) - 输入的一维 Tensor，支持的数据类型：int32、int64、float32、float64。该 Tensor 的数值在其最后一个维度递增。 + - **x** (Tensor) - 输入的 N 维 Tensor，支持的数据类型：int32、int64、float32、float64。别名 ``input``。 + - **sorted_sequence** (Tensor) - 输入的一维 Tensor，支持的数据类型：int32、int64、float32、float64。该 Tensor 的数值在其最后一个维度递增。别名 ``boundaries``。 - **out_int32** (bool，可选) - 输出的数据类型支持 int32、int64。默认值为 False，表示默认的输出数据类型为 int64。 - **right** (bool，可选) - 根据给定 ``x`` 在 ``sorted_sequence`` 查找对应的上边界或下边界。如果 ``sorted_sequence`` 的值为 nan 或 inf，则返回最内层维度的大小。默认值为 False，表示在 ``sorted_sequence`` 的查找给定 ``x`` 的下边界。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::: Tensor(与 ``x`` 维度相同)，如果参数 ``out_int32`` 为 False，则返回数据类型为 int64 的 Tensor，否则将返回 int32 的 Tensor。 diff --git a/docs/api/paddle/ceil_cn.rst b/docs/api/paddle/ceil_cn.rst index 28d2d923e04..cc74d8e40f4 100644 --- a/docs/api/paddle/ceil_cn.rst +++ b/docs/api/paddle/ceil_cn.rst @@ -3,7 +3,7 @@ ceil ------------------------------- -.. py:function:: paddle.ceil(x, name=None) +.. py:function:: paddle.ceil(x, name=None, *, out=None) @@ -14,20 +14,19 @@ ceil out = \left \lceil x \right \rceil -.. note:: - 别名支持: 参数名 ``input`` 可替代 ``x``，如 ``input=tensor_x`` 等价于 ``x=tensor_x``。 - 参数 :::::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型支持 float32, float64, float16, bfloat16, uint8, int8, int16, int32, int64。 - 别名： ``input`` + - **x** (Tensor) - 输入的 Tensor，数据类型支持 float32, float64, float16, bfloat16, uint8, int8, int16, int32, int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **out** （Tensor，可选） - 指定输出结果的 ``Tensor``，默认值为 None。 + +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 返回 :::::::::::: -输出 Tensor，与 ``x`` 维度相同、数据类型相同。 +输出 Tensor，与 ``x`` 维度相同。若 ``x`` 为整数类型，则自动转换为 float32。 代码示例 :::::::::::: diff --git a/docs/api/paddle/column_stack_cn.rst b/docs/api/paddle/column_stack_cn.rst index 40b60db1f13..0cf5555d882 100644 --- a/docs/api/paddle/column_stack_cn.rst +++ b/docs/api/paddle/column_stack_cn.rst @@ -3,7 +3,7 @@ column_stack ------------------------------- -.. py:function:: paddle.column_stack(x, name=None) +.. py:function:: paddle.column_stack(x, name=None, *, out=None) 沿水平轴堆叠输入 ``x`` 中的所有张量。 ``x`` 中的每个张量 ``tensor`` 如果在堆叠之前 ``tensor.ndim < 2`` ，则首先被整形为 ``(tensor.numel(), 1)``。所有张量必须具有相同的数据类型。 @@ -16,9 +16,13 @@ column_stack 参数 :::::::::::: - - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。 + - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int8``、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。别名 ``tensors``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，与输入数据类型相同的堆叠张量。 diff --git a/docs/api/paddle/conj_cn.rst b/docs/api/paddle/conj_cn.rst index 368784e42d6..a31e0e7adef 100644 --- a/docs/api/paddle/conj_cn.rst +++ b/docs/api/paddle/conj_cn.rst @@ -3,7 +3,7 @@ conj ------------------------------- -.. py:function:: paddle.conj(x, name=None, *, out=None) +.. py:function:: paddle.conj(x, name=None) 是逐元素计算 Tensor 的共轭运算。 @@ -11,13 +11,9 @@ conj 参数 :::::::::::: - - **x** (Tensor) - 输入的复数值的 Tensor，数据类型为：complex64、complex128、bfloat16、float16、float32、float64、int32 或 int64。 + - **x** (Tensor) - 输入的复数值的 Tensor，数据类型为：complex64、complex128、bfloat16、float16、float32、float64、int32 或 int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 ``None``。 -关键字参数 -::::::::: - - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 - 返回 :::::::::::: diff --git a/docs/api/paddle/cumprod_cn.rst b/docs/api/paddle/cumprod_cn.rst index 28aea6a3ed1..cbad73d6a8f 100644 --- a/docs/api/paddle/cumprod_cn.rst +++ b/docs/api/paddle/cumprod_cn.rst @@ -3,7 +3,7 @@ cumprod ------------------------------- -.. py:function:: paddle.cumprod(x, dim=None, dtype=None, name=None) +.. py:function:: paddle.cumprod(x, dim=None, dtype=None, name=None, *, out=None) @@ -14,11 +14,15 @@ cumprod 参数 ::::::::: - - **x** (Tensor) - 累乘的输入，需要进行累乘操作的 tensor。 - - **dim** (int，可选) - 指明需要累乘的维度，取值范围需在[-x.rank,x.rank)之间，其中 x.rank 表示输入 tensor x 的维度，-1 代表最后一维。 + - **x** (Tensor) - 累乘的输入，需要进行累乘操作的 tensor。别名 ``input``。 + - **dim** (int，可选) - 指明需要累乘的维度，取值范围需在[-x.rank,x.rank)之间或为 None，其中 x.rank 表示输入 tensor x 的维度，-1 代表最后一维。默认值为 None，此时对展平后的数组计算累乘。 - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 tensor 的数据类型，支持 int32、int64、bfloat16、float16、float32、float64、complex64、complex128。如果指定了，那么在执行操作之前，输入的 tensor 将被转换为 dtype 类型。这对于防止数据类型溢出非常有用。默认为：None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: ``Tensor``，累乘操作的结果。 diff --git a/docs/api/paddle/distributed/DistModel_cn.rst b/docs/api/paddle/distributed/DistModel_cn.rst index 05975372d46..3e9b58650b7 100644 --- a/docs/api/paddle/distributed/DistModel_cn.rst +++ b/docs/api/paddle/distributed/DistModel_cn.rst @@ -3,7 +3,7 @@ DistModel ------------------------------- -.. py:class:: paddle.distributed.DistModel() +.. py:class:: paddle.distributed.DistModel(layer, loader, loss=None, optimizer=None, strategy=None, metrics=None, input_spec=None) .. note:: 不推荐直接使用这个 API 生成实例，建议使用 ``paddle.distributed.to_static``。 @@ -19,7 +19,7 @@ DistModel 通过自身的 ``__call__`` 方法来执行模型训练、评估和 - **layer** (paddle.nn.Layer) - 动态图中所使用的 ``paddle.nn.Layer`` 实例，其参数包含由 ``paddle.distributed.shard_tensor`` 生成的分布式张量。 - - **loader** (paddle.io.DataLoader) - 动态图模式下所使用的 ``paddle.io.DataLoader`` 实例，用于生成静态图训练所需要的 ``DistributedDataloader``。 + - **loader** (ShardDataloader|paddle.io.DataLoader) - 动态图模式下所使用的数据加载器，用于推断输入和标签的规格。 - **loss** (Loss|Callable|None，可选) - 损失函数。可以是 ``paddle.nn.Layer`` 实例或任何可调用函数。如果 loss 不为 None，则 DistModel 会默认设置为 "train"（当 optimizer 不为 None 时）或 "eval" 模式（当 optimizer 为 None 时）。如果 loss 为 None，则 DistModel 会默认设置为 "predict" 模式。默认值：None。 @@ -27,6 +27,10 @@ DistModel 通过自身的 ``__call__`` 方法来执行模型训练、评估和 - **strategy** (paddle.distributed.Strategy|None，可选) - 并行策略和优化策略的配置（例如优化器分片、流水线并行等）。默认值：None。 + - **metrics** (list[Metric]|None，可选) - 评估指标列表。默认值为 None。 + + - **input_spec** (list[list[paddle.distributed.DistributedInputSpec]]|None，可选) - 自定义输入规格，指定模型输入和标签的形状、数据类型及名称信息。非 None 时，由该参数推断输入和标签规格；其应包含两个子列表，第一个表示输入规格，第二个表示标签规格。默认值为 None。 + **代码示例** @@ -104,7 +108,7 @@ serial_startup_program(mode=None) **参数** - - **mode** (str|None，可选) - 指定需要返回的 ``startup_program`` 的模式，可以是 "train "、"eval" 或 "predict"，如果未设置，则使用 DistModel 的当前模式。默认值：None。 + - **mode** (str|None，可选) - 指定需要返回的 ``startup_program`` 的模式，可以是 "train"、"eval" 或 "predict"，如果未设置，则使用 DistModel 的当前模式。默认值：None。 **返回** diff --git a/docs/api/paddle/distributed/LocalLayer_cn.rst b/docs/api/paddle/distributed/LocalLayer_cn.rst index 05bb0963e49..079576fc11e 100644 --- a/docs/api/paddle/distributed/LocalLayer_cn.rst +++ b/docs/api/paddle/distributed/LocalLayer_cn.rst @@ -3,7 +3,7 @@ LocalLayer ------------------------------- -.. py:class:: paddle.distributed.LocalLayer(out_dist_attrs) +.. py:class:: paddle.distributed.LocalLayer(out_dist_attrs, grad_dist_attrs) LocalLayer 用于在分布式训练中实现局部计算操作。在自动并行训练中，某些操作（如带 mask 的 loss 计算、MoE 相关计算等）需要在每张卡上独立进行局部计算，而不是直接在全局分布式张量上计算。LocalLayer 通过自动处理张量转换，使得用户可以像编写单卡代码一样实现这些局部操作。 @@ -15,6 +15,8 @@ LocalLayer 用于在分布式训练中实现局部计算操作。在自动并行 - ProcessMesh: 计算设备网格,定义计算资源的拓扑结构 - list[Placement]: 张量分布方式的列表,描述如何将局部计算结果转换回分布式张量 + - **grad_dist_attrs** (list[tuple[ProcessMesh, list[Placement]]]) - 指定梯度 Tensor 的分布策略。列表中的元组可为 None，此时对应梯度 Tensor 的分布属性与对应输入 Tensor 相同。 + **代码示例** .. code-block:: python @@ -24,8 +26,8 @@ LocalLayer 用于在分布式训练中实现局部计算操作。在自动并行 from paddle.distributed import Placement, ProcessMesh, LocalLayer class CustomLayer(dist.LocalLayer): - def __init__(self, out_dist_attrs): - super().__init__(out_dist_attrs) + def __init__(self, out_dist_attrs, grad_dist_attrs): + super().__init__(out_dist_attrs, grad_dist_attrs) self.local_result = paddle.to_tensor(0.0) def forward(self, x): mask = paddle.zeros_like(x) @@ -53,7 +55,7 @@ LocalLayer 用于在分布式训练中实现局部计算操作。在自动并行 [dist.Shard(0)] ) - custom_layer = CustomLayer(out_dist_attrs) + custom_layer = CustomLayer(out_dist_attrs, out_dist_attrs) output_dist = custom_layer(input_dist) local_value = custom_layer.local_result @@ -71,7 +73,7 @@ LocalLayer 用于在分布式训练中实现局部计算操作。在自动并行 ::::::::: __call__() -''''''''' +''''''''''' 执行局部计算的核心方法。该方法会: @@ -94,9 +96,11 @@ LocalLayer 可以用于但不限于以下场景： 1. 带 mask 的 loss 计算：需要在每张卡上独立计算 masked token 的 loss 2. MoE（混合专家模型）相关计算： - - aux_loss 计算：基于每张卡上专家分配到的局部 token 数进行计算 - - z_loss 计算：对每张卡上的 logits 独立计算 z_loss - - 张量 reshape 操作：在局部维度上进行 shape 变换 + + - aux_loss 计算：基于每张卡上专家分配到的局部 token 数进行计算 + - z_loss 计算：对每张卡上的 logits 独立计算 z_loss + - 张量 reshape 操作：在局部维度上进行 shape 变换 + 3. 其他需要保持局部计算语义的场景 **注意事项** diff --git a/docs/api/paddle/distributed/all_gather_object_cn.rst b/docs/api/paddle/distributed/all_gather_object_cn.rst index 6a36c57eba6..54dd4024396 100644 --- a/docs/api/paddle/distributed/all_gather_object_cn.rst +++ b/docs/api/paddle/distributed/all_gather_object_cn.rst @@ -14,8 +14,8 @@ all_gather_object 参数 ::::::::: - - **object_list** (List[Any]) - 用于保存聚合结果的列表。 - - **object** (Any) - 待聚合的对象。需要保证该对象是 picklable 的。 + - **object_list** (List[Any]) - 用于保存聚合结果的列表。可传入长度为 world_size、元素均为 ``None`` 的列表（PyTorch 风格），也可传入空列表（Paddle 兼容风格，此时该列表会被原地扩容）。 + - **obj** (Any) - 待聚合的对象。需要保证该对象是 picklable 的。 - **group** (Group，可选) - 执行该操作的进程组实例（通过 ``new_group`` 创建）。默认为 None，即使用全局默认进程组。 返回 diff --git a/docs/api/paddle/distributed/destroy_process_group_cn.rst b/docs/api/paddle/distributed/destroy_process_group_cn.rst index 17140d84d78..71764e50b0d 100644 --- a/docs/api/paddle/distributed/destroy_process_group_cn.rst +++ b/docs/api/paddle/distributed/destroy_process_group_cn.rst @@ -10,7 +10,7 @@ destroy_process_group 参数 ::::::::: - - group (ProcessGroup, 可选): 待销毁的通信组。所有通信组都会被销毁（包括默认的通信组），并且整个分布式环境也会回到未被初始化的状态。 + - **group** (Group，可选): 待销毁的通信组。未指定或指定全局默认通信组时，所有通信组（包括默认通信组）都会被销毁，整个分布式环境会回到未初始化状态；指定非全局通信组时，仅销毁该通信组。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/init_parallel_env_cn.rst b/docs/api/paddle/distributed/init_parallel_env_cn.rst index 495b2fa2803..40bbb8f4529 100644 --- a/docs/api/paddle/distributed/init_parallel_env_cn.rst +++ b/docs/api/paddle/distributed/init_parallel_env_cn.rst @@ -3,16 +3,21 @@ init_parallel_env ----------------- -.. py:function:: paddle.distributed.init_parallel_env() +.. py:function:: paddle.distributed.init_parallel_env(nccl_config=None) 初始化动态图模式下的并行训练环境。 .. note:: 目前同时初始化 ``NCCL`` 和 ``GLOO`` 上下文用于通信。 +参数 +::::::::: + + - **nccl_config** (NCCLConfig|None，可选) - NCCL 配置。默认值为 None。 + 返回 ::::::::: -无 +Group，初始化后的默认进程组实例 代码示例 ::::::::: diff --git a/docs/api/paddle/distributed/load_state_dict_cn.rst b/docs/api/paddle/distributed/load_state_dict_cn.rst index 2923a15e6ab..a60bd9e6114 100644 --- a/docs/api/paddle/distributed/load_state_dict_cn.rst +++ b/docs/api/paddle/distributed/load_state_dict_cn.rst @@ -2,20 +2,24 @@ load_state_dict ------------------------------- -.. py:function:: paddle.distributed.load_state_dict(state_dict, path, process_group=None, coordinator_rank=0, unique_id=None, offload=False, mw_name_compatibility=True) +.. py:function:: paddle.distributed.load_state_dict(state_dict, path, process_group=None, coordinator_rank=0, unique_id=None, offload=False, mw_name_compatibility=True, aoa_config=None, safetensors=False, worker_groups=None, comm_method="broadcast") 将指定路径的 checkpoint 加载到指定 state_dict 中。 参数 ::::::::: - - **state_dict** (dict[str, paddle.Tensor]): 要加载的 state_dict，使用原地加载方式。 + - **state_dict** (dict[str, paddle.Tensor|paddle.distributed.ShardedWeight]): 要加载的 state_dict，使用原地加载方式。 - **path** (str): checkpoint 文件所在目录。 - **process_group** (paddle.distributed.collective.Group，可选): 用于跨 rank 同步的 ProcessGroup。默认值为 None，表示使用包含所有卡的全局 process group。 - **coordinator_rank** (int，可选): 用于协调检查点的 Rank。默认值为 0，表示使用 Rank 0 作为协调检查点。 - **unique_id** (int，可选): checkpoint 的唯一 ID，用于区分不同版本的检查点。默认值为 None，使用指定路径最大值加载最新版本的检查点。 - **offload** (bool，可选): 是否 offload checkpoint 到 CPU。默认值为 False，表示不进行 offload。 - **mw_name_compatibility** (bool，可选): 是否兼容动态图与静态图半自动并行参数的命名。默认值为 True，表示兼容。 + - **aoa_config** (dict[str, list[str]]|None，可选): 用于修改参数的 AOA 配置。默认值为 None。 + - **safetensors** (bool，可选): 是否使用 safetensors 格式。默认值为 False。 + - **worker_groups** (list[paddle.distributed.collective.Group]|None，可选): 用于 Tensor 通信的通信组。提供多个通信组时会选择合适的组；为 None 时使用 process_group。默认值为 None。 + - **comm_method** (str，可选): 重分片的通信方式，可选 ``"send_recv"``、``"broadcast"``、``"multi_group_broadcast"``、``"grouped_send_recv"`` 或 ``"parallel_broadcast"``。默认值为 ``"broadcast"``。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/new_group_cn.rst b/docs/api/paddle/distributed/new_group_cn.rst index 5004d9aaab6..9dead41ea89 100644 --- a/docs/api/paddle/distributed/new_group_cn.rst +++ b/docs/api/paddle/distributed/new_group_cn.rst @@ -4,15 +4,18 @@ new_group ------------------------------- -.. py:function:: paddle.distributed.new_group(ranks=None, backend=None) +.. py:function:: paddle.distributed.new_group(ranks=None, backend=None, timeout=datetime.timedelta(seconds=1800), nccl_comm_init_option=0, nccl_config=None) 创建分布式通信组。 参数 ::::::::: - - **ranks** (list) - 用于新建通信组的全局 rank 列表 - - **backend** (str) - 用于新建通信组的后端支持，目前仅支持 nccl + - **ranks** (list，可选) - 用于新建通信组的全局 rank 列表。默认值为 None。 + - **backend** (str，可选) - 用于新建通信组的后端支持，目前仅支持 nccl。默认值为 None。 + - **timeout** (datetime.timedelta，可选) - 等待 store 相关选项的超时时间。默认值为 30 分钟。 + - **nccl_comm_init_option** (int，可选) - NCCL 通信器初始化选项。默认值为 0。 + - **nccl_config** (NCCLConfig|None，可选) - NCCL 配置。默认值为 None。 返回 diff --git a/docs/api/paddle/distributed/save_state_dict_cn.rst b/docs/api/paddle/distributed/save_state_dict_cn.rst index e41e209191b..30803c7d13f 100644 --- a/docs/api/paddle/distributed/save_state_dict_cn.rst +++ b/docs/api/paddle/distributed/save_state_dict_cn.rst @@ -1,20 +1,22 @@ -.. _cn_api_paddle_distributed_save_state_dict: + .. _cn_api_paddle_distributed_save_state_dict: save_state_dict ------------------------------- -.. py:function:: paddle.distributed.save_state_dict(state_dict, path, process_group=None, coordinator_rank=0, unique_id=None, async_save=False) +.. py:function:: paddle.distributed.save_state_dict(state_dict, path, process_group=None, coordinator_rank=0, unique_id=None, async_save=False, safetensors=False, save_replicas=False) 保存分布式训练的 state_dict 到指定路径。 参数 ::::::::: - - **state_dict** (dict[str, paddle.Tensor]): 要保存的 state_dict。 + - **state_dict** (dict[str, paddle.Tensor|paddle.distributed.ShardedWeight]): 要保存的 state_dict。 - **path** (str): checkpoint 文件所在目录。 - **process_group** (paddle.distributed.collective.Group，可选): 用于跨 rank 同步的 ProcessGroup。默认值为 None，表示使用包含所有卡的全局 process group。 - **coordinator_rank** (int，可选): 用于协调检查点的 Rank。默认值为 0，表示使用 Rank 0 作为协调检查点。 - - **unique_id** (int，可选): checkpoint 的唯一 ID，用于区分不同版本的检查点。默认值为 None，表示使用指定路径最大值加载最新版本的检查点。 + - **unique_id** (int，可选): checkpoint 的唯一 ID，用于区分不同版本的检查点。默认值为 None：首次保存时使用 0，之后在同一路径中每次调用时递增 1；指定的 ID 已存在时会覆盖对应 checkpoint。 - **async_save** (bool，可选): 是否异步保存 state_dict。默认值为 False，表示不使用异步保存。 + - **safetensors** (bool，可选): 是否使用 safetensors 格式保存。默认值为 False。 + - **save_replicas** (bool，可选): 是否保存所有 Tensor 副本（例如来自不同 rank 的副本），而非每个 Tensor 只保存一个去重后的副本。默认值为 False。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/scatter_object_list_cn.rst b/docs/api/paddle/distributed/scatter_object_list_cn.rst index 5e193abd6e9..430f0946966 100644 --- a/docs/api/paddle/distributed/scatter_object_list_cn.rst +++ b/docs/api/paddle/distributed/scatter_object_list_cn.rst @@ -4,7 +4,7 @@ scatter_object_list ------------------------------- -.. py:function:: paddle.distributed.scatter_object_list(out_object_list, in_object_list, src=0, group=None) +.. py:function:: paddle.distributed.scatter_object_list(out_object_list, in_object_list=None, src=0, group=None) 将一组来自指定进程的 picklable 对象分发到每个进程 过程与 ``scatter`` 类似，但可以传入自定义的 python 对象。 @@ -16,7 +16,7 @@ scatter_object_list ::::::::: - **out_object_list** (List[Any]) - 用于接收数据的 object 列表。 - **in_object_list** (List[Any]，可选) - 将被分发的 object 列表。默认为 None，因为 rank != src 的进程上的该参数将被忽略。 - - **src** (int，可选) - 目标进程的 rank，该进程的 object 列表将被分发到其他进程中。默认为 0，即分发 rank=0 的进程上的 object 列表。 + - **src** (int，可选) - 源进程的 rank，该进程的 object 列表将被分发到其他进程中。默认为 0，即分发 rank=0 的进程上的 object 列表。 - **group** (Group，可选) - 执行该操作的进程组实例（通过 ``new_group`` 创建）。默认为 None，即使用全局默认进程组。 返回 diff --git a/docs/api/paddle/distributed/shard_dataloader_cn.rst b/docs/api/paddle/distributed/shard_dataloader_cn.rst index 11146b22238..e5ee8cce03a 100644 --- a/docs/api/paddle/distributed/shard_dataloader_cn.rst +++ b/docs/api/paddle/distributed/shard_dataloader_cn.rst @@ -3,7 +3,7 @@ shard_dataloader ------------------------------- -.. py:function:: paddle.distributed.shard_dataloader(dataloader, meshes, input_keys=None, shard_dims=None, is_dataset_splitted=False) +.. py:function:: paddle.distributed.shard_dataloader(dataloader, meshes, input_keys=None, shard_dims=None, is_dataset_splitted=False, dense_tensor_idx=None) 将单卡视角的数据加载器转变为分布式视角，与普通的 dataloader 相比，其提供了两个能力： 1. 如果 dataloader 的 shard_dim 不为 None，则按 shard_dim 拆分 dataloader 以进行数据并行。 @@ -15,9 +15,10 @@ shard_dataloader - **dataloader** (paddle.io.DataLoader) - 单卡视角的 dataloader。 - **meshes** (ProcessMesh|list|tuple) - 切分 dataloader 使用的 mesh。可以是个 ProcessMesh 或者 list，如果是个 list，则表示不同的输入需要在不同的 mesh 上。 - - **input_keys** (list|tuple，可选) - 如果 dataloader 的迭代结果是一个张量字典，input_keys 是这个字典的键，标识哪个张量位于哪个 mesh 上，与 meshes 一一对应。默认值 None，表示 dataloader 的迭代结果不是 dict。 + - **input_keys** (list[str]|tuple[str]，可选) - 如果 dataloader 的迭代结果是一个张量字典，input_keys 是这个字典的键，标识哪个张量位于哪个 mesh 上，与 meshes 一一对应。默认值 None，表示 dataloader 的迭代结果不是 dict。 - **shard_dims** (str|int|list|tuple，可选) - 对 dataloader 进行分片的 mesh 维度。默认值 None，代表不切分 dataloader，通常使用数据并行的情况下，必须设置此参数。 - **is_dataset_splitted** (bool，可选) - 数据集是否已根据数据并行的 rank 进行了切分。默认值 False。 + - **dense_tensor_idx** (list，可选) - 成对的二维列表，指定 dataloader 输出中 dense Tensor 的索引。每对中的第一个元素指定 dataloader 返回的 dense Tensor，第二个元素指定如何切分该 Tensor：数值表示均匀切分，列表表示非均匀切分。默认值为 None，表示所有输出均为分布式 Tensor。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/shard_optimizer_cn.rst b/docs/api/paddle/distributed/shard_optimizer_cn.rst index c25215d3d16..4aba8a58cc8 100644 --- a/docs/api/paddle/distributed/shard_optimizer_cn.rst +++ b/docs/api/paddle/distributed/shard_optimizer_cn.rst @@ -3,7 +3,7 @@ shard_optimizer ------------------------------- -.. py:function:: paddle.distributed.shard_optimizer(optimizer, shard_fn=None) +.. py:function:: paddle.distributed.shard_optimizer(optimizer, shard_fn=None, gradient_accumulation_steps=1) 将单卡视角的优化器转变为分布式视角。可以通过指定 ``shard_fn`` 来定制化优化器状态的切分方式，否则会将参数的分布式信息传递给对应的优化器状态。 @@ -15,6 +15,7 @@ shard_optimizer - **optimizer** (paddle.optimizer.Optimizer) - 单卡视角的优化器。 - **shard_fn** (Callable，可选) - 用于切分优化器状态函数。如果没有指定，默认地我们将参数的分布式信息传递给对应的优化器状态。 + - **gradient_accumulation_steps** (int，可选) - 梯度累积步数。默认值为 1。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/shard_tensor_cn.rst b/docs/api/paddle/distributed/shard_tensor_cn.rst index a2e61acff26..d1c7f5cb514 100644 --- a/docs/api/paddle/distributed/shard_tensor_cn.rst +++ b/docs/api/paddle/distributed/shard_tensor_cn.rst @@ -3,7 +3,7 @@ shard_tensor ------------------------------- -.. py:function:: paddle.distributed.shard_tensor(data, mesh, placements, dtype=None, place=None, stop_gradient=True) +.. py:function:: paddle.distributed.shard_tensor(data, mesh, placements, dtype=None, place=None, stop_gradient=None) 通过已知的 ``data`` 来创建一个带有分布式信息的 Tensor，Tensor 类型为 ``paddle.Tensor``。 ``data`` 可以是 scalar，tuple，list，numpy\.ndarray，paddle\.Tensor。 @@ -19,8 +19,8 @@ shard_tensor - **placements** (list(Placement)) - 分布式 Tensor 的切分表示列表，描述 Tensor 在 mesh 上如何切分。 - **dtype** (str|paddle.dtype|np.dtype，可选) - 创建 Tensor 的数据类型，可以是 bool、float16、float32、float64、int8、int16、int32、int64、uint8、complex64、complex128。 默认值为 None，如果 ``data`` 为 python 浮点类型，则从 :ref:`cn_api_paddle_get_default_dtype` 获取类型，如果 ``data`` 为其他类型，则会自动推导类型。 - - **place** (CPUPlace|CUDAPinnedPlace|CUDAPlace，可选) - 创建 tensor 的设备位置，可以是 CPUPlace、CUDAPinnedPlace、CUDAPlace。默认值为 None，使用全局的 place。 - - **stop_gradient** (bool，可选) - 是否阻断 Autograd 的梯度传导。默认值为 True，此时不进行梯度传传导。 + - **place** (CPUPlace|CUDAPinnedPlace|CUDAPlace|str，可选) - 创建 Tensor 的设备位置，可以是 CPUPlace、CUDAPinnedPlace、CUDAPlace。默认值为 None，使用全局的 place。若为字符串，可为 ``"cpu"``、``"gpu:x"`` 或 ``"gpu_pinned"``，其中 ``x`` 为 GPU 的索引。 + - **stop_gradient** (bool|None，可选) - 是否阻断 Autograd 的梯度传导。默认值为 None。若为 None，当 ``data`` 具有 ``stop_gradient`` 属性时，返回 Tensor 的 ``stop_gradient`` 与其相同；否则为 True。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/spawn_cn.rst b/docs/api/paddle/distributed/spawn_cn.rst index 6a40feb5a60..c7c773bcb5e 100644 --- a/docs/api/paddle/distributed/spawn_cn.rst +++ b/docs/api/paddle/distributed/spawn_cn.rst @@ -13,11 +13,11 @@ spawn 参数 ::::::::: - **func** (function) - 由 ``spawn`` 方法启动的进程所调用的目标函数。该目标函数需要能够被 ``pickled`` (序列化)，所以目标函数必须定义为模块的一级函数，不能是内部子函数或者类方法。 - - **args** (tuple，可选) - 传入目标函数 ``func`` 的参数。 - - **nprocs** (int，可选) - 启动进程的数目。默认值为-1。当 ``nproc`` 为-1 时，模型执行时将会从环境变量中获取当前可用的所有设备进行使用：如果使用 GPU 执行任务，将会从环境变量 ``CUDA_VISIBLE_DEVICES`` 中获取当前所有可用的设备 ID；如果使用 XPU 执行任务，将会从环境变量 ``XPU_VISIBLE_DEVICES`` 中获取当前所有可用的设备 ID。 + - **args** (list|tuple，可选) - 传入目标函数 ``func`` 的参数。 + - **nprocs** (int，可选) - 启动进程的数目。默认值为-1。当 ``nprocs`` 为 -1 时，模型执行时将会从环境变量中获取当前可用的所有设备进行使用：如果使用 GPU 执行任务，将会从环境变量 ``CUDA_VISIBLE_DEVICES`` 中获取当前所有可用的设备 ID；如果使用 XPU 执行任务，将会从环境变量 ``XPU_VISIBLE_DEVICES`` 中获取当前所有可用的设备 ID。 - **join** (bool，可选) - 对所有启动的进程执行阻塞的 ``join``，等待进程执行结束。默认为 True。 - **daemon** (bool，可选) - 配置启动进程的 ``daemon`` 属性。默认为 False。 - - **options (dict，可选) - 其他初始化并行执行环境的配置选项。目前支持以下选项：(1) start_method (string) - 启动子进程的方法。进程的启动方法可以是 ``spawn`` ， ``fork`` , ``forkserver``。因为 CUDA 运行时环境不支持 ``fork`` 方法，当在子进程中使用 CUDA 时，需要使用 ``spawn`` 或者 ``forkserver`` 方法启动进程。默认方法为 ``spawn`` ； (2) gpus (string) - 指定训练使用的 GPU ID，例如 "0,1,2,3"，默认值为 None ； (3) xpus (string) - 指定训练使用的 XPU ID，例如 "0,1,2,3"，默认值为 None ； (4) ips (string) - 运行集群的节点（机器）IP，例如 "192.168.0.16,192.168.0.17"，默认值为 "127.0.0.1" 。 + - **options** (dict，可选) - 其他初始化并行执行环境的配置选项。目前支持以下选项：(1) start_method (string) - 启动子进程的方法。进程的启动方法可以是 ``spawn`` ， ``fork`` , ``forkserver``。因为 CUDA 运行时环境不支持 ``fork`` 方法，当在子进程中使用 CUDA 时，需要使用 ``spawn`` 或者 ``forkserver`` 方法启动进程。默认方法为 ``spawn`` ； (2) gpus (string) - 指定训练使用的 GPU ID，例如 "0,1,2,3"，默认值为 None ； (3) xpus (string) - 指定训练使用的 XPU ID，例如 "0,1,2,3"，默认值为 None ； (4) ips (string) - 运行集群的节点（机器）IP，例如 "192.168.0.16,192.168.0.17"，默认值为 "127.0.0.1" 。 返回 ::::::::: diff --git a/docs/api/paddle/distributed/to_distributed_cn.rst b/docs/api/paddle/distributed/to_distributed_cn.rst index 2b8da82d7fa..edc5bcf4f63 100644 --- a/docs/api/paddle/distributed/to_distributed_cn.rst +++ b/docs/api/paddle/distributed/to_distributed_cn.rst @@ -17,10 +17,12 @@ to_distributed - **model** (paddle.nn.Layer) - 单卡视角的模型，没有包含任何分布式代码。 - **optimizer** (paddle.optimizer.Optimizer) - 单卡视角的优化器，通过常规优化器 API 构造，如 ``paddle.optimizer.Adam``。 - - **dataloader** (paddle.io.DataLoader) - 单卡视角的数据加载器，通过常规方式沟通，如 ``paddle.io.Dataset`` 及 ``paddle.io.Sampler``, 无需使用 ``paddle.io.DistributedBatchSampler``。 + - **dataloader** (paddle.io.DataLoader) - 单卡视角的数据加载器，通过常规方式构造，如 ``paddle.io.Dataset`` 及 ``paddle.io.Sampler``, 无需使用 ``paddle.io.DistributedBatchSampler``。 + - **device_num** (int) - 每个节点或机器上的设备数量。 + - **node_num** (int|None，可选) - 节点或机器数量。默认值为 1。 - **config** (ToDistributedConfig，可选) - 可以用来配置 输入数据信息 和 是否使用序列并行。配置时使用数据类 ``paddle.distributed.auto_parallel.high_level_api.ToDistributedConfig`` 来完成。 - 配置 输入数据信息，是提供模型训练时最有可能输入数据的 shape、dtype 和 stop_gradient 信息，便于更快更准地自动选择最优的分布式策略。 + 配置 输入数据信息，是通过 ``list[paddle.static.InputSpec]`` 提供模型训练时最有可能输入数据的 shape、dtype 和 name 信息，便于更快更准地自动选择最优的分布式策略。 配置 是否使用序列并行，可以指定如果最优的分布式策略中包含模型并行时，是否要使用序列并行。 diff --git a/docs/api/paddle/distributed/to_static_cn.rst b/docs/api/paddle/distributed/to_static_cn.rst index 797a5e840cb..253cda97737 100644 --- a/docs/api/paddle/distributed/to_static_cn.rst +++ b/docs/api/paddle/distributed/to_static_cn.rst @@ -3,27 +3,26 @@ to_static ------------------------------- -.. py:function:: paddle.distributed.to_static(layer, loader, loss=None, optimizer=None, strategy=None) +.. py:function:: paddle.distributed.to_static(layer, loader=None, loss=None, optimizer=None, strategy=None, input_spec=None) -将带有分布式切分信息的动态图 ``layer`` 转换为静态图分布式模型，可在静态图模式下进行分布式训练；同时将动态图下所使用的数据迭代器 ``loader`` 转换为静态图分布式训练所使用的数据迭代器。 +将带有分布式切分信息的动态图 ``layer`` 转换为静态图分布式模型，可在静态图模式下进行分布式训练、评估和预测。 -``paddle.distributed.to_static`` 返回 ``DistModel`` 实例和 ``DistributedDataLoader`` 实例。 ``DistModel`` 实例包含了转换后的静态图模型，同时提供了训练、评估和预测的接口。 ``DistributedDataLoader`` 实例用于在静态图分布式训练中加载数据。 +``paddle.distributed.to_static`` 返回包含转换后静态图模型的 ``DistModel`` 实例，并提供训练、评估和预测接口。 参数 ::::::::: - **layer** (paddle.nn.Layer) - 带有分布式信息，可在动态图模式下进行分布式训练的模型。 - - **loader** (paddle.io.DataLoader) - 动态图训练时所使用的数据迭代器。 - - **loss** (Loss|Callable|None, 可选) - 损失函数。需要训练或者评估模型时，该参数必须设定。 - - **optimizer** (Optimizer|None, 可选) - 优化器。训练模型时，该参数必须设定。 - - **strategy** (Strategy|None, 可选) - 分布式训练的配置，用于设置混合精度训练、分布式优化策略等。 + - **loader** (ShardDataloader|paddle.io.DataLoader|None，可选) - 动态图模式下使用的数据加载器，用于推断 input_spec 和 label_spec。默认值为 None。 + - **loss** (Loss|Callable|None，可选) - 损失函数。需要训练或者评估模型时，该参数必须设定。 + - **optimizer** (Optimizer|_ShardOptimizer|None，可选) - 优化器。可以是 ``paddle.optimizer.Optimizer``，也可以是由 ``shard_optimizer`` 包装的 ``_ShardOptimizer``。训练模型时，该参数必须设定。 + - **strategy** (Strategy|None，可选) - 分布式训练的配置，用于设置混合精度训练、分布式优化策略等。 + - **input_spec** (list[list[paddle.distributed.DistributedInputSpec]]|None，可选) - 自定义输入规格，指定模型输入和标签的形状、数据类型及名称信息。非 None 时，由该参数推断输入和标签规格；其应包含两个子列表，第一个表示输入规格，第二个表示标签规格。默认值为 None。 返回 ::::::::: -DistModel: 用于静态图分布式训练的模型，通过 ``__call__`` 方法进行训练、评估和预测。需要执行训练、评估或预测时，需要先使用 ``DistModel`` 实例的 ``train()/eval()/predict()`` 方法将其转换为对应的模式。 ``DistModel`` 实例的默认模式会根据 ``paddle.distributed.to_static`` 的输入设置，当 ``loss`` 和 ``optimizer`` 均给定时，默认模式为 ``train``；当 ``optimizer`` 为空时，默认模式为 ``eval``；当 ``loss`` 和 ``optimizer`` 均为空时，默认模式为 ``predict``。 - -DistributedDataLoader: 用于静态图分布式训练的数据迭代器，和 ``paddle.io.DataLoader`` 用法一致。 +DistModel: 用于静态图分布式训练的模型，通过 ``__call__`` 方法进行训练、评估和预测。需要执行训练、评估或预测时，需要先使用 ``DistModel`` 实例的 ``train()/eval()/predict()`` 方法将其转换为对应的模式。``DistModel`` 实例的默认模式会根据 ``paddle.distributed.to_static`` 的输入设置：当 ``loss`` 和 ``optimizer`` 均给定时，默认模式为 ``train``；当 ``loss`` 非空且 ``optimizer`` 为空时，默认模式为 ``eval``；当 ``loss`` 为空时，默认模式为 ``predict``。 代码示例 diff --git a/docs/api/paddle/distribution/ExponentialFamily_cn.rst b/docs/api/paddle/distribution/ExponentialFamily_cn.rst index c59365bf14c..51208472899 100644 --- a/docs/api/paddle/distribution/ExponentialFamily_cn.rst +++ b/docs/api/paddle/distribution/ExponentialFamily_cn.rst @@ -3,7 +3,7 @@ ExponentialFamily ------------------------------- -.. py:class:: paddle.distribution.ExponentialFamily() +.. py:class:: paddle.distribution.ExponentialFamily(batch_shape=(), event_shape=(), validate_args=None) 指数型分布族的基类，继承 ``paddle.distribution.Distribution``。概率密度/质量函数满足下述 形式 @@ -13,6 +13,12 @@ ExponentialFamily f_{F}(x; \theta) = \exp(\langle t(x), \theta\rangle - F(\theta) + k(x)) 其中，:math:`\theta` 表示自然参数，:math:`t(x)` 表示充分统计量，:math:`F(\theta)` 为对数 -归一化函数。 +归一化函数，:math:`k(x)` 表示基测度（carrier measure）。 属于指数型分布族的概率分布列表参考 https://en.wikipedia.org/wiki/Exponential_family + +参数 +::::::::: + - **batch_shape** (Sequence[int]，可选) - 独立但不必同分布的采样所对应的形状，即一组分布的形状。默认值为 ``()``。 + - **event_shape** (Sequence[int]，可选) - 单次采样的形状，维度之间可以相关。对于标量分布，事件形状为 ``[]``；对于 n 维多元分布，事件形状为 ``[n]``。默认值为 ``()``。 + - **validate_args** (bool|None，可选) - 是否启用参数校验。默认值为 None，此时使用全局默认设置。 diff --git a/docs/api/paddle/distribution/LKJCholesky_cn.rst b/docs/api/paddle/distribution/LKJCholesky_cn.rst index 258149deaa7..190dbf62ea4 100644 --- a/docs/api/paddle/distribution/LKJCholesky_cn.rst +++ b/docs/api/paddle/distribution/LKJCholesky_cn.rst @@ -2,7 +2,8 @@ LKJCholesky ------------------------------- -.. py:class:: paddle.distribution.LKJCholesky(dim, concentration=1.0, sample_method = 'onion') + +.. py:class:: paddle.distribution.LKJCholesky(dim=2, concentration=1.0, sample_method='onion') @@ -17,14 +18,15 @@ LKJ 分布通常定义为对相关矩阵 :math:`\Omega` 的分布，其密度函 其中，:math:`\Omega` 是一个 :math:`n \times n` 的相关矩阵，:math:`\eta` 是分布的形状参数，:math:`|\Omega|` 是矩阵的行列式。参数 :math:`\eta` 调节矩阵元素的分布集中度。 -相关矩阵的下三角 Choleskey 因子的 LJK 分布支持两种 sample 方法：``onion`` 和 ``cvine``。 +相关矩阵的下三角 Cholesky 因子的 LKJ 分布支持两种 sample 方法：``onion`` 和 ``cvine``。 参数 :::::::::::: - **dim** (int) - 目标相关矩阵的维度。 - **concentration** (float|Tensor) - 集中参数，这个参数控制了生成的相关矩阵的分布，值必须大于 0。concentration 越大，生成的矩阵越接近单位矩阵。 - - **sample_method** (str) - 不同采样策略，可选项有：``onion`` 和 ``cvine``. 这两种 sample 方法都在 `Generating random correlation matrices based on vines and extended onion method `_ 中提出，并且在相关矩阵上提供相同的分布。但是它们在如何生成样本方面是不同的。默认为“onion”。 + - **sample_method** (str) - 不同采样策略，可选项有：``onion`` 和 ``cvine``。这两种 sample 方法都在 `Generating random correlation matrices based on vines and extended onion method `_ 中提出，并且在相关矩阵上提供相同的分布。但是它们在如何生成样本方面是不同的。默认为“onion”。 + 代码示例 :::::::::::: @@ -36,8 +38,8 @@ COPY-FROM: paddle.distribution.LKJCholesky log_prob(value) -''''''''' -卡方分布的对数概率密度函数。 +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +计算给定相关矩阵 Cholesky 因子在 LKJ 分布下的对数概率密度。 **参数** @@ -45,18 +47,18 @@ log_prob(value) **返回** - - **Tensor** - value 对应的对数概率密度。 + - **Tensor** - 给定相关矩阵 Cholesky 因子对应的对数概率密度。 -sample(shape=[]) -''''''''' +sample(sample_shape=[]) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 随机采样，生成指定维度的样本。 **参数** - - **shape** (Sequence[int]，可选) - 采样的样本维度。 + - **sample_shape** (Sequence[int]，可选) - 采样的样本维度。 **返回** - - **Tensor** - 指定维度的样本数据。数据类型为 float32。 + - **Tensor** - 指定维度的样本数据。数据类型与 ``concentration`` 相同。 diff --git a/docs/api/paddle/distribution/LogNormal_cn.rst b/docs/api/paddle/distribution/LogNormal_cn.rst index e722dd8afe9..f28f8a653c3 100644 --- a/docs/api/paddle/distribution/LogNormal_cn.rst +++ b/docs/api/paddle/distribution/LogNormal_cn.rst @@ -3,7 +3,7 @@ LogNormal ------------------------------- -.. py:class:: paddle.distribution.LogNormal(loc, scale, name=None) +.. py:class:: paddle.distribution.LogNormal(loc, scale) 对数正态分布 @@ -33,7 +33,7 @@ LogNormal 参数 :::::::::::: - - **loc** (int|float|list|tuple|numpy.ndarray|Tensor) - 基础正态分布的平均值。 + - **loc** (int|float|complex|list|tuple|numpy.ndarray|Tensor) - 基础正态分布的平均值。数据类型为 float32、float64、complex64 或 complex128。 - **scale** (int|float|list|tuple|numpy.ndarray|Tensor) - 基础正态分布的标准差。 代码示例 @@ -60,15 +60,14 @@ variance 方法 ::::::::: -sample(shape=[], seed=0) -''''''''' +sample(shape=[]) +'''''''''''''''''''''''''''''''''''''''' 生成指定维度的样本。 **参数** - - **shape** (Sequence[int], 可选) - 指定生成样本的维度。 - - **seed** (int) - 长整型数。 + - **shape** (Sequence[int], 可选) - 指定生成样本的维度。别名 ``sample_shape``。 **返回** @@ -81,7 +80,7 @@ rsample(shape=[]) **参数** - - **shape** (Sequence[int], 可选) - 指定生成样本的维度。 + - **shape** (Sequence[int], 可选) - 指定生成样本的维度。别名 ``sample_shape``。 **返回** diff --git a/docs/api/paddle/div__cn.rst b/docs/api/paddle/div__cn.rst index 43d49fd89df..f519042f2db 100644 --- a/docs/api/paddle/div__cn.rst +++ b/docs/api/paddle/div__cn.rst @@ -3,6 +3,6 @@ div\_ ------------------------------- -.. py:function:: paddle.div_(x, y, name=None, *, rounding_mode=None, out=None) +.. py:function:: paddle.div_(x, y, name=None, *, rounding_mode=None) 别名函数，功能与 :ref:`cn_api_paddle_divide_` 完全相同，详情请参考 :ref:`cn_api_paddle_divide_` 。 diff --git a/docs/api/paddle/divide__cn.rst b/docs/api/paddle/divide__cn.rst index a2592c07ed6..f1600c3ad89 100644 --- a/docs/api/paddle/divide__cn.rst +++ b/docs/api/paddle/divide__cn.rst @@ -3,8 +3,8 @@ divide\_ ------------------------------- -.. py:function:: paddle.divide_(x, y, name=None, *, rounding_mode=None, out=None) -Inplace 版本的 :ref:`cn_api_paddle_divide` API，对输入 x 采用 Inplace 策略。 +.. py:function:: paddle.divide_(x, y, name=None, *, rounding_mode=None) +Inplace 版本的 :ref:`cn_api_paddle_divide` API，对输入 x 采用 Inplace 策略。参数 ``x`` 和 ``y`` 分别支持别名 ``input`` 和 ``other``。 更多关于 inplace 操作的介绍请参考 `3.1.3 原位（Inplace）操作和非原位操作的区别`_ 了解详情。 diff --git a/docs/api/paddle/dot_cn.rst b/docs/api/paddle/dot_cn.rst index 80013b35004..da1b4eb8366 100644 --- a/docs/api/paddle/dot_cn.rst +++ b/docs/api/paddle/dot_cn.rst @@ -3,7 +3,7 @@ dot ------------------------------- -.. py:function:: paddle.dot(x, y, name=None) +.. py:function:: paddle.dot(x, y, name=None, *, out=None) 计算向量的内积 @@ -13,7 +13,7 @@ dot 支持 1 维和 2 维 Tensor。如果是 2 维 Tensor，矩阵的第一个维度是 batch_size，将会在多个样本上进行点积计算。 .. note:: - 别名支持：参数名 ``input`` 可替代 ``x``， ``tensor`` 可替代 ``y``。 + 别名支持：参数名 ``input`` 可替代 ``x``， ``other`` 可替代 ``y``。 参数 ::::::::: @@ -21,7 +21,7 @@ dot - **x** （Tensor） - 1 维或 2 维 ``Tensor``。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 、 ``int64`` 、 ``complex64`` 或 ``complex128`` 。 别名： ``input`` - **y** （Tensor） - 1 维或 2 维 ``Tensor``。数据类型为 ``float32`` 、 ``float64`` 、 ``int32`` 、 ``int64`` 、 ``complex64`` 或 ``complex128`` 。 - 别名： ``tensor`` + 别名： ``other`` - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 diff --git a/docs/api/paddle/dstack_cn.rst b/docs/api/paddle/dstack_cn.rst index 5b458c360fc..cdb2daf49df 100644 --- a/docs/api/paddle/dstack_cn.rst +++ b/docs/api/paddle/dstack_cn.rst @@ -3,16 +3,20 @@ dstack ------------------------------- -.. py:function:: paddle.dstack(x, name=None) +.. py:function:: paddle.dstack(x, name=None, *, out=None) 沿深度轴堆叠输入 ``x`` 中的所有张量。所有张量必须具有相同的数据类型。 参数 :::::::::::: - - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。 + - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int8`` 、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。别名 ``tensors``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，与输入数据类型相同的堆叠张量。 diff --git a/docs/api/paddle/equal_cn.rst b/docs/api/paddle/equal_cn.rst index 39706a5969c..cd4e11ac62e 100644 --- a/docs/api/paddle/equal_cn.rst +++ b/docs/api/paddle/equal_cn.rst @@ -2,7 +2,7 @@ equal ------------------------------- -.. py:function:: paddle.equal(x, y, name=None) +.. py:function:: paddle.equal(x, y, name=None, *, out=None) 返回 :math:`x==y` 逐元素比较 x 和 y 是否相等，相同位置的元素相同则返回 True，否则返回 False。使用重载算子 ``==`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ equal 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出结果的 Tensor，输出 Tensor 的 shape 和输入一致，Tensor 数据类型为 bool。 diff --git a/docs/api/paddle/erf_cn.rst b/docs/api/paddle/erf_cn.rst index 49ed3033f29..0599f87b389 100644 --- a/docs/api/paddle/erf_cn.rst +++ b/docs/api/paddle/erf_cn.rst @@ -3,7 +3,7 @@ erf ------------------------------- -.. py:function:: paddle.erf(x, name=None) +.. py:function:: paddle.erf(x, name=None, *, out=None) 逐元素计算 Erf 激活函数。 @@ -18,6 +18,10 @@ erf - **x** (Tensor) - 输入 Tensor，数据类型为 float32、float64、uint8、int8、int16、int32、int64。别名: ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 ``None``。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: diff --git a/docs/api/paddle/erfinv__cn.rst b/docs/api/paddle/erfinv__cn.rst index 72295fa4198..31d30f29cea 100644 --- a/docs/api/paddle/erfinv__cn.rst +++ b/docs/api/paddle/erfinv__cn.rst @@ -3,7 +3,7 @@ erfinv\_ ------------------------------- -.. py:function:: paddle.erfinv_(x) +.. py:function:: paddle.erfinv_(x, name=None) Inplace 版本的 :ref:`cn_api_paddle_erfinv` API，对输入 ``x`` 采用 Inplace 策略。 diff --git a/docs/api/paddle/exp_cn.rst b/docs/api/paddle/exp_cn.rst index 375ae21b3e2..8ff1a8980dd 100644 --- a/docs/api/paddle/exp_cn.rst +++ b/docs/api/paddle/exp_cn.rst @@ -3,7 +3,7 @@ exp ------------------------------- -.. py:function:: paddle.exp(x, name=None) +.. py:function:: paddle.exp(x, name=None, *, out=None) @@ -16,9 +16,13 @@ exp 参数 :::::::::::: - - **x** (Tensor) - 该 OP 的输入为多维 Tensor。数据类型为 int32、int64、bfloat16、float16、float32、float64、complex64、complex128。 + - **x** (Tensor) - 该 OP 的输入为多维 Tensor。数据类型为 int32、int64、bfloat16、float16、float32、float64、complex64、complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出为 Tensor，与 ``x`` 维度相同、数据类型相同。 diff --git a/docs/api/paddle/expm1_cn.rst b/docs/api/paddle/expm1_cn.rst index a75876ce6dd..a18949c0219 100644 --- a/docs/api/paddle/expm1_cn.rst +++ b/docs/api/paddle/expm1_cn.rst @@ -3,7 +3,7 @@ expm1 ------------------------------- -.. py:function:: paddle.expm1(x, name=None) +.. py:function:: paddle.expm1(x, name=None, *, out=None) @@ -16,9 +16,13 @@ expm1 参数 ::::::::: - - **x** (Tensor) - 该 OP 的输入为多维 Tensor。数据类型为：int32、int64、bfloat16、float16、float32、float64、complex64、complex128。 + - **x** (Tensor) - 该 OP 的输入为多维 Tensor。数据类型为：int32、int64、bfloat16、float16、float32、float64、complex64、complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/fft/fft2_cn.rst b/docs/api/paddle/fft/fft2_cn.rst index d297cad6cc3..fa36dcae1f9 100644 --- a/docs/api/paddle/fft/fft2_cn.rst +++ b/docs/api/paddle/fft/fft2_cn.rst @@ -3,7 +3,7 @@ fft2 ------------------------------- -.. py:function:: paddle.fft.fft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.fft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 二维离散傅里叶变换。 @@ -13,13 +13,14 @@ fft2 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维傅里 叶变换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度大，则输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各 - 个轴的长度。 + 个轴的长度。默认为 None。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两个轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取 值必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应 的行为如下： @@ -32,6 +33,10 @@ fft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，形状和输入 Tensor 相同，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在 diff --git a/docs/api/paddle/fft/fft_cn.rst b/docs/api/paddle/fft/fft_cn.rst index f60692b5d05..7bf8e3f354f 100644 --- a/docs/api/paddle/fft/fft_cn.rst +++ b/docs/api/paddle/fft/fft_cn.rst @@ -3,7 +3,7 @@ fft ------------------------------- -.. py:function:: paddle.fft.fft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.fft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) 一维离散傅里叶变换。 @@ -12,9 +12,9 @@ fft 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。别名 ``input``。 - **n** (int，可选) - 输出 Tensor 中傅里叶变换轴的长度。如果 ``n`` 比输入 Tensor 中对应轴的长度小，输入数据会被截断。如果 ``n`` 比输入 Tensor 中对应轴的长度大，则输入会被补零。如果 ``n`` 没有被指定，则使用输入 Tensor 中由 ``axis`` 指定的轴的长度。 - - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取 值必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应 的行为如下： @@ -26,6 +26,10 @@ fft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/fft/fftfreq_cn.rst b/docs/api/paddle/fft/fftfreq_cn.rst index 6e0e914b6ce..b79cc5b937d 100644 --- a/docs/api/paddle/fft/fftfreq_cn.rst +++ b/docs/api/paddle/fft/fftfreq_cn.rst @@ -3,7 +3,7 @@ fftfreq ------------------------------- -.. py:function:: paddle.fft.fftfreq(n, d=1.0, dtype=None, name=None) +.. py:function:: paddle.fft.fftfreq(n, d=1.0, dtype=None, name=None, *, out=None, device=None, requires_grad=False) 返回离散傅里叶变换的频率窗口（frequency bins）中心序列，以 "循环/采样间隔" 为单位。例如，采 样间隔以秒为单位，则频率的单位是 "循环/秒"。 @@ -23,6 +23,12 @@ fftfreq - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。为 None 时，使用当前默认 Tensor 类型的当前设备。默认值为 None。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 ::::::::: diff --git a/docs/api/paddle/fft/fftn_cn.rst b/docs/api/paddle/fft/fftn_cn.rst index a06cd9eead1..9b6ca1fbcc1 100644 --- a/docs/api/paddle/fft/fftn_cn.rst +++ b/docs/api/paddle/fft/fftn_cn.rst @@ -3,7 +3,7 @@ fftn ------------------------------- -.. py:function:: paddle.fft.fftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.fftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) 计算 N 维离散傅里叶变换。 @@ -12,7 +12,7 @@ fftn 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型可以为实数或复数。 + - **x** (Tensor) - 输入数据，其数据类型可以为实数或复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维傅里 叶变换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 @@ -20,6 +20,7 @@ fftn 个轴的长度。 - **axes** (Sequence[int]，可选) - 计算快速傅里叶变换的轴。如果没有指定，默认是使用最后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入 Tensor 的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 指定傅里叶变换的缩放模式，缩放系数由变换的方向和模式同时决定。取 值必须是 "forward", "backward", "ortho"之一，默认值为 "backward"。三种缩放模式对应 的行为如下： @@ -32,6 +33,10 @@ fftn - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: 输入数据（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出，数据类型为复数类型。 diff --git a/docs/api/paddle/fft/hfft2_cn.rst b/docs/api/paddle/fft/hfft2_cn.rst index 8f2190f8699..437fa64c7f9 100644 --- a/docs/api/paddle/fft/hfft2_cn.rst +++ b/docs/api/paddle/fft/hfft2_cn.rst @@ -3,7 +3,7 @@ hfft2 ------------------------------- -.. py:function:: paddle.fft.hfft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.hfft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 通过快速傅里叶变换（FFT）算法计算二维厄米特(Hermitian)傅里叶变换。 @@ -11,10 +11,11 @@ hfft2 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数类型。 + - **x** (Tensor) - 输入数据，其数据类型为复数类型。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在傅里叶变换轴的长度（类似一维傅里叶变换中 的参数 ``n``）。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两个轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取 值必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应 的行为如下： @@ -27,6 +28,10 @@ hfft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输 diff --git a/docs/api/paddle/fft/hfft_cn.rst b/docs/api/paddle/fft/hfft_cn.rst index 57c949cb20f..2eee2abbb7a 100644 --- a/docs/api/paddle/fft/hfft_cn.rst +++ b/docs/api/paddle/fft/hfft_cn.rst @@ -4,7 +4,7 @@ hfft ------------------------------- -.. py:function:: paddle.fft.hfft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.hfft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) 通过快速傅里叶变换（FFT）算法计算一维厄米特（Hermitian）傅里叶变换。 @@ -12,9 +12,9 @@ hfft 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数。 + - **x** (Tensor) - 输入数据，其数据类型为复数。别名 ``input``。 - **n** (int，可选) - 输出 Tensor 在傅里叶变换轴的长度。输入 Tensor 在该轴的长度必须为 ``n//2+1``，如果输入 Tensor 的长度大于 ``n//2+1``，输入 Tensor 会被截断。如果输入 Tensor 的长度小于 ``n//2+1``，则输入 Tensor 会被补零。如果 ``n`` 没有被指定，则取 ``2*(m-1)``，其中, ``m`` 是输入 Tensor 在 ``axis`` 维的长度。 - - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认是使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认是使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必须是 "forward", "backward", "ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为如下： - "backward"：正向和逆向变换的缩放系数分别为 ``1`` 和 ``1/n``； @@ -24,6 +24,10 @@ hfft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。如果指定 ``n`` ，则输出 Tensor 在傅立叶变换轴的长度为 ``n`` ，否则为 ``2*(m-1)``，其中 ``m`` 是输入 Tensor 在 ``axis`` 维的长度。 diff --git a/docs/api/paddle/fft/hfftn_cn.rst b/docs/api/paddle/fft/hfftn_cn.rst index 2b1d1375713..63899d5bb78 100644 --- a/docs/api/paddle/fft/hfftn_cn.rst +++ b/docs/api/paddle/fft/hfftn_cn.rst @@ -3,7 +3,7 @@ hfftn ------------------------------- -.. py:function:: paddle.fft.hfftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.hfftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) 通过快速傅里叶变换（FFT）算法计算 N 维厄米特（Hermitian）傅里叶变换。 @@ -11,7 +11,7 @@ hfftn 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数类型。 + - **x** (Tensor) - 输入数据，其数据类型为复数类型。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维傅里 叶变换中的参数 ``n``）。对于傅里叶变换的最后一个轴，输入长度要求是 ``s[-1]//2+1``，如果 输入 Tensor 的长度大于 ``s[-1]//2+1``，输入 Tensor 会被截断。如果输入 Tensor 的长度 @@ -22,6 +22,7 @@ hfftn - **axes** (Sequence[int]，可选) - 计算快速傅里叶变换的轴。如果没有指定，默认是使用最 后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入数据的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 指定傅里叶变换的缩放模式，缩放系数由变换的方向和模式同时决定。取 值必须是 "forward"，"backward"，"ortho"之一，默认值为 "backward"。三种缩放模式对应的 行为如下： @@ -34,6 +35,10 @@ hfftn - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。输入数据（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。 diff --git a/docs/api/paddle/fft/ifft2_cn.rst b/docs/api/paddle/fft/ifft2_cn.rst index d51847292c7..4e0f47164ff 100644 --- a/docs/api/paddle/fft/ifft2_cn.rst +++ b/docs/api/paddle/fft/ifft2_cn.rst @@ -3,7 +3,7 @@ ifft2 ------------------------------- -.. py:function:: paddle.fft.ifft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.ifft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 二维傅里叶变换(``fft2``)的逆变换。在一定的误差范围内，``ifft2(fft2(x)) == x``。 @@ -11,13 +11,14 @@ ifft2 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维逆向傅 里叶变换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度大，则输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各 个轴的长度。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两维。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值 必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对 应的行为如下： @@ -30,6 +31,10 @@ ifft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，形状和输入 Tensor 相同，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在 diff --git a/docs/api/paddle/fft/ifft_cn.rst b/docs/api/paddle/fft/ifft_cn.rst index a1c11a45502..1121b1a677a 100644 --- a/docs/api/paddle/fft/ifft_cn.rst +++ b/docs/api/paddle/fft/ifft_cn.rst @@ -3,18 +3,18 @@ ifft ------------------------------- -.. py:function:: paddle.fft.ifft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.ifft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) 一维傅里叶变换（``fft``）的逆变换。在一定的误差范围内，``ifft(fft(x)) == x``。 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。别名 ``input``。 - **n** (int，可选) - 输出 Tensor 中在傅里叶变换轴的长度。如果 ``n`` 比输入 Tensor 中 对应轴的长度小，输入数据会被截断。如果 ``n`` 比输入 Tensor 中对应轴的长度大，则输入会被 补零。如果 ``n`` 没有被指定，则使用输入 Tensor 中由 ``axis`` 指定的轴的长度。 - - **axis** (int, 可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值 必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对 应的行为如下： @@ -25,6 +25,10 @@ ifft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，形状和输入 Tensor 相同，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在 diff --git a/docs/api/paddle/fft/ifftn_cn.rst b/docs/api/paddle/fft/ifftn_cn.rst index 5cca64b64b3..28da62fdf30 100644 --- a/docs/api/paddle/fft/ifftn_cn.rst +++ b/docs/api/paddle/fft/ifftn_cn.rst @@ -3,7 +3,7 @@ ifftn ------------------------------- -.. py:function:: paddle.fft.ifftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.ifftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) N 维离散傅里叶变换的逆变换。在一定的误差范围内，``ifftn(fftn(x)) == x``。 @@ -11,7 +11,7 @@ N 维离散傅里叶变换的逆变换。在一定的误差范围内，``ifftn(f 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数或复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维逆向傅 里叶变换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 @@ -19,6 +19,7 @@ N 维离散傅里叶变换的逆变换。在一定的误差范围内，``ifftn(f 个轴的长度。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认是使用最后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入 Tensor 的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值 必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对 应的行为如下： @@ -31,6 +32,10 @@ N 维离散傅里叶变换的逆变换。在一定的误差范围内，``ifftn(f - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，形状和输入 Tensor 相同，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在 diff --git a/docs/api/paddle/fft/ihfft2_cn.rst b/docs/api/paddle/fft/ihfft2_cn.rst index e9843fd9238..4613bf91ae5 100644 --- a/docs/api/paddle/fft/ihfft2_cn.rst +++ b/docs/api/paddle/fft/ihfft2_cn.rst @@ -3,7 +3,7 @@ ihfft2 ------------------------------- -.. py:function:: paddle.fft.ihfft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.ihfft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 二维厄米特（Hermitian）傅里叶变换的逆变换。 @@ -14,12 +14,13 @@ ihfft2 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数。别名 ``input``。 - **s** (Sequence[int]，可选) - 傅里叶变换轴的长度（类似一维傅里叶变 换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度大，则 输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各个轴的长度。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两个轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必 须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为 如下： @@ -32,6 +33,10 @@ ihfft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。 diff --git a/docs/api/paddle/fft/ihfft_cn.rst b/docs/api/paddle/fft/ihfft_cn.rst index 15ecbbda982..e617a0ef3a5 100644 --- a/docs/api/paddle/fft/ihfft_cn.rst +++ b/docs/api/paddle/fft/ihfft_cn.rst @@ -3,19 +3,19 @@ ihfft ------------------------------- -.. py:function:: paddle.fft.ihfft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.ihfft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) -使用快速傅里叶变（FFT）算法计算一维厄米特（Hermitian）傅里叶变换的逆变换。 +使用快速傅里叶变换（FFT）算法计算一维厄米特（Hermitian）傅里叶变换的逆变换。 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数。别名 ``input``。 - **n** (int，可选) - 傅里叶变换点数。如果 ``n`` 比输入 Tensor 中对应轴 的长度小，输入数据会被截断。如果 ``n`` 比输入 Tensor 中对应轴的长度大，则输入会被补零。如果 ``n`` 没有被指定，则使用输入 Tensor 中由 ``axis`` 指定的轴的长度。 - - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必 须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为 如下： @@ -27,6 +27,10 @@ ihfft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在指定 diff --git a/docs/api/paddle/fft/ihfftn_cn.rst b/docs/api/paddle/fft/ihfftn_cn.rst index 24077788865..c21ef94c1ea 100644 --- a/docs/api/paddle/fft/ihfftn_cn.rst +++ b/docs/api/paddle/fft/ihfftn_cn.rst @@ -3,7 +3,7 @@ ihfftn ------------------------------- -.. py:function:: paddle.fft.ihfftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.ihfftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) N 维厄米特（Hermitian）傅里叶变换的逆变换。 @@ -14,13 +14,14 @@ N 维厄米特（Hermitian）傅里叶变换的逆变换。 参数 ::::::::: - - **x** (Tensor) - 输入数据，数据类型为实数。 + - **x** (Tensor) - 输入数据，数据类型为实数。别名 ``input``。 - **s** (Sequence[int]，可选) - 傅里叶变换轴的长度（类似一维傅里叶变 换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度大，则 输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各个轴的长度。 - **axes** (Sequence[int]，可选) - 计算快速傅里叶变换的轴。如果没有指定，默认是使用最后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入数据的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 指定傅里叶变换的缩放模式，缩放系数由变换的方向和模式同时决定。取值必 须是 "forward"，"backward"，"ortho"之一，默认值为 "backward"。三种缩放模式对应的行为如下： @@ -32,6 +33,10 @@ N 维厄米特（Hermitian）傅里叶变换的逆变换。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，复数类型，输入数据（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。最后一个傅立 diff --git a/docs/api/paddle/fft/irfft2_cn.rst b/docs/api/paddle/fft/irfft2_cn.rst index 1ed7c3b8e41..bfeb60a717a 100644 --- a/docs/api/paddle/fft/irfft2_cn.rst +++ b/docs/api/paddle/fft/irfft2_cn.rst @@ -3,7 +3,7 @@ irfft2 ------------------------------- -.. py:function:: paddle.fft.irfft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.irfft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 通过快速傅里叶变换（FFT）算法计算二维实数傅里叶变换 （rfft2）的逆变换。 @@ -11,10 +11,11 @@ irfft2 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数。 + - **x** (Tensor) - 输入数据，其数据类型为复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在傅里叶变换轴的长度（类似一维傅里叶变换中 的参数 ``n``）。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两个轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取 值必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应 的行为如下： @@ -27,10 +28,14 @@ irfft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。 -二维厄米特傅里叶变换为 N 维厄米特傅里（``irfftn``）变换的特例。 +二维厄米特傅里叶变换为 N 维厄米特傅里叶变换（``irfftn``）变换的特例。 代码示例 ::::::::: diff --git a/docs/api/paddle/fft/irfft_cn.rst b/docs/api/paddle/fft/irfft_cn.rst index 3dab940e940..af4cd915c2c 100644 --- a/docs/api/paddle/fft/irfft_cn.rst +++ b/docs/api/paddle/fft/irfft_cn.rst @@ -4,7 +4,7 @@ irfft ------------------------------- -.. py:function:: paddle.fft.irfft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.irfft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) 通过快速傅里叶变换（FFT）算法计算一维实数傅里叶变换 （rfft）的逆变换。 @@ -12,9 +12,9 @@ irfft 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数。 + - **x** (Tensor) - 输入数据，其数据类型为复数。别名 ``input``。 - **n** (int，可选) - 输出 Tensor 在傅里叶变换轴的长度。输入 Tensor 在该轴的长度必须为 ``n//2+1`` ，如果输入 Tensor 的长度大于 ``n//2+1`` ，输入 Tensor 会被截断。如果输入 Tensor 的长度小于 ``n//2+1`` ，则输入 Tensor 会被补零。如果 ``n`` 没有被指定，则取 ``2*(m-1)`` ，其中， ``m`` 是输入 Tensor 在 ``axis`` 维的长度。 - - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认是使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认是使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必须是 "forward"、"backward"、"ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为如下： - "backward"：正向和逆向变换的缩放系数分别为 ``1`` 和 ``1/n`` ； @@ -24,6 +24,10 @@ irfft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。如果指定 ``n`` ，则输出 Tensor 在傅立叶变换轴的长度为 ``n`` ，否则为 ``2*(m-1)`` ，其中 ``m`` 是输入 Tensor 在 ``axis`` 维的长度。 diff --git a/docs/api/paddle/fft/irfftn_cn.rst b/docs/api/paddle/fft/irfftn_cn.rst index dc9bdfea57b..81c9ab72ec9 100644 --- a/docs/api/paddle/fft/irfftn_cn.rst +++ b/docs/api/paddle/fft/irfftn_cn.rst @@ -3,7 +3,7 @@ irfftn ------------------------------- -.. py:function:: paddle.fft.irfftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.irfftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) 通过快速傅里叶变换(FFT)算法计算 N 维实数傅里叶变换 （rfftn）的逆变换。 @@ -13,7 +13,7 @@ irfftn 参数 ::::::::: - - **x** (Tensor) - 输入数据，其数据类型为复数。 + - **x** (Tensor) - 输入数据，其数据类型为复数。别名 ``input``。 - **s** (Sequence[int]，可选) - 输出 Tensor 在每一个傅里叶变换轴上的长度（类似一维傅里叶变换中的参数 ``n``）。 - 对于傅里叶变换的最后一个轴，输入长度要求是 ``s[-1]//2+1``，如果输入 Tensor 的长度大于 ``s[-1]//2+1``，输入 Tensor 会被截断。如果输入 Tensor 的长度小于 ``s[-1]//2+1``，则输入 Tensor 会被补零； @@ -21,6 +21,7 @@ irfftn - 如果未指定 ``s``，则 ``s`` 在最后一个傅里叶变换轴取值为 ``2*(m-1)``，其中 ``m`` 是输入 Tensor 在最后一个傅里叶变换轴的长度，其余轴为输入 Tensor 在该轴的长度。 - **axes** (Sequence[int]，可选) - 计算快速傅里叶变换的轴。如果没有指定，默认是使用最后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入数据的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 指定傅里叶变换的缩放模式，缩放系数由变换的方向和模式同时决定。取值必须是 "forward"，"backward"，"ortho"之一，默认值为 "backward"。三种缩放模式对应的行为如下： - "backward"：正向和逆向变换的缩放系数分别为 ``1`` 和 ``1/n``； @@ -31,6 +32,10 @@ irfftn - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为实数。输入数据（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。 diff --git a/docs/api/paddle/fft/rfft2_cn.rst b/docs/api/paddle/fft/rfft2_cn.rst index e08a1e5806b..b793af57acf 100644 --- a/docs/api/paddle/fft/rfft2_cn.rst +++ b/docs/api/paddle/fft/rfft2_cn.rst @@ -3,7 +3,7 @@ rfft2 ------------------------------- -.. py:function:: paddle.fft.rfft2(x, s=None, axes=(-2, -1), norm="backward", name=None) +.. py:function:: paddle.fft.rfft2(x, s=None, axes=(-2, -1), norm="backward", name=None, *, out=None) 二维实数傅里叶变换。 @@ -14,12 +14,13 @@ rfft2 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数。别名 ``input``。 - **s** (Sequence[int]，可选) - 傅里叶变换轴的长度（类似一维傅里叶变 换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度大，则 输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各个轴的长度。 - **axes** (Sequence[int]，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后两个轴。 + 别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必 须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为 如下，其中 ``n`` 为 ``s`` 中每个元素连乘： @@ -31,6 +32,10 @@ rfft2 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为复数。由输入 Tensor（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。 diff --git a/docs/api/paddle/fft/rfft_cn.rst b/docs/api/paddle/fft/rfft_cn.rst index 244fa7faacd..fb447efde55 100644 --- a/docs/api/paddle/fft/rfft_cn.rst +++ b/docs/api/paddle/fft/rfft_cn.rst @@ -3,7 +3,7 @@ rfft ------------------------------- -.. py:function:: paddle.fft.rfft(x, n=None, axis=-1, norm="backward", name=None) +.. py:function:: paddle.fft.rfft(x, n=None, axis=-1, norm="backward", name=None, *, out=None) 通过快速傅里叶变换(FFT)算法计算一维实数傅里叶变换。 @@ -13,11 +13,11 @@ rfft 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为实数。 + - **x** (Tensor) - 输入 Tensor，数据类型为实数。别名 ``input``。 - **n** (int，可选) - 傅里叶变换点数。如果 ``n`` 比输入 Tensor 中对应轴 的长度小，输入数据会被截断。如果 ``n`` 比输入 Tensor 中对应轴的长度大，则输入会被补零。如果 ``n`` 没有被指定，则使用输入 Tensor 中由 ``axis`` 指定的轴的长度。 - - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。 + - **axis** (int，可选) - 傅里叶变换的轴。如果没有指定，默认使用最后一维。别名 ``dim``。 - **norm** (str，可选) - 傅里叶变换的缩放模式，缩放系数由变换的方向和缩放模式同时决定。取值必须是 "forward"，"backward"，"ortho" 之一，默认值为 "backward"。三种缩放模式对应的行为如下： - "backward"：正向和逆向变换的缩放系数分别为 ``1`` 和 ``1/n``； @@ -27,6 +27,10 @@ rfft - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，数据类型为复数。 diff --git a/docs/api/paddle/fft/rfftfreq_cn.rst b/docs/api/paddle/fft/rfftfreq_cn.rst index ad4eee3581b..1bcee46e745 100644 --- a/docs/api/paddle/fft/rfftfreq_cn.rst +++ b/docs/api/paddle/fft/rfftfreq_cn.rst @@ -3,7 +3,7 @@ rfftfreq ------------------------------- -.. py:function:: paddle.fft.rfftfreq(n, d=1.0, dtype=None, name=None) +.. py:function:: paddle.fft.rfftfreq(n, d=1.0, dtype=None, name=None, *, out=None, device=None, requires_grad=False) 返回离散傅里叶变换的频率窗口(frequency bins)中心，以 "循环/采样间隔" 为单位。例如，采样间 隔以秒为单位，则频谱的单位是 "循环/秒"。用于 ``rfft`` 和 ``irfft``。 @@ -25,6 +25,12 @@ rfftfreq - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。为 None 时，使用当前默认 Tensor 类型的当前设备。默认值为 None。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 ::::::::: diff --git a/docs/api/paddle/fft/rfftn_cn.rst b/docs/api/paddle/fft/rfftn_cn.rst index 0d648634cfc..63633800e07 100644 --- a/docs/api/paddle/fft/rfftn_cn.rst +++ b/docs/api/paddle/fft/rfftn_cn.rst @@ -3,7 +3,7 @@ rfftn ------------------------------- -.. py:function:: paddle.fft.rfftn(x, s=None, axes=None, norm="backward", name=None) +.. py:function:: paddle.fft.rfftn(x, s=None, axes=None, norm="backward", name=None, *, out=None) N 维实数傅里叶变换。 @@ -14,13 +14,14 @@ N 维实数傅里叶变换。 参数 ::::::::: - - **x** (Tensor) - 输入数据，数据类型为实数。 + - **x** (Tensor) - 输入数据，数据类型为实数。别名 ``input``。 - **s** (Sequence[int]，可选) - 傅里叶变换轴的长度（类似一维傅里叶变 换中的参数 ``n``）。对于每一个傅里叶变换的轴，如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴 的长度小，输入 Tensor 会被截断。如果 ``s`` 中该轴的长度比输入 Tensor 中对应轴的长度大，则 输入会被补零。如果 ``s`` 没有指定，则使用输入 Tensor 中由 ``axes`` 指定的各个轴的长度。 - **axes** (Sequence[int]，可选) - 计算快速傅里叶变换的轴。如果没有指定，默认是使用最后 ``len(s)`` 个轴，如果 ``s`` 也没有指定则使用输入数据的全部的轴。 + 别名 ``dim``。 - **norm** (str，可选) - 指定傅里叶变换的缩放模式，缩放系数由变换的方向和模式同时决定。取值必 须是 "forward"，"backward"，"ortho"之一，默认值为 "backward"。三种缩放模式对应的行为如下： @@ -32,6 +33,10 @@ N 维实数傅里叶变换。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，复数类型，输入数据（可能被截断或者补零之后）在指定维度进行傅里叶变换的输出。最后一个傅立 diff --git a/docs/api/paddle/floor_divide_cn.rst b/docs/api/paddle/floor_divide_cn.rst index 9edd21e671d..fad3b3699dd 100644 --- a/docs/api/paddle/floor_divide_cn.rst +++ b/docs/api/paddle/floor_divide_cn.rst @@ -3,7 +3,7 @@ floor_divide ------------------------------- -.. py:function:: paddle.floor_divide(x, y, name=None) +.. py:function:: paddle.floor_divide(x, y, name=None, *, out=None) 逐元素整除算子，将输入 ``x`` 与输入 ``y`` 逐元素整除（商被朝 -inf 方向舍入到最接近的整数值），并将各个位置的输出元素保存到返回结果中。 @@ -26,13 +26,15 @@ floor_divide 参数 ::::::::: - - **x** (Tensor) - 多维 Tensor。数据类型为 int8 int16 int32 int64 float32 float64 float16 或 bfloat16。 + - **x** (Tensor) - 多维 Tensor。数据类型为 uint8、int8、int16、int32、int64、float16、bfloat16、float32 或 float64。 别名： ``input`` - - **y** (Tensor) - 多维 Tensor。数据类型为 int8 int16 int32 int64 float32 float64 float16 或 bfloat16。 + - **y** (Tensor|Number) - 多维 Tensor 或数值标量。数据类型为 uint8、int8、int16、int32、int64、float16、bfloat16、float32 或 float64。 别名： ``other`` - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **out** （Tensor，可选） - 指定输出结果的 ``Tensor``，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 返回 ::::::::: diff --git a/docs/api/paddle/gather_cn.rst b/docs/api/paddle/gather_cn.rst index 618f8b054be..b1df3abbb57 100644 --- a/docs/api/paddle/gather_cn.rst +++ b/docs/api/paddle/gather_cn.rst @@ -11,7 +11,7 @@ gather ===== -.. py:function:: paddle.gather(x, index, axis=None, name=None) +.. py:function:: paddle.gather(x, index, axis=None, name=None, out=None) 根据索引 index 获取输入 ``x`` 的指定 ``axis`` 维度的条目，并将它们拼接在一起。 @@ -42,8 +42,9 @@ gather :::::::::::: - **x** (Tensor) - 输入 Tensor，秩 ``rank >= 1``，支持的数据类型包括 int32、int64、float32、float64、complex64、complex128 和 uint8 (CPU)、float16（GPU） 。 - **index** (Tensor) - 索引 Tensor，秩 ``rank = 0`` 或者 ``rank = 1``，数据类型为 int32 或 int64。 - - **axis** (Tensor) - 指定 index 获取输入的维度，``axis`` 的类型可以是 int 或者 Tensor，当 ``axis`` 为 Tensor 的时候其数据类型为 int32 或者 int64。默认值为 None，当 ``axis`` 为 None 的时候其值为 0。 + - **axis** (Tensor|int|None) - 指定 index 获取输入的维度，``axis`` 的类型可以是 int 或者 Tensor，当 ``axis`` 为 Tensor 的时候其数据类型为 int32 或者 int64。默认值为 None，当 ``axis`` 为 None 的时候其值为 0。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 返回 :::::::::::: @@ -68,7 +69,7 @@ PyTorch 兼容的 ``gather`` 操作：根据索引 index 获取输入 ``input`` 参数 :::::::::::: - **input** (Tensor) - 输入 Tensor，支持的数据类型包括 int32、int64、float32、float64、int16、uint8、float16（GPU）以及 bfloat16（GPU） 。 - - **dim** (int) - 指定 index 获取输入的维度，``dim`` 的类型可以是 int 或者。 + - **dim** (int|Tensor) - 指定 index 获取输入的维度，``dim`` 的类型可以是 int 或 Tensor。 - **index** (Tensor) - 索引 Tensor，``index`` 张量的各维度需要小于等于 ``input`` 张量的各维度（除 ``dim`` 维度外），且值需要在 ``input.shape[dim]`` 范围内。数据类型为 int32 或 int64。 - **out** (Tensor，可选) - 用于引用式传入输出值，注意：动态图下 out 可以是任意 Tensor，默认值为 None。 @@ -76,6 +77,8 @@ PyTorch 兼容的 ``gather`` 操作：根据索引 index 获取输入 ``input`` 本接口没有实现 PyTorch 的 ``sparse_grad`` 参数！梯度默认是稠密的，等效于 ``sparse_grad=False``。 + 当前三个参数均为 Tensor 时，两种 ``gather`` 接口之间存在歧义，当前会优先选择原始 ``gather`` 接口。因此建议避免将 Tensor 作为 ``dim`` 传入。 + 返回 :::::::::::: diff --git a/docs/api/paddle/gcd_cn.rst b/docs/api/paddle/gcd_cn.rst index 8dae5949aea..8219e04a348 100644 --- a/docs/api/paddle/gcd_cn.rst +++ b/docs/api/paddle/gcd_cn.rst @@ -3,7 +3,7 @@ gcd ------------------------------- -.. py:function:: paddle.gcd(x, y, name=None) +.. py:function:: paddle.gcd(x, y, name=None, *, out=None) 计算两个输入的按元素绝对值的最大公约数，输入必须是整型。 @@ -23,6 +23,10 @@ gcd - **y** (Tensor) - 输入的 Tensor，数据类型为：int32，int64。支持别名 ``other`` 。 - **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/grad_cn.rst b/docs/api/paddle/grad_cn.rst index 13ee55a2a09..d1a6d7b79aa 100644 --- a/docs/api/paddle/grad_cn.rst +++ b/docs/api/paddle/grad_cn.rst @@ -4,7 +4,7 @@ grad ------------------------------- -.. py:function:: paddle.grad(outputs, inputs, grad_outputs=None, retain_graph=None, create_graph=False, only_inputs=True, allow_unused=False, no_grad_vars=None) +.. py:function:: paddle.grad(outputs, inputs, grad_outputs=None, retain_graph=None, create_graph=False, only_inputs=True, allow_unused=False, no_grad_vars=None, *, dump_backward_graph_path=None) .. note:: 该 API 仅支持 **动态图模式**。 @@ -20,13 +20,18 @@ grad - **retain_graph** (bool，可选) - 是否保留计算梯度的前向图。若值为 True，则前向图会保留，用户可对同一张图求两次反向。若值为 False，则前向图会释放。默认值为 None，表示值与 ``create_graph`` 相等。 - **create_graph** (bool，可选) - 是否创建计算过程中的反向图。若值为 True，则可支持计算高阶导数。若值为 False，则计算过程中的反向图会释放。默认值为 False。 - **only_inputs** (bool，可选) - 是否只计算 ``inputs`` 的梯度。若值为 False，则图中所有叶节点变量的梯度均会计算，并进行累加。若值为 True，则只会计算 ``inputs`` 的梯度。默认值为 True。only_inputs=False 功能正在开发中，目前尚不支持。 - - **allow_unused** (bool，可选) - 决定当某些 ``inputs`` 变量不在计算图中时抛出错误还是返回 None。若某些 ``inputs`` 变量不在计算图中（即它们的梯度为 None），则当 allowed_unused=False 时会抛出错误，当 allow_unused=True 时会返回 None 作为这些变量的梯度。默认值为 False。 + - **allow_unused** (bool，可选) - 决定当某些 ``inputs`` 变量不在计算图中时抛出错误还是返回 None。若某些 ``inputs`` 变量不在计算图中（即它们的梯度为 None），则当 allow_unused=False 时会抛出错误，当 allow_unused=True 时会返回 None 作为这些变量的梯度。默认值为 False。 - **no_grad_vars** (Tensor|list(Tensor)|tuple(Tensor)|set(Tensor)，可选) - 指明不需要计算梯度的变量。默认值为 None。 +关键字参数 +::::::::: + + - **dump_backward_graph_path** (str，可选) - 用于保存调试文件的目录路径。指定该参数后，会在此目录中生成反向相关图（dot 格式）和调试调用栈信息。默认值为 None。 + 返回 ::::::::: -tuple(Tensor)，其长度等于 ``inputs`` 中的变量个数，且第 i 个返回的变量是所有 ``outputs`` 相对于第 i 个 ``inputs`` 的梯度之和。 +list(Tensor)，其长度等于 ``inputs`` 中的变量个数，且第 i 个返回的变量是所有 ``outputs`` 相对于第 i 个 ``inputs`` 的梯度之和。 代码示例 1 ::::::::: diff --git a/docs/api/paddle/greater_equal_cn.rst b/docs/api/paddle/greater_equal_cn.rst index 2f627039572..a479fdf0986 100644 --- a/docs/api/paddle/greater_equal_cn.rst +++ b/docs/api/paddle/greater_equal_cn.rst @@ -2,7 +2,7 @@ greater_equal ------------------------------- -.. py:function:: paddle.greater_equal(x, y, name=None) +.. py:function:: paddle.greater_equal(x, y, name=None, *, out=None) 逐元素地返回 :math:`x >= y` 的逻辑值，相同位置前者输入大于等于后者输入返回 True，否则返回 False。使用重载算子 ``>=`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ greater_equal 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出结果的 Tensor，shape 和输入一致，数据类型为 bool。 diff --git a/docs/api/paddle/greater_than_cn.rst b/docs/api/paddle/greater_than_cn.rst index fc4f37fc4e1..c192dc419d8 100644 --- a/docs/api/paddle/greater_than_cn.rst +++ b/docs/api/paddle/greater_than_cn.rst @@ -2,21 +2,25 @@ greater_than ------------------------------- -.. py:function:: paddle.greater_than(x, y, name=None) +.. py:function:: paddle.greater_than(x, y, name=None, *, out=None) -返回 :math:`x>y` 逐元素比较 x 和 y 是否相等，相同位置前者输入大于等于后者输入则返回 True，否则返回 False。使用重载算子 ``>`` 可以有相同的计算函数效果。 +逐元素返回 :math:`x > y` 的真值；对应位置的 ``x`` 大于 ``y`` 时返回 True，否则返回 False。使用重载算子 ``>`` 可以获得相同的计算效果。 .. note:: 输出的结果不返回梯度。 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 用于比较的第一个输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 用于比较的第二个输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor，输出结果，shape 和输入一致，Tensor 数据类型为 bool。 diff --git a/docs/api/paddle/i0_cn.rst b/docs/api/paddle/i0_cn.rst index 31f31c1f47d..7a481b190b0 100644 --- a/docs/api/paddle/i0_cn.rst +++ b/docs/api/paddle/i0_cn.rst @@ -3,7 +3,7 @@ i0 ------------------------------- -.. py:function:: paddle.i0(x, name=None) +.. py:function:: paddle.i0(x, name=None, *, out=None) 对于给定 ``x`` 计算其每个元素的第一类零阶修正贝塞尔曲线函数，其中输入 ``x`` 大小无特殊限制。返回一个第一类零阶修正贝塞尔曲线函数上的 Tensor。 @@ -13,7 +13,7 @@ i0 参数 :::::::::: - - **x** (Tensor) – 输入是一个多维的 Tensor，它的数据类型可以是 float32，float64。 + - **x** (Tensor) – 输入是一个多维的 Tensor，它的数据类型可以是 float32、float64、uint8、int8、int16、int32、int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 ``None``。 关键字参数 @@ -22,7 +22,7 @@ i0 返回 :::::::::: - - ``Tensor`` (Tensor)：在 x 处的第一类零阶修正贝塞尔曲线函数的值。 + - ``Tensor`` (Tensor)：在 x 处的第一类零阶修正贝塞尔曲线函数的值。整数类型输入会自动转换为 float32。 代码示例 diff --git a/docs/api/paddle/i0e_cn.rst b/docs/api/paddle/i0e_cn.rst index cbdfeb4d7e9..70788f712ae 100644 --- a/docs/api/paddle/i0e_cn.rst +++ b/docs/api/paddle/i0e_cn.rst @@ -3,7 +3,7 @@ i0e ------------------------------- -.. py:function:: paddle.i0e(x, name=None) +.. py:function:: paddle.i0e(x, name=None, *, out=None) 对于给定 ``x`` 计算其每个元素的第一类指数缩放零阶修正贝塞尔曲线函数，其中输入 ``x`` 大小无特殊限制。返回一个第一类指数缩放零阶修正贝塞尔曲线函数上的 Tensor。 @@ -14,7 +14,7 @@ i0e 参数 :::::::::: - - **x** (Tensor) – 输入是一个多维的 Tensor，它的数据类型可以是 float32，float64。 + - **x** (Tensor) – 输入是一个多维的 Tensor，它的数据类型可以是 float32、float64、uint8、int8、int16、int32、int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 ``None``。 关键字参数 @@ -23,7 +23,7 @@ i0e 返回 :::::::::: - - ``Tensor`` (Tensor)：在 x 处的第一类指数缩放零阶修正贝塞尔曲线函数的值。 + - ``Tensor`` (Tensor)：在 x 处的第一类指数缩放零阶修正贝塞尔曲线函数的值。整数类型输入会自动转换为 float32。 代码示例 diff --git a/docs/api/paddle/imag_cn.rst b/docs/api/paddle/imag_cn.rst index 5f15f51a4b5..d0f4251d0a3 100644 --- a/docs/api/paddle/imag_cn.rst +++ b/docs/api/paddle/imag_cn.rst @@ -3,7 +3,7 @@ imag ------ -.. py:function:: paddle.imag(x, name=None) +.. py:function:: paddle.imag(x, name=None, *, out=None) 返回一个包含输入复数 Tensor 的虚部数值的新 Tensor。 @@ -13,6 +13,10 @@ imag - **x** (Tensor) - 输入的 Tensor，其数据类型可以为 complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，包含原复数 Tensor 的虚部数值。 diff --git a/docs/api/paddle/incubate/nn/FusedBiasDropoutResidualLayerNorm_cn.rst b/docs/api/paddle/incubate/nn/FusedBiasDropoutResidualLayerNorm_cn.rst index eaf074f8d56..00c4f069afd 100644 --- a/docs/api/paddle/incubate/nn/FusedBiasDropoutResidualLayerNorm_cn.rst +++ b/docs/api/paddle/incubate/nn/FusedBiasDropoutResidualLayerNorm_cn.rst @@ -1,7 +1,7 @@ .. _cn_api_paddle_incubate_nn_FusedBiasDropoutResidualLayerNorm: FusedBiasDropoutResidualLayerNorm -------------------------------- +---------------------------------- .. py:class:: paddle.incubate.nn.FusedBiasDropoutResidualLayerNorm(embed_dim, dropout_rate=0.5, weight_attr=None, bias_attr=None, epsilon=1e-05, name=None) @@ -11,8 +11,10 @@ FusedBiasDropoutResidualLayerNorm :::::::::::: - **embed_dim** (int) - 输入和输出中预期的特征大小。 - **dropout_rate** (float，可选) - 在注意力权重上使用的 Dropout 概率，用于在注意力后的 Dropout 过程中丢弃一些注意力目标。0 表示无 Dropout。默认为 0.5。 + - **weight_attr** (ParamAttr，可选) - 指定本层可学习权重的属性。默认值为 None，权重初始化为零。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数的属性。默认为 None，意味着使用默认的偏置参数属性。如果设置为 False，则该层不会有可训练的偏置参数。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **epsilon** (float，可选) - 添加到方差中的小值，以防止除零。默认为 1e-05。 + - **name** (str，可选) - 一般无需设置。具体用法请参见 :ref:`api_guide_Name`。 代码示例 :::::::::::: diff --git a/docs/api/paddle/incubate/nn/FusedFeedForward_cn.rst b/docs/api/paddle/incubate/nn/FusedFeedForward_cn.rst index b8630276734..cf6e51f3a63 100644 --- a/docs/api/paddle/incubate/nn/FusedFeedForward_cn.rst +++ b/docs/api/paddle/incubate/nn/FusedFeedForward_cn.rst @@ -2,7 +2,7 @@ FusedFeedForward ------------------------------- -.. py:class:: paddle.incubate.nn.FusedFeedForward(d_model, dim_feedforward, dropout_rate=0.1, activation='relu', act_dropout_rate=None, normalize_before=False, weight_attr=None, bias_attr=None) +.. py:class:: paddle.incubate.nn.FusedFeedForward(d_model, dim_feedforward, dropout_rate=0.1, epsilon=1e-05, activation='relu', act_dropout_rate=None, normalize_before=False, linear1_weight_attr=None, linear1_bias_attr=None, linear2_weight_attr=None, linear2_bias_attr=None, ln1_scale_attr=None, ln1_bias_attr=None, ln2_scale_attr=None, ln2_bias_attr=None, nranks=1, ring_id=-1, name=None) 这是一个调用融合算子 fused_feedforward（参考 :ref:`cn_api_paddle_incubate_nn_functional_fused_feedforward` ）。 @@ -12,11 +12,21 @@ FusedFeedForward - **d_model** (int) - 输入输出的维度。 - **dim_feedforward** (int) - 前馈神经网络中隐藏层的大小。 - **dropout_rate** (float，可选) - 对本层的输出进行处理的 dropout 值，置零的概率。默认值：0.1。 + - **epsilon** (float，可选) - 为防止方差除零而加到方差上的小值。默认值为 1e-05。 - **activation** (str，可选) - 激活函数。默认值：``relu``。 - **act_dropout_rate** (float，可选) - 激活函数后的 dropout 置零的概率。如果为 ``None`` 则 ``act_dropout_rate = dropout_rate``。默认值：``None`` 。 - **normalize_before** (bool，可选) - 设置对输入输出的处理。如果为 ``True``，则对输入进行层标准化（Layer Normalization），否则（即为 ``False`` ），则对输入不进行处理，而是在输出前进行标准化。默认值：``False`` 。 - - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值：``None``，表示使用默认的权重参数属性，即使用 0 进行初始化。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。如果该参数值是 ``ParamAttr``，则使用 ``ParamAttr``。如果该参数为 ``bool`` 类型，只支持为 ``False``，表示没有偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **linear1_weight_attr** (ParamAttr，可选) - 前馈网络第一个线性层权重参数的属性。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **linear1_bias_attr** (ParamAttr|bool，可选) - 前馈网络第一个线性层偏置参数的属性。设为 False 时该层不包含可训练偏置参数。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **linear2_weight_attr** (ParamAttr，可选) - 前馈网络第二个线性层权重参数的属性。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **linear2_bias_attr** (ParamAttr|bool，可选) - 前馈网络第二个线性层偏置参数的属性。设为 False 时该层不包含可训练偏置参数。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **ln1_scale_attr** (ParamAttr，可选) - 前置 LayerNorm 权重参数的属性。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **ln1_bias_attr** (ParamAttr|bool，可选) - 前置 LayerNorm 偏置参数的属性。设为 False 时该层不包含可训练偏置参数。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **ln2_scale_attr** (ParamAttr，可选) - 后置 LayerNorm 权重参数的属性。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **ln2_bias_attr** (ParamAttr|bool，可选) - 后置 LayerNorm 偏置参数的属性。设为 False 时该层不包含可训练偏置参数。默认值为 None。具体用法请参见 :ref:`cn_api_paddle_ParamAttr`。 + - **nranks** (int，可选) - 分布式张量模型并行的 rank 数。默认值为 1，表示不使用张量并行。 + - **ring_id** (int，可选) - 用于分布式张量模型并行。默认值为 -1，表示不使用张量并行。 + - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 ::::::::: diff --git a/docs/api/paddle/incubate/nn/FusedMultiHeadAttention_cn.rst b/docs/api/paddle/incubate/nn/FusedMultiHeadAttention_cn.rst index a4ccf7d36e2..e86529865da 100644 --- a/docs/api/paddle/incubate/nn/FusedMultiHeadAttention_cn.rst +++ b/docs/api/paddle/incubate/nn/FusedMultiHeadAttention_cn.rst @@ -23,22 +23,22 @@ FusedMultiHeadAttention ::::::::: - **embed_dim** (int) - 输入输出的维度。 - **num_heads** (int) - 多头注意力机制的 Head 数量。 - - **dropout_rate** (float，可选) - Multi-Head Attention 后面的 dropout 算子的注意力目标的随机失活率。0 表示进行 dropout 计算。默认值：0.5。 + - **dropout_rate** (float，可选) - Multi-Head Attention 后面的 dropout 算子的注意力目标的随机失活率。0 表示不进行 dropout 计算。默认值：0.5。 - **attn_dropout_rate** (float，可选) - Multi-Head Attention 中的 dropout 算子的注意力目标的随机失活率。0 表示不进行 dropout 计算。默认值：0.5。 - **kdim** (int，可选) - 键值对中 key 的维度。如果为 ``None`` 则 ``kdim = embed_dim``。默认值 ``None`` 。 - **vdim** (int，可选) - 键值对中 value 的维度。如果为 ``None`` 则 ``vdim = embed_dim``。默认值：``None`` 。 - **normalize_before** (bool，可选) - 是 pre_layer_norm 结构（True）还是 post_layer_norm 结构（False）。pre_layer_norm 结构中，``layer_norm`` 算子位于 multi-head attention 和 ffn 的前面，post_layer_norm 结构中，``layer_norm`` 位于两者的后面。默认值：``False`` 。 - - **need_weights** (bool，可选) - 表明是否返回注意力权重。默认值：``False`` 。 + - **need_weights** (bool，可选) - 表明是否返回注意力权重。当前仅支持 ``False``。默认值：``False`` 。 - **qkv_weight_attr** (ParamAttr，可选) - 为 Attention 中计算 q, k, v 时的计算指定权重参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **qkv_bias_attr** (ParamAttr，可选) - 为 Attention 中计算 q, k, v 时的计算指定偏置参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **qkv_bias_attr** (ParamAttr|bool|None，可选) - 为 Attention 中计算 q, k, v 时的计算指定偏置参数属性的对象。若为 ``False``，对应层不含可训练偏置参数。默认值：``None``，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **linear_weight_attr** (ParamAttr，可选) - 为 Multi-Head Attention 之后的线性计算指定权重参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **linear_bias_attr** (ParamAttr，可选) - 为 Multi-Head Attention 之后的线性计算指定偏置参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **linear_bias_attr** (ParamAttr|bool|None，可选) - 为 Multi-Head Attention 之后的线性计算指定偏置参数属性的对象。若为 ``False``，对应层不含可训练偏置参数。默认值：``None``，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **pre_ln_scale_attr** (ParamAttr，可选) - 为 pre_layer_norm 结构的前置 layer norm 计算指定权重参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **pre_ln_bias_attr** (ParamAttr，可选) - 为 pre_layer_norm 结构的前置 layer norm 计算指定偏置参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **pre_ln_bias_attr** (ParamAttr|bool|None，可选) - 为 pre_layer_norm 结构的前置 layer norm 计算指定偏置参数属性的对象。若为 ``False``，对应层不含可训练偏置参数。默认值：``None``，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **ln_scale_attr** (ParamAttr，可选) - 为 post_layer_norm 结构的后置 layer norm 计算指定权重参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - - **ln_bias_attr** (ParamAttr，可选) - 为 post_layer_norm 结构的前置 layer norm 计算指定偏置参数属性的对象。默认值：``None``，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 + - **ln_bias_attr** (ParamAttr|bool|None，可选) - 为 post_layer_norm 结构的前置 layer norm 计算指定偏置参数属性的对象。若为 ``False``，对应层不含可训练偏置参数。默认值：``None``，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。 - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 - - **nranks** (int，可选) - 分布式 tensor parallel 运行下该策略的并行度。默认值：-1，表示不使用 tensor parallel。 + - **nranks** (int，可选) - 分布式 tensor parallel 运行下该策略的并行度。默认值：1，表示不使用 tensor parallel。 - **ring_id** (int，可选) - 分布式 tensor parallel 运行下通讯所使用的 NCCL id。默认值：-1，表示不使用 tensor parallel。 - **transpose_qkv_wb** (bool，可选) - 生成 QKV 的映射计算的权重形状为 ``[3, num_heads, head_dim, embed_dim]`` (False) 还是 ``[embed_dim, 3 * embed_dim]`` (True)。仅支持 GPU 运算。默认值：``False``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/incubate/nn/functional/fused_feedforward_cn.rst b/docs/api/paddle/incubate/nn/functional/fused_feedforward_cn.rst index 30c36e8255b..520b8c0fc18 100644 --- a/docs/api/paddle/incubate/nn/functional/fused_feedforward_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/fused_feedforward_cn.rst @@ -3,7 +3,7 @@ fused_feedforward ------------------------------- -.. py:function:: paddle.incubate.nn.functional.fused_feedforward(x, linear1_weight, linear2_weight, linear1_bias=None, linear2_bias=None, ln1_scale=None, ln1_bias=None, ln2_scale=None, ln2_bias=None, dropout1_rate=0.5, dropout2_rate=0.5,activation="relu", ln1_epsilon=1e-5, ln2_epsilon=1e-5, pre_layer_norm=False, training=True, mode='upscale_in_train', name=None) +.. py:function:: paddle.incubate.nn.functional.fused_feedforward(x, linear1_weight, linear2_weight, linear1_bias=None, linear2_bias=None, ln1_scale=None, ln1_bias=None, ln2_scale=None, ln2_bias=None, dropout1_rate=0.5, dropout2_rate=0.5, activation="relu", ln1_epsilon=1e-5, ln2_epsilon=1e-5, pre_layer_norm=False, training=True, mode='upscale_in_train', ring_id=-1, add_residual=True, name=None) 这是一个融合算子，该算子是对 transformer 模型中 feed forward 层的多个算子进行融合，该算子只支持在 GPU 下运行，该算子与如下伪代码表达一样的功能： @@ -13,7 +13,10 @@ fused_feedforward if pre_layer_norm: src = layer_norm(src) src = linear(dropout(activation(linear(src)))) - src = residual + dropout(src) + if add_residual: + src = residual + dropout(src) + else: + src = dropout(src) if not pre_layer_norm: src = layer_norm(src) @@ -34,8 +37,8 @@ fused_feedforward - **ln1_epsilon** (float，可选) - 一个很小的浮点数，被第一个 layer_norm 算子加到分母，避免出现除零的情况。默认值是 1e-5。 - **ln2_epsilon** (float，可选) - 一个很小的浮点数，被第二个 layer_norm 算子加到分母，避免出现除零的情况。默认值是 1e-5。 - **pre_layer_norm** (bool，可选) - 在预处理阶段加上 layer_norm，或者在后处理阶段加上 layer_norm。默认值是 False。 - - **training** (bool)：标记是否为训练阶段。默认：True。 - - **mode** (str)：丢弃单元的方式，有两种'upscale_in_train'和'downscale_in_infer'，默认：'upscale_in_train'。计算方法如下： + - **training** (bool。可选) - 标记是否为训练阶段。默认：True。 + - **mode** (str，可选) - 丢弃单元的方式，有两种'upscale_in_train'和'downscale_in_infer'，默认：'upscale_in_train'。计算方法如下： 1. upscale_in_train，在训练时增大输出结果。 @@ -47,6 +50,8 @@ fused_feedforward - train: out = input * mask - inference: out = input * (1.0 - p) + - **ring_id** (int，可选) - 用于张量模型并行中的分布式前向传播，仅支持 NCCL。默认值为 -1，表示不使用张量并行。 + - **add_residual** (bool，可选) - 是否在末尾添加残差。默认值为 True。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/incubate/nn/functional/fused_linear_cn.rst b/docs/api/paddle/incubate/nn/functional/fused_linear_cn.rst index d5322691d2d..2675ccb0954 100644 --- a/docs/api/paddle/incubate/nn/functional/fused_linear_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/fused_linear_cn.rst @@ -3,18 +3,17 @@ fused_linear ------------------------------- -.. py:function:: paddle.incubate.nn.functional.fused_linear(x, weight, bias=None, trans_x=False, transpose_weight=False, name=None) +.. py:function:: paddle.incubate.nn.functional.fused_linear(x, weight, bias=None, transpose_weight=False, name=None) 全连接线性变换算子。该方法要求 CUDA 版本大于等于 11.6 。 参数 ::::::::: - - **x** (Tensor) – 需要进行乘法运算的输入 Tensor。 - - **weight** (Tensor) – 需要进行乘法运算的权重 Tensor，它的阶数必须为 2。 - - **bias** (Tensor, 可选) – 输入的偏置 Tensor。如果为 None ，则不执行偏置加法。否则，将偏置加到矩阵乘法的结果上。默认值为 None。 - - **trans_x** (bool, 可选) - 是否在乘法之前转置输入 Tensor。默认值：False。 - - **transpose_weight** (bool, 可选) - 是否在乘法之前转置权重。默认值：False。 - - **name** (str, 可选) - 如需详细信息，请参阅 :ref:`api_guide_Name` 。一般无需设置，默认值为 None。 + - **x** (Tensor) - 需要进行乘法运算的输入 Tensor。 + - **weight** (Tensor) - 需要进行乘法运算的权重 Tensor，它的阶数必须为 2。 + - **bias** (Tensor，可选) - 输入的偏置 Tensor。如果为 None ，则不执行偏置加法。否则，将偏置加到矩阵乘法的结果上。默认值为 None。 + - **transpose_weight** (bool，可选) - 是否在乘法之前转置权重。默认值：False。 + - **name** (str，可选) - 如需详细信息，请参阅 :ref:`api_guide_Name` 。一般无需设置，默认值为 None。 返回 ::::::::: diff --git a/docs/api/paddle/incubate/nn/functional/fused_multi_transformer_cn.rst b/docs/api/paddle/incubate/nn/functional/fused_multi_transformer_cn.rst index a55cdb79d2c..98e5852ed20 100644 --- a/docs/api/paddle/incubate/nn/functional/fused_multi_transformer_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/fused_multi_transformer_cn.rst @@ -3,7 +3,7 @@ fused_multi_transformer ------------------------------- -.. py:function:: paddle.incubate.nn.functional.fused_multi_transformer(x, ln_scales, ln_biases, qkv_weights, qkv_biases, linear_weights, linear_biases, ffn_ln_scales, ffn_ln_biases, ffn1_weights, ffn1_biases, ffn2_weights, ffn2_biases, pre_layer_norm=True, epsilon=1e-05, cache_kvs=None, pre_caches=None, seq_lens=None, rotary_embs=None, time_step=None, attn_mask=None, dropout_rate=0.0, rotary_emb_dims=0, activation='gelu', training=False, mode='upscale_in_train', trans_qkvw=True, ring_id=- 1, name=None) +.. py:function:: paddle.incubate.nn.functional.fused_multi_transformer(x, ln_scales, ln_biases, qkv_weights, qkv_biases, linear_weights, linear_biases, ffn_ln_scales, ffn_ln_biases, ffn1_weights, ffn1_biases, ffn2_weights, ffn2_biases, pre_layer_norm=True, epsilon=1e-05, residual_alpha=1.0, cache_kvs=None, beam_offset=None, pre_caches=None, seq_lens=None, rotary_embs=None, time_step=None, attn_mask=None, dropout_rate=0.0, rotary_emb_dims=0, activation='gelu', training=False, mode='upscale_in_train', trans_qkvw=True, ring_id=-1, norm_type='layernorm', use_neox_rotary_style=False, gqa_group_size=-1, name=None) 这是一个融合算子，用于计算 Transformer 模型架构中的多个 transformer 层。 @@ -49,27 +49,29 @@ Transformer 层的功能与以下伪代码一致： :::::::::::: - **x** (Tensor) - 输入张量可以是 3-D 张量，输入数据类型可以是 float16 或 float32，形状为 ``[batch\_size, sequence\_length, d\_model]``。 - **ln_scales** (list(Tensor)|tuple(Tensor)) - 注意力机制中层归一化层的权重张量，形状为 ``[d\_model]``。 - - **ln_biases** (list(Tensor)|tuple(Tensor)) - 注意力机制中层归一化层的偏重张量，形状为 ``[d\_model]``。 + - **ln_biases** (list(Tensor)|tuple(Tensor)) - 注意力机制中层归一化层的偏置张量，形状为 ``[d\_model]``。 - **qkv_weights** (list(Tensor)|tuple(Tensor)) - 注意力 qkv 计算的权重张量，形状为 ``[3, num\_head, dim\_head, d\_model]``。 - **qkv_biases** (list(Tensor)|tuple(Tensor)|None) - 注意力 qkv 计算的偏置张量，形状为 ``[3, num\_head, dim\_head]``。 - **linear_weights** (list(Tensor)|tuple(Tensor)) - 注意力机制中线性层的权重张量，形状为 ``[num\_head * dim\_head, d\_model]``。 - - **linear_biases** (list(Tensor)|tuple(Tensor)|None) - 注意力机制中线性层的的偏置张量，形状为 ``[d\_model]``。 + - **linear_biases** (list(Tensor)|tuple(Tensor)|None) - 注意力机制中线性层的偏置张量，形状为 ``[d\_model]``。 - **ffn_ln_scales** (list(Tensor)|tuple(Tensor)) - 前馈层中层归一化层的权重张量，形状为 ``[d\_model]``。 - **ffn_ln_biases** (list(Tensor)|tuple(Tensor)) - 前馈层中层归一化层的偏置张量，形状为 ``[d\_model]``。 - **ffn1_weights** (list(Tensor)|tuple(Tensor)) - 前馈层中第一个线性变换层的权重张量，形状为 ``[d\_model, dim\_feedforward]``。 - **ffn1_biases** (list(Tensor)|tuple(Tensor)|None) - 前馈层中第一个线性变换层的偏置张量，形状为 ``[dim\_feedforward]``。 - **ffn2_weights** (list(Tensor)|tuple(Tensor)) - 前馈层中第二线性变换层的权重张量，形状为 ``[dim\_feedforward, d\_model]``。 - - **ffn2_biases** (list(Tensor)|tuple(Tensor)|None) - 前馈层中第二线性变换层的偏置张量，形状为 ``[d_model]``。 + - **ffn2_biases** (list(Tensor)|tuple(Tensor)|None) - 前馈层中第二线性变换层的偏置张量，形状为 ``[d\_model]``。 - **pre_layer_norm** (bool，可选) - 是否是 pre_layer_norm（True）或 post_layer_norm（False）。默认为 True。 - **epsilon** (float，可选) - 添加到 layer_norm 的分母中的小浮点值，以避免除以零。默认为 1e-5。 + - **residual_alpha** (float，可选) - 残差连接的缩放系数。默认值为 1.0。 - **cache_kvs** (list(Tensor)|tuple(Tensor)，可选) - 生成模型的缓存结构张量。形状为 ``[2, bsz, num\_head, max\_seq\_len, head\_dim]``。默认为 None。 + - **beam_offset** (list(Tensor)|tuple(Tensor)|None，可选) - 生成模型使用的 beam offset。默认值为 None。 - **pre_caches** (list(Tensor)|tuple(Tensor)，可选) - 生成模型的前缀缓存。形状为 ``[2, bsz, num\_head, cache\_len, head\_dim]``。默认为 None。 - **seq_lens** (Tensor，可选) - 此批次的序列长度。形状为 ``[bsz]``。默认为 None。 - **rotary_embs** (Tensor，可选) - 用于旋转计算的 RoPE 嵌入。形状为 ``[2, bsz, 1, seq\_len, head\_dim]``。默认为 None。 - **time_step** (Tensor，可选) - 生成模型的时间步张量。用于解码阶段，表示时间步，即 CacheKV 的实际 seq_len。形状为 ``[1]``，必须位于 CPUPlace。默认为 None。 - **attn_mask** (Tensor，可选) - 用于多头注意力层中防止对某些不需要的位置（通常是填充或后续位置）进行注意。其形状为 ``[batch_size, 1, sequence_length, sequence_length]``。默认为 None。 - **dropout_rate** (float，可选) - 将单元设置为零的 dropout 概率。默认为 0.0。 - - **rotary_emb_dims** (int，可选) - 旋转计算的 rotary_emb_dims，当 rotary_embs 为 None 时为 0，当 rotary_embs 不为 None 且 pos_extra_ids 为 None 时为 1，当 rotary_embs 和 pos_extra_ids 均不为 None 时为 2。默认为 0。 + - **rotary_emb_dims** (int，可选) - 旋转计算的 rotary_emb_dims，当 ``rotary_embs`` 为 None 时为 0；当 ``rotary_embs`` 不为 None 时，该值大于 0 以启用旋转位置编码计算。默认为 0。 - **activation** (str，可选) - 激活函数。默认为"gelu"。 - **training** (bool，可选) - 标志是否处于训练阶段。默认为 False。 - **mode** (str，可选) - ['upscale_in_train'(默认) | 'downscale_in_infer'] @@ -85,6 +87,9 @@ Transformer 层的功能与以下伪代码一致： 如果为 true，则 qkv 的权重形状应为[3, num_head, dim_head, dim_embed]。 否则，qkv 的权重形状应为[dim_embed, 3, num_head, dim_head]。默认为 True。 - **ring_id** (int，可选) - 用于张量模型并行中的分布式前向传播，仅支持 NCCL。默认为-1，表示不使用 mp。 + - **norm_type** (str，可选) - 归一化类型。默认值为 ``"layernorm"``。 + - **use_neox_rotary_style** (bool，可选) - 是否使用 Neox 风格的旋转位置编码。默认值为 False。 + - **gqa_group_size** (int，可选) - GQA（Group Query Attention）组大小。默认值为 -1。 - **name** (str，可选) - 操作的名称（可选，默认为 None）。更多信息，请参阅 :ref:`api_guide_Name`。 返回 diff --git a/docs/api/paddle/incubate/nn/functional/fused_rms_norm_cn.rst b/docs/api/paddle/incubate/nn/functional/fused_rms_norm_cn.rst index 1cb6548d0fe..21b26f918dc 100644 --- a/docs/api/paddle/incubate/nn/functional/fused_rms_norm_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/fused_rms_norm_cn.rst @@ -3,7 +3,7 @@ fused_rms_norm ------------------------------- -.. py:function:: paddle.incubate.nn.functional.fused_rms_norm(x, norm_weight, norm_bias, epsilon, begin_norm_axis, bias=None, residual=None, quant_scale=- 1, quant_round_type=0, quant_max_bound=0, quant_min_bound=0) +.. py:function:: paddle.incubate.nn.functional.fused_rms_norm(x, norm_weight, norm_bias, epsilon, begin_norm_axis=1, bias=None, residual=None, quant_scale=-1, quant_round_type=0, quant_max_bound=0, quant_min_bound=0) 应用 Fused RMSNorm 内核，提供了更高的 GPU 利用率。同时，支持模式融合 RMSNorm(bias + residual + x)。 @@ -17,13 +17,13 @@ fused_rms_norm 算子目前只支持在 GPU 下运行。 - **norm_weight** (Tensor) - 用于仿射输出的权重张量。 - **norm_bias** (Tensor) - 用于仿射输出的偏置张量。 - **epsilon** (float) - 一个小的浮点数，用于避免除以零。 - - **begin_norm_axis** (int) - 归一化的起始轴，默认为 1。 + - **begin_norm_axis** (int，可选) - 归一化的起始轴，默认为 1。 - **bias** (Tensor，可选) - 前一层的偏置。 - **residual** (Tensor，可选) - 输入的残差。 - - **quant_scale** (float) - 量化缩放因子。 - - **quant_round_type** (float) - 量化四舍五入类型。 - - **quant_max_bound** (float) - 量化裁剪的最大边界值。 - - **quant_min_bound** (float) - 量化裁剪的最小边界值。 + - **quant_scale** (float，可选) - 量化缩放因子。 + - **quant_round_type** (float，可选) - 量化四舍五入类型。 + - **quant_max_bound** (float，可选) - 量化裁剪的最大边界值。 + - **quant_min_bound** (float，可选) - 量化裁剪的最小边界值。 返回 diff --git a/docs/api/paddle/incubate/nn/functional/fused_rotary_position_embedding_cn.rst b/docs/api/paddle/incubate/nn/functional/fused_rotary_position_embedding_cn.rst index 62f0baa1ccf..3345e05d133 100644 --- a/docs/api/paddle/incubate/nn/functional/fused_rotary_position_embedding_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/fused_rotary_position_embedding_cn.rst @@ -3,21 +3,22 @@ fused_rotary_position_embedding ------------------------------- -.. py:function:: paddle.incubate.nn.functional.fused_rotary_position_embedding(q, k=None, v=None, sin=None, cos=None, position_ids=None, use_neox_rotary_style=True) +.. py:function:: paddle.incubate.nn.functional.fused_rotary_position_embedding(q, k=None, v=None, sin=None, cos=None, position_ids=None, use_neox_rotary_style=True, time_major=False, rotary_emb_base=10000.0) + 融合旋转位置编码。 参数 :::::::::: - - **q** (Tensor) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 q 的形状必须是 [batch_size, seq_len, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 - - **k** (Tensor, 可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 k 的形状必须是 [batch_size, seq_len, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 - - **v** (Tensor, 可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 v 的形状必须是 [batch_size, seq_len, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 - - **sin** (Tensor, 可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 sin 的形状必须是 [seq_len, head_dim] 或 [1, seq_len, 1, head_dim], 并且 head_dim 必须是 2 的倍数。 - - **cos** (Tensor, 可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 cos 的形状必须是 [seq_len, head_dim] 或 [1, seq_len, 1, head_dim], 并且 head_dim 必须是 2 的倍数。 - - **position_ids** (Tensor, 可选) - 输入张量。 数据类型为 int64. position_ids 的形状为[batch_size, seq_len]。 - - **use_neox_rotary_style** (可选|bool) - 当 use_neox_rotary_style 为 True, 每两个相邻的数字计算一次。 当 use_neox_rotary_style 为 False, 计算与前半段和后半段位置相对应的数字。 默认值为 True。 - - **time_major** (可选|bool) - 指定输入张量的时间维度是否为第一个维度。 如果为 True，则输入张量的形状应为 [seq_len, batch_size, num_heads, head_dim]。 如果为 False，则输入张量的形状应为 [batch_size, seq_len, num_heads, head_dim] 。 默认值为 False。 - - **rotary_emb_base** (可选|float) - 计算旋转角使用的底数。 默认值为 10000.0。 + - **q** (Tensor) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 q 的形状必须是 [batch_size, seq_len, num_heads, head_dim] 或 [seq_len, batch_size, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 + - **k** (Tensor，可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 k 的形状必须是 [batch_size, seq_len, num_heads, head_dim] 或 [seq_len, batch_size, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 + - **v** (Tensor，可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 v 的形状必须是 [batch_size, seq_len, num_heads, head_dim] 或 [seq_len, batch_size, num_heads, head_dim]，并且 head_dim 必须是 2 的倍数。 + - **sin** (Tensor，可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 sin 的形状必须是 [seq_len, head_dim] 或 [1, seq_len, 1, head_dim], 并且 head_dim 必须是 2 的倍数。 + - **cos** (Tensor，可选) - 输入张量。 数据类型可以是 bfloat16, float16, float32 或 float64。 cos 的形状必须是 [seq_len, head_dim] 或 [1, seq_len, 1, head_dim], 并且 head_dim 必须是 2 的倍数。 + - **position_ids** (Tensor，可选) - 输入张量。 数据类型为 int64。 position_ids 的形状为[batch_size, seq_len]。 + - **use_neox_rotary_style** (bool，可选) - 当 use_neox_rotary_style 为 True, 每两个相邻的数字计算一次。 当 use_neox_rotary_style 为 False, 计算与前半段和后半段位置相对应的数字。 默认值为 True。 + - **time_major** (bool，可选) - 指定输入张量的时间维度是否为第一个维度。 如果为 True，则输入张量的形状应为 [seq_len, batch_size, num_heads, head_dim]。 如果为 False，则输入张量的形状应为 [batch_size, seq_len, num_heads, head_dim] 。 默认值为 False。 + - **rotary_emb_base** (float，可选) - 计算旋转角使用的底数。 默认值为 10000.0。 返回 diff --git a/docs/api/paddle/incubate/nn/functional/masked_multihead_attention_cn.rst b/docs/api/paddle/incubate/nn/functional/masked_multihead_attention_cn.rst index 1827e0726a8..ede7cd7c152 100644 --- a/docs/api/paddle/incubate/nn/functional/masked_multihead_attention_cn.rst +++ b/docs/api/paddle/incubate/nn/functional/masked_multihead_attention_cn.rst @@ -3,18 +3,23 @@ masked_multihead_attention ------------------------------- -.. py:function:: paddle.incubate.nn.functional.masked_multihead_attention(x, cache_kv=None, bias=None, src_mask=None, cum_offsets=None, sequence_lengths=None, rotary_tensor=None, beam_cache_offset=None, qkv_out_scale=None, out_shift=None, out_smooth=None, seq_len=1, rotary_emb_dims=0, use_neox_rotary_style=False, compute_dtype='default', out_scale=- 1, quant_round_type=1, quant_max_bound=127.0, quant_min_bound=- 127.0) +.. py:function:: paddle.incubate.nn.functional.masked_multihead_attention(x, cache_kv=None, bias=None, src_mask=None, cum_offsets=None, sequence_lengths=None, rotary_tensor=None, beam_cache_offset=None, qkv_out_scale=None, out_shift=None, out_smooth=None, seq_len=1, rotary_emb_dims=0, use_neox_rotary_style=False, compute_dtype='default', out_scale=-1, quant_round_type=1, quant_max_bound=127.0, quant_min_bound=-127.0) 用于文本摘要的蒙版多头注意力机制。 这是一个融合操作符，用于计算 Transformer 模型架构中的蒙版多头注意力。该操作符仅支持在 GPU 上运行。 +.. warning:: + + 此 API 自 Paddle 3.4.0 起已废弃，未来版本将移除。请改用 ``paddle.nn.functional.scaled_dot_product_attention``。 + 参数 :::::::::::: - **x** (Tensor) - 输入张量可以是 2-D 张量。其形状为 [batch_size, 3 * num_head * head_dim]。 - - **cache_kvs** (list(Tensor)|tuple(Tensor)) - 生成模型的缓存结构张量。其形状为 [2, batch_size, num_head, max_seq_len, head_dim]。 - - **bias** (Tensor，可选) - 偏置张量。其形状为 [3, num_head, head_dim]。 + - **cache_kv** (Tensor，可选) - 生成模型的缓存结构张量。其形状为 [2, batch_size, num_head, max_seq_len, head_dim]。 + - **bias** (Tensor) - 偏置张量。其形状为 [3, num_head, head_dim]。 - **src_mask** (Tensor，可选) - 源掩码张量。其形状为 [batch_size, 1, 1, sequence_length]。 + - **cum_offsets** (Tensor，可选) - 从填充数据到去填充数据的累积偏移量。 - **sequence_lengths** (Tensor，可选) - 序列长度张量，用于索引输入。其形状为 [batch_size, 1]。 - **rotary_tensor** (Tensor，可选) - 旋转张量。其数据类型必须为浮点型。其形状为 [batch_size, 1, 1, sequence_length, head_dim]。 - **beam_cache_offset** (Tensor，可选) - Beam 缓存偏移张量。其形状为 [batch_size, beam_size, max_seq_len + max_dec_len]。 @@ -22,17 +27,17 @@ masked_multihead_attention - **out_shift** (Tensor，可选) - 量化中使用的 out_shift 张量。 - **out_smooth** (Tensor，可选) - 量化中使用的 out_smooth 张量。 - **seq_len** (int，可选) - 序列长度，用于获取输入长度。默认为 1。 - - **rotary_emb_dims** (int，可选) - 旋转嵌入维度。默认为 1。 + - **rotary_emb_dims** (int，可选) - 旋转嵌入维度。默认为 0。 - **use_neox_rotary_style** (bool，可选) - 表示是否需要 neox_rotary_style 的标志。默认为 False。 - - **compute_dtype** (string) - 计算数据类型，用于表示输入数据类型。 - - **out_scale** (float，可选) - 量化中使用的 out_scale。默认为 1.0。 + - **compute_dtype** (string，可选) - 计算数据类型，用于表示输入数据类型。 + - **out_scale** (float，可选) - 量化中使用的 out_scale。默认为 -1。 - **quant_round_type** (int，可选) - 量化中使用的 quant_round_type。默认为 1。 - **quant_max_bound** (float，可选) - 量化中使用的 quant_max_bound。默认为 127.0。 - **quant_min_bound** (float，可选) - 量化中使用的 quant_min_bound。默认为 -127.0。 返回 :::::::::::: - - Tensor|tuple：如果 "beam_cache_offset_out" 不为 None，则返回元组 (output, cache_kvs_out, beam_cache_offset_out)，其中 output 是蒙版多头注意力层的输出，cache_kvs_out 与输入 ``cache_kvs`` 原地更新。如果 "beam_cache_offset_out" 为 None，则返回元组 (output, cache_kvs_out)。 + - Tensor|tuple：如果 ``beam_cache_offset_out`` 不为 None，则返回元组 ``(output, cache_kv_out, beam_cache_offset_out)``，其中 ``output`` 是蒙版多头注意力层的输出，``cache_kv_out`` 与输入 ``cache_kv`` 原地更新。如果 ``beam_cache_offset_out`` 为 None，则返回元组 ``(output, cache_kv_out)``。 形状 :::::::::::: diff --git a/docs/api/paddle/incubate/optimizer/LBFGS_cn.rst b/docs/api/paddle/incubate/optimizer/LBFGS_cn.rst index 0ab658442fe..61bec75d0cf 100644 --- a/docs/api/paddle/incubate/optimizer/LBFGS_cn.rst +++ b/docs/api/paddle/incubate/optimizer/LBFGS_cn.rst @@ -3,7 +3,10 @@ LBFGS ------------------------------- -.. py:class:: paddle.incubate.optimizer.LBFGS(lr=1.0, max_iter=20, max_eval=None, tolerance_grad=1e-07, tolerance_change=1e-09, history_size=100, line_search_fn=None, parameters=None, weight_decay=None, grad_clip=None, name=None) +.. py:class:: paddle.incubate.optimizer.LBFGS(learning_rate=1.0, max_iter=20, max_eval=None, tolerance_grad=1e-07, tolerance_change=1e-09, history_size=100, line_search_fn=None, parameters=None, weight_decay=None, grad_clip=None, name=None) + +.. warning:: + 此 API 自 Paddle 2.5.0 起已废弃，未来版本将移除。请改用 ``paddle.optimizer.LBFGS``。 ``LBFGS`` 使用 L-BFGS 方法对参数进行优化更新，使得 loss 值最小。 @@ -27,14 +30,14 @@ LBFGS 具体原理参考书籍 Jorge Nocedal, Stephen J. Wright, Numerical Optim 参数 ::::::::: - - **lr** (float，可选) - 学习率，用于参数更新的计算，默认值：1.0。 - - **max_iter** (Scalar，可选) - 每个优化单步的最大迭代次数，默认值：20。 - - **max_eval** (Scalar，可选) - 每次优化单步中函数计算的最大数量，默认值：max_iter * 1.25。 - - **tolerance_grad** (float，可选) - 当梯度的范数小于该值时，终止迭代。当前使用正无穷范数。默认值：1e-5。 + - **learning_rate** (float，可选) - 学习率，用于参数更新的计算，默认值：1.0。 + - **max_iter** (int，可选) - 每个优化单步的最大迭代次数，默认值：20。 + - **max_eval** (int，可选) - 每次优化单步中函数计算的最大数量，默认值：max_iter * 1.25。 + - **tolerance_grad** (float，可选) - 当梯度的范数小于该值时，终止迭代。当前使用正无穷范数。默认值：1e-7。 - **tolerance_change** (float，可选) - 当函数值/x 值/其他参数 两次迭代的改变量小于该值时，终止迭代。默认值：1e-9。 - - **history_size** (Scalar，可选) - 指定储存的向量对{si,yi}数量。默认值：100。 - - **line_search_fn** (str，可选) - 指定要使用的线搜索方法，目前支持值为'strong wolfe'方法。默认值：'None'。 - - **parameters** (list，可选) - 指定优化器需要优化的参数，在动态图模式下必须提供该参数。默认值：None。 + - **history_size** (int，可选) - 指定储存的向量对{si,yi}数量。默认值：100。 + - **line_search_fn** (str，可选) - 指定要使用的线搜索方法，目前支持值为'strong wolfe'方法。默认值：None。 + - **parameters** (list|tuple，可选) - 指定优化器需要优化的参数，在动态图模式下必须提供该参数。默认值：None。 - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 :ref:`cn_api_paddle_regularizer_L2Decay` 。如果一个参数已经在 :ref:`cn_api_paddle_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； 如果没有在 :ref:`cn_api_paddle_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为 None，表示没有正则化。 diff --git a/docs/api/paddle/incubate/segment_max_cn.rst b/docs/api/paddle/incubate/segment_max_cn.rst index 055880474b7..18f0a7427c5 100644 --- a/docs/api/paddle/incubate/segment_max_cn.rst +++ b/docs/api/paddle/incubate/segment_max_cn.rst @@ -3,8 +3,10 @@ segment_max ------------------------------- -.. py:function:: paddle.incubate.segment_max((data, segment_ids, name=None) +.. py:function:: paddle.incubate.segment_max(data, segment_ids, name=None) +.. warning:: + 此 API 自 Paddle 2.4.0 起已废弃，未来版本将移除。请改用 ``paddle.geometric.segment_max``。 分段求最大值函数。 @@ -20,7 +22,7 @@ segment_max 参数 ::::::::: - - **data** (Tensor) - Tensor，数据类型为 float32、float64。 + - **data** (Tensor) - Tensor，数据类型为 float32、float64、int32、int64。 - **segment_ids** (Tensor) - 一维 Tensor，与输入数据 ``data`` 的第一维大小相同，表示 ``data`` 分段位置，单调非减。合法的数据类型为 int32、int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/incubate/segment_min_cn.rst b/docs/api/paddle/incubate/segment_min_cn.rst index f550ef2910d..0cd3078b6d8 100644 --- a/docs/api/paddle/incubate/segment_min_cn.rst +++ b/docs/api/paddle/incubate/segment_min_cn.rst @@ -3,8 +3,10 @@ segment_min ------------------------------- -.. py:function:: paddle.incubate.segment_min((data, segment_ids, name=None) +.. py:function:: paddle.incubate.segment_min(data, segment_ids, name=None) +.. warning:: + 此 API 自 Paddle 2.4.0 起已废弃，未来版本将移除。请改用 ``paddle.geometric.segment_min``。 分段求最小值函数。 @@ -20,7 +22,7 @@ segment_min 参数 ::::::::: - - **data** (Tensor) - Tensor，数据类型为 float32、float64。 + - **data** (Tensor) - Tensor，数据类型为 float32、float64、int32、int64。 - **segment_ids** (Tensor) - 一维 Tensor，与输入数据 ``data`` 的第一维大小相同，表示 ``data`` 分段位置，单调非减。合法的数据类型为 int32、int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/incubate/segment_sum_cn.rst b/docs/api/paddle/incubate/segment_sum_cn.rst index b1d20c8e4f4..5f2e2c45eac 100644 --- a/docs/api/paddle/incubate/segment_sum_cn.rst +++ b/docs/api/paddle/incubate/segment_sum_cn.rst @@ -3,8 +3,10 @@ segment_sum ------------------------------- -.. py:function:: paddle.incubate.segment_sum((data, segment_ids, name=None) +.. py:function:: paddle.incubate.segment_sum(data, segment_ids, name=None) +.. warning:: + 此 API 自 Paddle 2.4.0 起已废弃，未来版本将移除。请改用 ``paddle.geometric.segment_sum``。 分段求和函数。 @@ -21,7 +23,7 @@ segment_sum 参数 ::::::::: - - **data** (Tensor) - Tensor，数据类型为 float32、float64。 + - **data** (Tensor) - Tensor，数据类型为 float32、float64、int32、int64。 - **segment_ids** (Tensor) - 一维 Tensor，与输入数据 ``data`` 的第一维大小相同，表示 ``data`` 分段位置，单调非减。合法的数据类型为 int32、int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/index_add_cn.rst b/docs/api/paddle/index_add_cn.rst index a4d17c33f20..df12877019d 100644 --- a/docs/api/paddle/index_add_cn.rst +++ b/docs/api/paddle/index_add_cn.rst @@ -3,11 +3,17 @@ index_add ------------------------------- -.. py:function:: paddle.index_add(x, index, axis, value, name=None) +.. py:function:: paddle.index_add(x, index, axis, value, alpha=1, name=None, *, out=None) +.. note:: + 本 API 支持两种签名： -沿着指定轴 ``axis`` 将 ``index`` 中指定位置的 ``x`` 与 ``value`` 相加，并写入到结果 Tensor 中的对应位置。这里 ``index`` 是一个 ``1-D`` Tensor。除 ``axis`` 轴外，返回的 Tensor 其余维度大小和输入 ``x`` 相等， ``axis`` 维度的大小等于 ``index`` 的大小。 + 1. ``paddle.index_add(x, index, axis, value, alpha=1, name=None, *, out=None)`` （Paddle 风格）。 + 2. ``paddle.index_add(input, dim, index, source, *, alpha=1, out=None)`` （PyTorch 风格）。 + + +沿着指定轴 ``axis`` 将 ``index`` 中指定位置的 ``x`` 与 ``value`` 相加，并写入到结果 Tensor 中的对应位置。这里 ``index`` 是一个 ``1-D`` Tensor。返回 Tensor 与输入 ``x`` 的形状相同。 **示例** @@ -60,7 +66,7 @@ index_add **示例 1 图解说明** - 下图展示了示例 1 中的情形——一个形状为 [3,3] 的二维张量通过 index_add 操作在 axis=0 轴上对指定位置的元素进行相加，同时保持了除 ``axis`` 轴外，返回的 Tensor 其余维度大小和输入 ``x`` 相等。 + 下图展示了示例 1 中的情形——一个形状为 [3,3] 的二维张量通过 index_add 操作在 axis=0 轴上对指定位置的元素进行相加，返回 Tensor 与输入 ``x`` 的形状相同。 .. figure:: ../../images/api_legend/index_add/index_add-1.png :width: 500 @@ -69,7 +75,7 @@ index_add **示例 2 图解说明** - 下图展示了示例 2 中的情形——一个形状为 [3,3] 的二维张量通过 index_add 操作在 axis=1 轴上对指定位置的元素进行相加，同时保持了除 ``axis`` 轴外，返回的 Tensor 其余维度大小和输入 ``x`` 相等。 + 下图展示了示例 2 中的情形——一个形状为 [3,3] 的二维张量通过 index_add 操作在 axis=1 轴上对指定位置的元素进行相加，返回 Tensor 与输入 ``x`` 的形状相同。 .. figure:: ../../images/api_legend/index_add/index_add-2.png :width: 500 @@ -79,16 +85,22 @@ index_add 参数 ::::::::: - - **x** (Tensor) - 输入 Tensor。 ``x`` 的数据类型可以是 float16，float32，float64，int32，int64。 + - **x** (Tensor) - 输入 Tensor。 ``x`` 的数据类型可以是 float16，float32，float64，int32，int64。别名 ``input``。 - **index** (Tensor) - 包含索引下标的 1-D Tensor。数据类型为 int32 或者 int64。 - - **axis** (int) - 索引轴。数据类型为 int。 - - **value** (Tensor) - 与 ``x`` 相加的 Tensor。 ``value`` 的数据类型同 ``x`` 。 + - **axis** (int) - 索引轴。数据类型为 int。别名 ``dim``。 + - **value** (Tensor) - 与 ``x`` 相加的 Tensor。 ``value`` 的数据类型同 ``x``。别名 ``source``。 + - **alpha** (Number，可选) - ``value`` 的缩放因子。默认值为 1。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** (Tensor，可选) - 输出 Tensor。默认值为 None。 + 返回 ::::::::: -Tensor，返回一个数据类型同输入的 Tensor。 +Tensor，返回一个形状和数据类型均与输入 ``x`` 相同的 Tensor。 代码示例 diff --git a/docs/api/paddle/lcm_cn.rst b/docs/api/paddle/lcm_cn.rst index 04439944401..2698753d80c 100644 --- a/docs/api/paddle/lcm_cn.rst +++ b/docs/api/paddle/lcm_cn.rst @@ -3,7 +3,7 @@ lcm ------------------------------- -.. py:function:: paddle.lcm(x, y, name=None) +.. py:function:: paddle.lcm(x, y, name=None, *, out=None) 计算两个输入的按元素绝对值的最小公倍数，输入必须是整型。 @@ -23,6 +23,10 @@ lcm - **y** (Tensor) - 输入的 Tensor，数据类型为：int32，int64。支持别名 ``other`` 。 - **name** (str，可选) - 操作的名称（可选，默认值为 None）。更多信息请参见 :ref:`api_guide_Name`。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/less_cn.rst b/docs/api/paddle/less_cn.rst index 9a7227a1c65..8bbc85ee32c 100644 --- a/docs/api/paddle/less_cn.rst +++ b/docs/api/paddle/less_cn.rst @@ -2,7 +2,7 @@ less ------------------------------- -.. py:function:: paddle.less(x, y, name=None) +.. py:function:: paddle.less(x, y, name=None, *, out=None) 逐元素地返回 :math:`x < y` 的逻辑值，相同位置前者输入小于后者输入则返回 True，否则返回 False。使用重载算子 ``<`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ less 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出结果的 Tensor，输出 Tensor 的 shape 和输入一致，Tensor 数据类型为 bool。 diff --git a/docs/api/paddle/less_equal_cn.rst b/docs/api/paddle/less_equal_cn.rst index 199f8151856..3edc77fe874 100644 --- a/docs/api/paddle/less_equal_cn.rst +++ b/docs/api/paddle/less_equal_cn.rst @@ -2,7 +2,7 @@ less_equal ------------------------------- -.. py:function:: paddle.less_equal(x, y, name=None) +.. py:function:: paddle.less_equal(x, y, name=None, *, out=None) 逐元素地返回 :math:`x <= y` 的逻辑值，相同位置前者输入小于等于后者输入则返回 True，否则返回 False。使用重载算子 ``<=`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ less_equal 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出结果的 Tensor，输出 Tensor 的 shape 和输入一致，Tensor 数据类型为 bool。 diff --git a/docs/api/paddle/less_than_cn.rst b/docs/api/paddle/less_than_cn.rst index 082086c3b42..5933119b4e1 100644 --- a/docs/api/paddle/less_than_cn.rst +++ b/docs/api/paddle/less_than_cn.rst @@ -2,7 +2,7 @@ less_than ------------------------------- -.. py:function:: paddle.less_than(x, y, name=None) +.. py:function:: paddle.less_than(x, y, name=None, *, out=None) 逐元素地返回 :math:`x < y` 的逻辑值，相同位置前者输入小于后者输入则返回 True，否则返回 False。使用重载算子 ``<`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ less_than 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输出结果的 Tensor，输出 Tensor 的 shape 和输入一致，Tensor 数据类型为 bool。 diff --git a/docs/api/paddle/lgamma_cn.rst b/docs/api/paddle/lgamma_cn.rst index 51f17ac1c11..dbf77c578ae 100644 --- a/docs/api/paddle/lgamma_cn.rst +++ b/docs/api/paddle/lgamma_cn.rst @@ -3,19 +3,23 @@ lgamma ------------------------------- -.. py:function:: paddle.lgamma(x, name=None) +.. py:function:: paddle.lgamma(x, name=None, *, out=None) 计算输入 x 的 gamma 函数的自然对数并返回。 参数 ::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64。 + - **x** (Tensor) - 输入 Tensor，数据类型为 bfloat16、float16、float32、float64、uint8、int8、int16、int32 或 int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: -输出 Tensor，与 ``x`` 维度相同、数据类型相同。 +输出 Tensor，与 ``x`` 维度相同、数据类型相同；整数类型输入会自动转换为 float32。 代码示例 ::::::::: diff --git a/docs/api/paddle/linalg/inv_cn.rst b/docs/api/paddle/linalg/inv_cn.rst index 020db048ce6..e2d2c9b828f 100644 --- a/docs/api/paddle/linalg/inv_cn.rst +++ b/docs/api/paddle/linalg/inv_cn.rst @@ -3,16 +3,20 @@ inv ------------------------------- -.. py:function:: paddle.linalg.inv(x, name=None) +.. py:function:: paddle.linalg.inv(x, name=None, *, out=None) 计算方阵的逆。方阵是行数和列数相等的矩阵。输入可以是一个方阵（2-D Tensor），或者是批次方阵（维数大于 2 时）。 参数 ::::::::: - - **x** (Tensor) – 输入 Tensor，最后两维的大小必须相等。如果输入 Tensor 的维数大于 2，则被视为 2-D 矩阵的批次（batch）。支持的数据类型：float32，float64。别名 ``input``。 + - **x** (Tensor) – 输入 Tensor，最后两维的大小必须相等。如果输入 Tensor 的维数大于 2，则被视为 2-D 矩阵的批次（batch）。支持的数据类型：float32、float64、complex64、complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::: Tensor，输入方阵的逆。 diff --git a/docs/api/paddle/linalg/ormqr_cn.rst b/docs/api/paddle/linalg/ormqr_cn.rst index 81b2615b01d..bba7614f9a6 100644 --- a/docs/api/paddle/linalg/ormqr_cn.rst +++ b/docs/api/paddle/linalg/ormqr_cn.rst @@ -3,23 +3,24 @@ ormqr ------------------------------- -.. py:function:: paddle.linalg.ormqr(x, tau, other, left=True, transpose=False) +.. py:function:: paddle.linalg.ormqr(x, tau, y, left=True, transpose=False, name=None) -计算维度为(m, n)的矩阵 C（由 :attr:`other` 给出）和一个矩阵 Q 的乘积， +计算维度为(m, n)的矩阵 C（由 :attr:`y` 给出）和一个矩阵 Q 的乘积， 其中 Q 由 Householder 反射系数 (:attr:`x`, :attr:`tau`) 表示。 参数 :::::::::::: - - **x** (Tensor) - 输入一个或一批矩阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, MN, K]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32， float64。 - - **tau** (Tensor) - 输入一个或一批 Householder 反射系数，类型为 Tensor。 ``tau`` 的形状应为 ``[*, min(MN, K)]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32， float64。 - - **other** (Tensor) - 输入一个或一批矩阵，类型为 Tensor。 ``other`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32， float64。 - - **left** (bool， 可选) - 决定了矩阵乘积运算的顺序。如果 left 为 ``True`` ，计算顺序为 op(Q) * other ，否则，计算顺序为 other * op(Q)。默认值： ``True`` 。 + - **x** (Tensor) - 输入一个或一批矩阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, MN, K]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float16、float32、float64、complex64、complex128。 + - **tau** (Tensor) - 输入一个或一批 Householder 反射系数，类型为 Tensor。 ``tau`` 的形状应为 ``[*, min(MN, K)]``，其中 ``*`` 为零或更大的批次维度，数据类型与 ``x`` 相同，支持 float16、float32、float64、complex64、complex128。 + - **y** (Tensor) - 输入一个或一批矩阵，类型为 Tensor。 ``y`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型与 ``x`` 相同，支持 float16、float32、float64、complex64、complex128。 + - **left** (bool， 可选) - 决定了矩阵乘积运算的顺序。如果 left 为 ``True`` ，计算顺序为 op(Q) * y ，否则，计算顺序为 y * op(Q)。默认值： ``True`` 。 - **transpose** (bool， 可选) - 如果为 ``True`` ，对矩阵 Q 进行共轭转置变换，否则，不对矩阵 Q 进行共轭转置变换。默认值： ``False`` 。 + - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 :::::::::::: - ``Tensor``，维度和数据类型都与 :attr:`other` 一致。 + ``Tensor``，维度和数据类型都与 :attr:`y` 一致。 代码示例 :::::::::: diff --git a/docs/api/paddle/linalg/pinv_cn.rst b/docs/api/paddle/linalg/pinv_cn.rst index 03939d08c2b..d2805849033 100644 --- a/docs/api/paddle/linalg/pinv_cn.rst +++ b/docs/api/paddle/linalg/pinv_cn.rst @@ -3,7 +3,7 @@ pinv ------------------------------- -.. py:function:: paddle.linalg.pinv(x, rcond=1e-15, hermitian=False, name=None) +.. py:function:: paddle.linalg.pinv(x, rcond=1e-15, hermitian=False, name=None, *, atol=None, rtol=None, out=None) 该 API 通过奇异值分解(``svd``)来计算伪逆矩阵，支持单个矩阵或批量矩阵。 @@ -11,16 +11,22 @@ pinv - 如果 ``hermitian`` 为真，那么该 API 会利用特征值分解(``eigh``)进行伪逆矩阵的求解。同时输入需要满足以下条件：如果数据类型为实数，那么输入需要为对称矩阵；如果数据类型为复数，那么输入需要为 ``hermitian`` 矩阵。 参数 -::::::::: - - **x** (Tensor)：输入变量，类型为 Tensor，数据类型为 float32、float64、complex64、complex12，形状为（M, N）或（B, M, N）。别名 ``input``。 - - **rcond** (float64，可选)：奇异值（特征值）被截断的阈值，奇异值（特征值）小于 rcond * 最大奇异值时会被置为 0，默认值为 1e-15。 +:::::::::::: + - **x** (Tensor)：输入变量，类型为 Tensor，数据类型为 float32、float64、complex64、complex128，形状为 ``[..., M, N]``，其中 ``...`` 为零个或多个批次维度，``M`` 和 ``N`` 为任意正整数。当数据类型为 complex64 或 complex128 时，``hermitian`` 必须设为 True。别名 ``input``、``A``。 + - **rcond** (Tensor|float，可选)：用于确定奇异值是否为零的容差值，保留该参数以兼容 NumPy。推荐使用 ``rtol``；若指定 ``rtol``，则忽略 ``rcond``。默认值为 1e-15。 - **hermitian** (bool，可选)：是否为 ``hermitian`` 矩阵或者实对称矩阵，默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **atol** (float|Tensor|None，可选) - 绝对容差值。为 None 时视为 0。默认值为 None。 + - **rtol** (float|Tensor|None，可选) - 相对容差值。``atol`` 和 ``rtol`` 均为 None 时使用 ``rcond``；若指定 ``rtol``，则忽略 ``rcond``。默认值为 None。 + - **out** (Tensor|None，可选) - 输出 Tensor。若提供，计算结果将写入该 Tensor。默认值为 None。 + 返回 :::::::::::: -Tensor，输入矩阵的伪逆矩阵，数据类型和输入数据类型一致。形状为（N, M）或（B, N, M）。 +Tensor，输入矩阵的伪逆矩阵，数据类型和输入数据类型一致，形状为 ``[..., N, M]``。 代码示例 :::::::::: diff --git a/docs/api/paddle/linalg/qr_cn.rst b/docs/api/paddle/linalg/qr_cn.rst index 5a7cd3ed219..d5c98b161bf 100644 --- a/docs/api/paddle/linalg/qr_cn.rst +++ b/docs/api/paddle/linalg/qr_cn.rst @@ -24,7 +24,7 @@ qr 参数 :::::::::::: - - **x** (Tensor)：输入进行正交三角分解的一个或一批方阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32、float64、complex64、complex128。别名 ``input``, ``A``。 + - **x** (Tensor)：输入进行正交三角分解的一个或一批矩阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，``M`` 和 ``N`` 为任意正整数，数据类型支持 float32、float64、complex64、complex128。别名 ``input``, ``A``。 - **mode** (str，可选)：控制正交三角分解的行为，默认是 ``reduced``，假设 ``x`` 形状应为 ``[*, M, N]`` 和 ``K = min(M, N)``： 如果 ``mode = "reduced"``，则 :math:`Q` 形状为 ``[*, M, K]`` 和 :math:`R` 形状为 ``[*, K, N]``； 如果 ``mode = "complete"``，则 :math:`Q` 形状为 ``[*, M, M]`` 和 :math:`R` 形状为 ``[*, M, N]``； diff --git a/docs/api/paddle/linalg/slogdet_cn.rst b/docs/api/paddle/linalg/slogdet_cn.rst index b6bb65344a2..7143fe14125 100644 --- a/docs/api/paddle/linalg/slogdet_cn.rst +++ b/docs/api/paddle/linalg/slogdet_cn.rst @@ -3,7 +3,7 @@ slogdet ------------------------------- -.. py:function:: paddle.linalg.slogdet(x) +.. py:function:: paddle.linalg.slogdet(x, name=None) 计算批量矩阵的行列式值的符号值和行列式值绝对值的自然对数值。 .. note:: @@ -14,6 +14,7 @@ slogdet :::::::::::: - **x** (Tensor)：输入一个或批量矩阵。``x`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32、float64、complex64、complex128。 + - **name** (str|None，可选) - 输出名称，用于打印开发调试信息。默认值为 None。具体用法请参见 :ref:`api_guide_Name`。 返回 :::::::::::: diff --git a/docs/api/paddle/linalg/solve_cn.rst b/docs/api/paddle/linalg/solve_cn.rst index 6e1a0b9ed49..34e9e1e5329 100644 --- a/docs/api/paddle/linalg/solve_cn.rst +++ b/docs/api/paddle/linalg/solve_cn.rst @@ -3,7 +3,7 @@ solve ------------------------------- -.. py:function:: paddle.linalg.solve(x, y, left=True, name=None) +.. py:function:: paddle.linalg.solve(x, y, left=True, name=None, *, out=None) 计算线性方程组的解。 @@ -25,11 +25,15 @@ solve 参数 ::::::::: - - **x** (Tensor) - 输入的欲进行线性方程组求解的一个或一批方阵（系数矩阵），类型为 Tensor。 ``x`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度，数据类型为 float32， float64。 - - **y** (Tensor) - 输入的欲进行线性方程组求解的右值，类型为 Tensor。 ``y`` 的形状应为 ``[*, M, K]``，其中 ``*`` 为零或更大的批次维度，数据类型和 ``x`` 相同。 + - **x** (Tensor) - 输入的欲进行线性方程组求解的一个或一批方阵（系数矩阵），类型为 Tensor。 ``x`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度，数据类型为 float32， float64。别名 ``A``。 + - **y** (Tensor) - 输入的欲进行线性方程组求解的右值，类型为 Tensor。 ``y`` 的形状应为 ``[*, M, K]``，其中 ``*`` 为零或更大的批次维度，数据类型和 ``x`` 相同。别名 ``B``。 - **left** (bool，可选) - 设置所求解的线性方程组是 :math:`X * Out = Y` 或 :math:`Out * X = Y`。默认值为 True，表示所求解的线性方程组是 :math:`X * Out = Y`。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: diff --git a/docs/api/paddle/linalg/svd_cn.rst b/docs/api/paddle/linalg/svd_cn.rst index a157b85d9a5..ebabc78734e 100644 --- a/docs/api/paddle/linalg/svd_cn.rst +++ b/docs/api/paddle/linalg/svd_cn.rst @@ -3,7 +3,7 @@ svd ------------------------------- -.. py:function:: paddle.linalg.svd(x, full_matrices=False, name=None) +.. py:function:: paddle.linalg.svd(x, full_matrices=False, name=None, *, out=None) 计算一个或一批矩阵的奇异值分解。 @@ -19,10 +19,14 @@ svd 参数 :::::::::::: - - **x** (Tensor) - 输入的欲进行奇异值分解的一个或一批方阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32， float64， complex64， complex128。 - - **full_matrices** (bool) - 是否计算完整的 U 和 V 矩阵，类型为 bool 默认为 False。这个参数会影响 U 和 V 生成的 Shape。 + - **x** (Tensor) - 输入的欲进行奇异值分解的一个或一批矩阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，``M`` 和 ``N`` 为任意正整数，数据类型支持 float32、float64、complex64、complex128。 + - **full_matrices** (bool，可选) - 是否计算完整的 U 和 V 矩阵，类型为 bool 默认为 False。这个参数会影响 U 和 V 生成的 Shape。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (tuple[Tensor, Tensor, Tensor]，可选) - 输出 Tensor 元组，若不为 ``None``，计算结果将保存在该 Tensor 元组中，默认值为 ``None``。 + 返回 :::::::::::: diff --git a/docs/api/paddle/linspace_cn.rst b/docs/api/paddle/linspace_cn.rst index ee8febc1376..db13f988ffc 100644 --- a/docs/api/paddle/linspace_cn.rst +++ b/docs/api/paddle/linspace_cn.rst @@ -3,7 +3,7 @@ linspace ------------------------------- -.. py:function:: paddle.linspace(start, stop, num, dtype=None, name=None) +.. py:function:: paddle.linspace(start, stop, num, dtype=None, name=None, *, out=None, device=None, requires_grad=False) 返回一个 Tensor，Tensor 的值为在区间 start 和 stop 上均匀间隔的 num 个值，输出 Tensor 的长度为 num。 **注意：不进行梯度计算** @@ -12,11 +12,17 @@ linspace :::::::::::: - **start** (int|float|Tensor) – ``start`` 是区间开始的变量，可以是一个 int、float，或是一个 shape 为[0]的 Tensor，该 Tensor 的数据类型可以是 int32，int64，float32，float64。 - - **stop** (int|float|Tensor) – ``stop`` 是区间结束的变量，可以是一个 int、float，或是一个 shape 为[0]的 Tensor，该 Tensor 的数据类型可以是 int32，int64，float32，float64。 - - **num** (int|Tensor) – ``num`` 是给定区间内需要划分的区间数，可以是一个 int，或是一个 shape 为[0]的 Tensor，该 Tensor 的数据类型需为 int32。 + - **stop** (int|float|Tensor) – ``stop`` 是区间结束的变量，可以是一个 int、float，或是一个 shape 为[0]的 Tensor，该 Tensor 的数据类型可以是 int32，int64，float32，float64。别名 ``end``。 + - **num** (int|Tensor) – ``num`` 是给定区间内需要划分的区间数，可以是一个 int，或是一个 shape 为[0]的 Tensor，该 Tensor 的数据类型需为 int32。别名 ``steps``。 - **dtype** (str|paddle.dtype|np.dtype，可选) – 输出 Tensor 的数据类型，可以是 int32，int64，float32，float64。如果 dtype 的数据类型为 None，输出 Tensor 数据类型为 float32。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **out** (Tensor|None，可选) - 可选的输出 Tensor。若提供，计算结果将保存在该 Tensor 中；该 Tensor 的形状和数据类型必须正确。默认值为 None。 + - **device** (str|paddle.CUDAPlace|paddle.CPUPlace|None，可选) - 输出 Tensor 所在设备。可以是设备字符串、``paddle.CUDAPlace`` 或 ``paddle.CPUPlace``；为 None 时使用当前设备上下文。默认值为 None。 + - **requires_grad** (bool，可选) - 输出 Tensor 是否启用梯度计算。若为 True，则其 ``stop_gradient`` 属性将设为 False。默认值为 False。 + 返回 :::::::::::: 表示等间隔划分结果的 1-D Tensor，该 Tensor 的 shape 大小为 :math:`[num]`，在 num 为 1 的情况下，仅返回包含 start 元素值的 Tensor。 diff --git a/docs/api/paddle/log10_cn.rst b/docs/api/paddle/log10_cn.rst index 9a4a2616e78..94f979347ad 100755 --- a/docs/api/paddle/log10_cn.rst +++ b/docs/api/paddle/log10_cn.rst @@ -3,7 +3,7 @@ log10 ------------------------------- -.. py:function:: paddle.log10(x, name=None) +.. py:function:: paddle.log10(x, name=None, *, out=None) @@ -18,9 +18,13 @@ Log10 激活函数（逐元素计算底为 10 的对数） 参数 :::::::::::: - - **x** (Tensor) – 输入的 Tensor。数据类型为 int32、int64、float16、bfloat16、float32、float64、complex64 或 complex128。 + - **x** (Tensor) – 输入的 Tensor。数据类型为 int32、int64、float16、bfloat16、float32、float64、complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，Log10 算子底为 10 对数输出，数据类型与输入一致。 diff --git a/docs/api/paddle/log1p_cn.rst b/docs/api/paddle/log1p_cn.rst index 0fe64ab7e92..f70b1f0e45e 100644 --- a/docs/api/paddle/log1p_cn.rst +++ b/docs/api/paddle/log1p_cn.rst @@ -3,7 +3,7 @@ log1p ------------------------------- -.. py:function:: paddle.log1p(x, name=None) +.. py:function:: paddle.log1p(x, name=None, *, out=None) 计算 Log1p（自然对数 + 1）结果。 @@ -15,9 +15,13 @@ log1p 参数 :::::::::::: - - **x** (Tensor) – 输入为一个多维的 Tensor，数据类型为 int32，int64，float16，bfloat16，float32， float64， complex64 或 complex128。 + - **x** (Tensor) – 输入为一个多维的 Tensor，数据类型为 int32，int64，float16，bfloat16，float32， float64， complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 计算 ``x`` 的自然对数 + 1 后的 Tensor，数据类型，形状与 ``x`` 一致。 diff --git a/docs/api/paddle/log2_cn.rst b/docs/api/paddle/log2_cn.rst index fd13a948956..ecba2c59e45 100755 --- a/docs/api/paddle/log2_cn.rst +++ b/docs/api/paddle/log2_cn.rst @@ -3,7 +3,7 @@ log2 ------------------------------- -.. py:function:: paddle.log2(x, name=None, *, out) +.. py:function:: paddle.log2(x, name=None, *, out=None) @@ -15,15 +15,15 @@ Log2 激活函数（计算底为 2 的对数） \\Out=log_2x\\ -.. note:: - 别名支持: 参数名 ``input`` 可替代 ``x``; - 参数 ::::::::: - - **x** (Tensor) – 该 OP 的输入为 Tensor。数据类型为 int32，int64，float16，bfloat16，float32， float64， complex64 或 complex128。 - ``别名：input`` + - **x** (Tensor) – 该 OP 的输入为 Tensor。数据类型为 int32，int64，float16，bfloat16，float32， float64， complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **out** (Tensor，可选) - 输出的结果。该参数为仅关键字参数，默认值为 None。 + +关键字参数 +::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: Tensor,Log2 算子底为 2 对数输出，数据类型与输入一致。 diff --git a/docs/api/paddle/logical_and_cn.rst b/docs/api/paddle/logical_and_cn.rst index 3e77c477117..d194f4fb649 100644 --- a/docs/api/paddle/logical_and_cn.rst +++ b/docs/api/paddle/logical_and_cn.rst @@ -3,7 +3,7 @@ logical_and ------------------------------- -.. py:function:: paddle.logical_and(x, y, out=None, name=None) +.. py:function:: paddle.logical_and(x, y, name=None, *, out=None) 逐元素的对 ``x`` 和 ``y`` 进行逻辑与运算。 @@ -25,9 +25,13 @@ logical_and 别名： ``input`` - **y** （Tensor） - 输入的 ``Tensor``，支持的数据类型为 bool, int8, int16, int32, int64, bfloat16, float16, float32, float64, complex64, complex128。 别名： ``other`` - - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``Tensor``，维度 ``x`` 维度相同，存储运算后的结果。 diff --git a/docs/api/paddle/logical_not_cn.rst b/docs/api/paddle/logical_not_cn.rst index 1e9341763b1..921893467d1 100644 --- a/docs/api/paddle/logical_not_cn.rst +++ b/docs/api/paddle/logical_not_cn.rst @@ -3,7 +3,7 @@ logical_not ------------------------------- -.. py:function:: paddle.logical_not(x, out=None, name=None) +.. py:function:: paddle.logical_not(x, name=None, *, out=None) @@ -21,12 +21,16 @@ logical_not - **x** （Tensor） - 逻辑非运算的输入，是一个 Tensor，支持的数据类型为 bool, int8, int16, int32, int64, bfloat16, float16, float32, float64, complex64, complex128。 别名： ``input`` - - **out** （Tensor，可选） - 指定算子输出结果的 Tensor，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选） - 指定算子输出结果的 Tensor，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: -Tensor，与 ``x`` 维度相同，数据类型相同。 +Tensor，与 ``x`` 维度相同。 代码示例 diff --git a/docs/api/paddle/logical_or_cn.rst b/docs/api/paddle/logical_or_cn.rst index 05199ab5693..191de14006b 100644 --- a/docs/api/paddle/logical_or_cn.rst +++ b/docs/api/paddle/logical_or_cn.rst @@ -3,7 +3,7 @@ logical_or ------------------------------- -.. py:function:: paddle.logical_or(x, y, out=None, name=None) +.. py:function:: paddle.logical_or(x, y, name=None, *, out=None) 逐元素的对 ``X`` 和 ``Y`` 进行逻辑或运算。 @@ -25,9 +25,13 @@ logical_or 别名： ``input`` - **y** （Tensor）- 输入的 ``Tensor``，支持的数据类型为 bool, int8, int16, int32, int64, bfloat16, float16, float32, float64, complex64, complex128。 别名： ``other`` - - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``Tensor``，维度 ``x`` 维度相同，存储运算后的结果。 diff --git a/docs/api/paddle/logical_xor_cn.rst b/docs/api/paddle/logical_xor_cn.rst index 5380f1fcac3..7d502567d49 100644 --- a/docs/api/paddle/logical_xor_cn.rst +++ b/docs/api/paddle/logical_xor_cn.rst @@ -3,7 +3,7 @@ logical_xor ------------------------------- -.. py:function:: paddle.logical_xor(x, y, out=None, name=None) +.. py:function:: paddle.logical_xor(x, y, name=None, *, out=None) 逐元素的对 ``X`` 和 ``Y`` 进行逻辑异或运算。 @@ -25,9 +25,13 @@ logical_xor 别名： ``input`` - **y** （Tensor） - 输入的 ``Tensor``，支持的数据类型为 bool, int8, int16, int32, int64, bfloat16, float16, float32, float64, complex64, complex128。 别名： ``other`` - - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **out** （Tensor，可选） - 指定算子输出结果的 ``Tensor``，可以是程序中已经创建的任何 Tensor。默认值为 None，此时将创建新的 Tensor 来保存输出结果。 + 返回 :::::::::::: ``Tensor``，维度 ``x`` 维度相同，存储运算后的结果。 diff --git a/docs/api/paddle/masked_select_cn.rst b/docs/api/paddle/masked_select_cn.rst index 551b86a234b..1046190726e 100644 --- a/docs/api/paddle/masked_select_cn.rst +++ b/docs/api/paddle/masked_select_cn.rst @@ -3,7 +3,7 @@ masked_select ------------------------------- -.. py:function:: paddle.masked_select(x, mask, name=None) +.. py:function:: paddle.masked_select(x, mask, name=None, *, out=None) @@ -15,11 +15,14 @@ masked_select 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，数据类型为 float32，float64，int32 或者 int64。 + - **x** (Tensor) - 输入 Tensor，数据类型为 float16、float32、float64、uint16、int32 或 int64。 别名： ``input`` - **mask** (Tensor) - 用于索引的二进制掩码的 Tensor，数据类型为 bool。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **out** （Tensor，可选） - 指定输出结果的 ``Tensor``，默认值为 None。 + +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 返回 :::::::::::: diff --git a/docs/api/paddle/median_cn.rst b/docs/api/paddle/median_cn.rst index 4d504728abf..bc98436fb21 100644 --- a/docs/api/paddle/median_cn.rst +++ b/docs/api/paddle/median_cn.rst @@ -3,7 +3,7 @@ median ------------------------------- -.. py:function:: paddle.median(x, axis=None, keepdim=False, mode='avg', name=None) +.. py:function:: paddle.median(x, axis=None, keepdim=False, mode='avg', name=None, *, out=None) 沿给定的轴 ``axis`` 计算 ``x`` 中元素的中位数。 @@ -21,6 +21,10 @@ median - **mode** (str，可选) - 当输入 Tensor ``x`` 在 ``axis`` 轴上有偶数个元素时，可选择按照中间两个数的平均值或最小值确定中位数。可选的值是 'avg' 或 'min'。默认为 'avg'。当出现别名替换时， ``mode`` 设置默认参数为 ``min`` 而不是 ``avg``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::: Tensor 或 (Tensor, Tensor)。 diff --git a/docs/api/paddle/meshgrid_cn.rst b/docs/api/paddle/meshgrid_cn.rst index e57f4976ef7..c4d898b0709 100644 --- a/docs/api/paddle/meshgrid_cn.rst +++ b/docs/api/paddle/meshgrid_cn.rst @@ -3,7 +3,7 @@ meshgrid ------------------------------- -.. py:function:: paddle.meshgrid(*args, **kargs) +.. py:function:: paddle.meshgrid(*args, name=None, indexing=None) @@ -13,8 +13,9 @@ meshgrid 参数 :::::::::::: - - **args** (Tensor|Tensor 数组) - 输入变量为 k 个一维 Tensor，形状分别为(N1,), (N2,), ..., (Nk, )。支持数据类型为 bfloat16、float16、float32、float64、int32、int64、complex64 和 complex128。 - - **kargs** (可选) - 目前只接受 name 参数（str），具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **args** (Tensor|Tensor 数组) - 输入变量为 k 个一维 Tensor，形状分别为(N1,), (N2,), ..., (Nk, )。支持数据类型为 bfloat16、float16、float32、float64、uint16、int32、int64、complex64 和 complex128。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **indexing** (str，可选) - 索引模式，可选 ``"xy"`` 或 ``"ij"``。默认值为 ``"ij"``。当选择 ``"xy"`` 时，前两个维度的顺序与前两个输入的基数相反；当选择 ``"ij"`` 时，各维度顺序与输入顺序一致。 diff --git a/docs/api/paddle/mm_cn.rst b/docs/api/paddle/mm_cn.rst index 12301f206bb..c368807dfe4 100644 --- a/docs/api/paddle/mm_cn.rst +++ b/docs/api/paddle/mm_cn.rst @@ -3,7 +3,7 @@ mm ------------------------------- -.. py:function:: paddle.mm(input, mat2, name=None, *, out=None) +.. py:function:: paddle.mm(input, mat2, name=None, *, out_dtype=None, out=None) @@ -23,12 +23,13 @@ mm 关键字参数 :::::::::::: - - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + - **out_dtype** (paddle.dtype|None，可选) - 期望的输出数据类型。目前仅支持在动态图中将 CUDA 上数据类型为 float16 或 bfloat16 的 2-D 输入转换为 ``paddle.float32`` 输出，两个输入 Tensor 的数据类型必须相同。默认值为 None。 + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中。该 Tensor 的形状和数据类型必须与预期输出相同。默认值为 ``None``。 返回 :::::::::::: - - Tensor，矩阵相乘后的结果。 + - Tensor，矩阵相乘后的结果。未指定 ``out_dtype`` 时，数据类型与 ``input`` 相同。 :: diff --git a/docs/api/paddle/mod_cn.rst b/docs/api/paddle/mod_cn.rst index f9049f3c6aa..a785947d2de 100644 --- a/docs/api/paddle/mod_cn.rst +++ b/docs/api/paddle/mod_cn.rst @@ -3,7 +3,7 @@ mod ------------------------------- -.. py:function:: paddle.mod(x, y, name=None) +.. py:function:: paddle.mod(x, y, name=None, *, out=None) 逐元素取模算子。公式为： @@ -17,10 +17,14 @@ mod 参数 ::::::::: - - **x** (Tensor) - 多维 Tensor。数据类型为 float16、float32 、float64、int32 或 int64。 - - **y** (Tensor) - 多维 Tensor。数据类型为 float16、float32 、float64、int32 或 int64。 + - **x** (Tensor) - 多维 Tensor。别名 ``input``。数据类型为 bfloat16、float16、float32、float64、int32 或 int64。 + - **y** (Tensor) - 多维 Tensor。别名 ``other``。数据类型为 bfloat16、float16、float32、float64、int32 或 int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: ``Tensor``，存储运算后的结果。如果 x 和 y 有不同的 shape 且是可以广播的，返回 Tensor 的 shape 是 x 和 y 经过广播后的 shape。如果 x 和 y 有相同的 shape，返回 Tensor 的 shape 与 x，y 相同。 diff --git a/docs/api/paddle/mode_cn.rst b/docs/api/paddle/mode_cn.rst index bbb8630525e..74e1ae6a9c4 100644 --- a/docs/api/paddle/mode_cn.rst +++ b/docs/api/paddle/mode_cn.rst @@ -11,7 +11,7 @@ mode ::::::::: - **x** （Tensor） - 输入的多维 ``Tensor``，支持的数据类型：float32、float64、int32、int64。别名 ``input``。 - **axis** （int，可选） - 指定对输入 Tensor 进行运算的轴，``axis`` 的有效范围是[-R, R），R 是输入 ``x`` 的 Rank， ``axis`` 为负时与 ``axis`` + R 等价。默认值为-1。别名 ``dim``。 - - **keepdim** （bool，可选）- 是否保留指定的轴。如果是 True，维度会与输入 x 一致，对应所指定的轴的 size 为 1。否则，由于对应轴被展开，输出的维度会比输入小 1。默认值为 1。 + - **keepdim** （bool，可选）- 是否保留指定的轴。如果是 True，维度会与输入 x 一致，对应所指定的轴的 size 为 1。否则，由于对应轴被展开，输出的维度会比输入小 1。默认值为 False。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 diff --git a/docs/api/paddle/nanquantile_cn.rst b/docs/api/paddle/nanquantile_cn.rst index 54a4982d563..2a3cfa93610 100644 --- a/docs/api/paddle/nanquantile_cn.rst +++ b/docs/api/paddle/nanquantile_cn.rst @@ -3,18 +3,17 @@ nanquantile ------------------------------- -.. py:function:: paddle.nanquantile(x, q, axis=None, keepdim=False, interpolation='linear', name=None, *, out=None) +.. py:function:: paddle.nanquantile(x, q, axis=None, keepdim=False, interpolation='linear', *, out=None) 沿给定的轴 ``axis`` 计算 ``x`` 中元素的分位数, 忽略元素中的 ``NaN`` 。 参数 :::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：bfloat16、float16、float32、float64、int32、int64。别名：``input``。 + - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64、int32、int64。别名：``input``。 - **q** (int|float|list|Tensor) - 待计算的分位数，需要在符合取值范围[0, 1]。如果 ``q`` 是 List 或者 1-D Tensor，其中的每一个 q 分位数都会被计算，并且输出的首维大小与列表或 Tensor 中元素的数量相同。如果 ``q`` 是 0-D Tensor ，则会被当作 float 和 int 对待。 - **axis** (int|list，可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是 int 或内部元素为 int 类型的 list。``axis`` 值应该在范围[-D, D)内，D 是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于 0，则等价于 :math:`axis + D`。如果 ``axis`` 是 list，对给定的轴上的所有元素计算分位数。如果 ``axis`` 是 None，则对 ``x`` 的全部元素计算分位数。默认值为 None。别名：``dim``。 - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留减小的维度。如果 ``keepdim`` 为 True，则输出 Tensor 和 ``x`` 具有相同的维度(减少的维度除外，减少的维度的大小为 1)。否则，输出 Tensor 的形状会在 ``axis`` 上进行 squeeze 操作。默认值为 False。 - **interpolation** (str，可选) - 计算分位数的插值方法，可以是 ``linear`` , ``lower`` , ``higher`` , ``nearest`` 或者 ``midpoint`` 。 默认值为 ``linear`` 。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 :::::::::: diff --git a/docs/api/paddle/nn/LeakyReLU_cn.rst b/docs/api/paddle/nn/LeakyReLU_cn.rst index 18240efc1db..723d0ffc9b2 100644 --- a/docs/api/paddle/nn/LeakyReLU_cn.rst +++ b/docs/api/paddle/nn/LeakyReLU_cn.rst @@ -2,7 +2,7 @@ LeakyReLU ------------------------------- -.. py:class:: paddle.nn.LeakyReLU(negative_slope=0.01, name=None) +.. py:class:: paddle.nn.LeakyReLU(negative_slope=0.01, inplace=False, name=None) LeakyReLU 激活层，创建一个可调用对象以计算输入 ``x`` 的 ``LeakReLU`` 。 @@ -21,6 +21,7 @@ LeakyReLU 激活层，创建一个可调用对象以计算输入 ``x`` 的 ``Lea 参数 :::::::::: - **negative_slope** (float，可选) - :math:`x < 0` 时的斜率。默认值为 0.01。 + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/nn/ReLU_cn.rst b/docs/api/paddle/nn/ReLU_cn.rst index f0bd5427dab..f16626748dd 100644 --- a/docs/api/paddle/nn/ReLU_cn.rst +++ b/docs/api/paddle/nn/ReLU_cn.rst @@ -2,7 +2,7 @@ ReLU ------------------------------- -.. py:class:: paddle.nn.ReLU(name=None) +.. py:class:: paddle.nn.ReLU(inplace=False, name=None) ReLU 激活层（Rectified Linear Unit）。计算公式如下： @@ -14,6 +14,7 @@ ReLU 激活层（Rectified Linear Unit）。计算公式如下： 参数 :::::::::: + - **inplace** (bool，可选) - 是否使用原地操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 diff --git a/docs/api/paddle/nn/init/xavier_normal__cn.rst b/docs/api/paddle/nn/init/xavier_normal__cn.rst index 7af2f55ddc7..138b0dbc5ef 100644 --- a/docs/api/paddle/nn/init/xavier_normal__cn.rst +++ b/docs/api/paddle/nn/init/xavier_normal__cn.rst @@ -3,7 +3,7 @@ xavier_normal\_ ------------------------------- -.. py:class:: paddle.nn.init.xavier_normal_(tensor, gain=1.0) +.. py:function:: paddle.nn.init.xavier_normal_(tensor, gain=1.0, fan_in=None, fan_out=None) 将输入张量的值设置为 Xavier 正常分布的随机数，该操作会直接修改输入张量。 @@ -12,3 +12,5 @@ xavier_normal\_ - **tensor** (Tensor) - 输入张量。 - **gain** (float，可选) - 比例因子，默认值为 1.0。 + - **fan_in** (float|None，可选) - Xavier 初始化的 ``fan_in``。默认从 Tensor 推断。默认值为 None。 + - **fan_out** (float|None，可选) - Xavier 初始化的 ``fan_out``。默认从 Tensor 推断。默认值为 None。 diff --git a/docs/api/paddle/nn/init/xavier_uniform__cn.rst b/docs/api/paddle/nn/init/xavier_uniform__cn.rst index ac8561f3e24..b937d2609b3 100644 --- a/docs/api/paddle/nn/init/xavier_uniform__cn.rst +++ b/docs/api/paddle/nn/init/xavier_uniform__cn.rst @@ -3,7 +3,7 @@ xavier_uniform\_ ------------------------------- -.. py:class:: paddle.nn.init.xavier_uniform_(tensor, gain=1.0) +.. py:function:: paddle.nn.init.xavier_uniform_(tensor, gain=1.0, fan_in=None, fan_out=None) 将输入张量的值设置为 Xavier 均匀分布的随机数，该操作会直接修改输入张量。 @@ -12,3 +12,5 @@ xavier_uniform\_ - **tensor** (Tensor) - 输入张量。 - **gain** (float，可选) - 比例因子，默认值为 1.0。 + - **fan_in** (float|None，可选) - Xavier 初始化的 ``fan_in``。默认从 Tensor 推断。默认值为 None。 + - **fan_out** (float|None，可选) - Xavier 初始化的 ``fan_out``。默认从 Tensor 推断。默认值为 None。 diff --git a/docs/api/paddle/normal_cn.rst b/docs/api/paddle/normal_cn.rst index 0a3b0420f43..829dfcd1a3c 100644 --- a/docs/api/paddle/normal_cn.rst +++ b/docs/api/paddle/normal_cn.rst @@ -3,7 +3,7 @@ normal ------------------------------- -.. py:function:: paddle.normal(mean=0.0, std=1.0, shape=None, name=None) +.. py:function:: paddle.normal(mean=0.0, std=1.0, shape=None, name=None, *, out=None) 返回符合正态分布（均值为 ``mean``，标准差为 ``std`` 的正态随机分布）的随机 Tensor。 @@ -20,10 +20,14 @@ normal 参数 :::::::::: - **mean** (float|complex|Tensor，可选) - 输出 Tensor 的正态分布的平均值。如果 ``mean`` 是 float，则表示输出 Tensor 中所有元素的正态分布的平均值。如果 ``mean`` 是 Tensor (支持的数据类型为 float32、float64、complex64、complex128)，则表示输出 Tensor 中每个元素的正态分布的平均值。默认值为 0.0。 - - **std** (float|Tensor，可选) - 输出 Tensor 的正态分布的标准差。如果 ``std`` 是 float，则表示输出 Tensor 中所有元素的正态分布的标准差。如果 ``std`` 是 Tensor (支持的数据类型为 float32、float64)，则表示输出 Tensor 中每个元素的正态分布的标准差。默认值为 0.0。 - - **shape** (list|tuple|Tensor，可选) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1D Tensor。如果 ``mean`` 或者 ``std`` 是 Tensor，输出 Tensor 的形状和 ``mean`` 或者 ``std`` 相同(此时 ``shape`` 无效)。默认值为 None。 + - **std** (float|Tensor，可选) - 输出 Tensor 的正态分布的标准差。如果 ``std`` 是 float，则表示输出 Tensor 中所有元素的正态分布的标准差。如果 ``std`` 是 Tensor (支持的数据类型为 float32、float64)，则表示输出 Tensor 中每个元素的正态分布的标准差。默认值为 1.0。 + - **shape** (list|tuple|Tensor，可选) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1D Tensor。如果 ``mean`` 或者 ``std`` 是 Tensor，输出 Tensor 的形状和 ``mean`` 或者 ``std`` 相同(此时 ``shape`` 无效)。默认值为 None。参数名别名为 ``size``，例如 ``normal(size=[2, 3], ...)`` 等价于 ``normal(shape=[2, 3], ...)``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中。该 Tensor 的形状和数据类型必须与预期输出相同。默认值为 ``None``。 + 返回 :::::::::: Tensor：符合正态分布（均值为 ``mean``，标准差为 ``std`` 的正态随机分布）的随机 Tensor。 diff --git a/docs/api/paddle/not_equal_cn.rst b/docs/api/paddle/not_equal_cn.rst index 78a246cf9d0..7ef5c07801c 100644 --- a/docs/api/paddle/not_equal_cn.rst +++ b/docs/api/paddle/not_equal_cn.rst @@ -2,7 +2,7 @@ not_equal ------------------------------- -.. py:function:: paddle.not_equal(x, y, name=None) +.. py:function:: paddle.not_equal(x, y, name=None, *, out=None) 返回 :math:`x!=y` 逐元素比较 x 和 y 是否相等，相同位置的元素不相同则返回 True，否则返回 False。使用重载算子 ``!=`` 可以有相同的计算函数效果。 @@ -13,11 +13,15 @@ not_equal 参数 :::::::::::: - - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 - - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64。 + - **x** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``input``。 + - **y** (Tensor) - 输入 Tensor，支持的数据类型包括 bool、bfloat16、float16、float32、float64、uint8、int8、int16、int32、int64、complex64、complex128。别名 ``other``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，shape 和输入一致，数据类型为 bool。 diff --git a/docs/api/paddle/optimizer/ASGD_cn.rst b/docs/api/paddle/optimizer/ASGD_cn.rst index e5630a4d0e5..3f9a5852d13 100644 --- a/docs/api/paddle/optimizer/ASGD_cn.rst +++ b/docs/api/paddle/optimizer/ASGD_cn.rst @@ -26,10 +26,10 @@ ASGD 算法的优化器。有关详细信息，请参阅： 参数 :::::::::::: - - **learning_rate** (float|_LRScheduleri，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类。默认值为 0.001。 + - **learning_rate** (float|Tensor|LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值、浮点类型的 Tensor 或 LRScheduler。默认值为 0.001。 - **batch_num** (int，可选) - 完成一个 epoch 所需迭代的次数。默认值为 1。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|Tensor，可选) - 权重衰减系数，是一个 float 类型或者 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 None。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 权重衰减策略。可以是 int 或 float 类型的 L2 正则化系数，或 :ref:`cn_api_paddle_regularizer_L1Decay`、:ref:`cn_api_paddle_regularizer_L2Decay`。若参数已通过 :ref:`cn_api_paddle_ParamAttr` 设置 regularizer，则该参数的设置会被忽略；否则在优化器中生效。默认值为 None，表示不进行正则化。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 - **multi_precision** (bool，可选) – 在基于 GPU 设备的混合精度训练场景中，该参数主要用于保证梯度更新的数值稳定性。设置为 True 时，优化器会针对 FP16 类型参数保存一份与其值相等的 FP32 类型参数备份。梯度更新时，首先将梯度类型提升到 FP32，然后将其更新到 FP32 类型参数备份中。最后，更新后的 FP32 类型值会先转换为 FP16 类型，再赋值给实际参与计算的 FP16 类型参数。默认为 False。 @@ -44,8 +44,8 @@ COPY-FROM: paddle.optimizer.ASGD 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -53,9 +53,13 @@ step() 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -82,8 +86,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.ASGD.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -92,6 +96,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.ASGD.clear_grad diff --git a/docs/api/paddle/optimizer/Adadelta_cn.rst b/docs/api/paddle/optimizer/Adadelta_cn.rst index eac1566700e..79ef91f78ec 100644 --- a/docs/api/paddle/optimizer/Adadelta_cn.rst +++ b/docs/api/paddle/optimizer/Adadelta_cn.rst @@ -3,7 +3,7 @@ Adadelta ------------------------------- -.. py:class:: paddle.optimizer.Adadelta(learning_rate=0.001, epsilon=1e-06, rho=0.95, parameters=None, weight_decay=0.01, grad_clip=None, name=None) +.. py:class:: paddle.optimizer.Adadelta(learning_rate=0.001, epsilon=1e-06, rho=0.95, parameters=None, weight_decay=None, grad_clip=None, name=None) .. note:: @@ -25,19 +25,15 @@ Adadelta 优化器，是对 :ref:`Adagrad ` 的 参数 :::::::::::: - - **learning_rate** (float|_LRScheduleri，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 + - **learning_rate** (float|Tensor|LRScheduler，可选) - 学习率，用于参数更新的计算。可以是浮点值、浮点类型的 Tensor 或 LRScheduler。默认值为 0.001。 - **epsilon** (float，可选) - 保持数值稳定性的短浮点类型值，默认值为 1e-06。 - **rho** (float，可选) - 算法中的衰减率，默认值为 0.95。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|Tensor，可选) - 权重衰减系数，是一个 float 类型或者 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 0.01。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数，可以是待更新 Tensor 的列表或元组；也可以是参数组字典的列表，以为不同参数组指定学习率、权重衰减等选项。参数组中的 ``learning_rate`` 表示基础学习率的缩放比例。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，此时所有参数都将被优化。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 正则化方法。可以是 int 或 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、:ref:`cn_api_paddle_regularizer_L2Decay`。如果参数已经在 :ref:`cn_api_paddle_ParamAttr` 中设置正则化，这里的设置将被忽略；否则该设置生效。默认值为 None，表示没有正则化。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 -Adadelta 优化器出自 `DECOUPLED WEIGHT DECAY REGULARIZATION 论文 `_，用来解决 Adam 优化器中 L2 正则化失效的问题。 - - - 代码示例 :::::::::::: @@ -46,17 +42,21 @@ COPY-FROM: paddle.optimizer.Adadelta 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 @@ -83,8 +83,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Adadelta.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 @@ -92,6 +92,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.Adadelta.clear_grad diff --git a/docs/api/paddle/optimizer/Adagrad_cn.rst b/docs/api/paddle/optimizer/Adagrad_cn.rst index eeeca3350a6..db014937474 100644 --- a/docs/api/paddle/optimizer/Adagrad_cn.rst +++ b/docs/api/paddle/optimizer/Adagrad_cn.rst @@ -3,7 +3,7 @@ Adagrad ------------------------------- -.. py:class:: paddle.optimizer.Adagrad(learning_rate, epsilon=1e-06, parameters=None, weight_decay=None, grad_clip=None, name=None, initial_accumulator_value=0.0) +.. py:class:: paddle.optimizer.Adagrad(learning_rate, epsilon=1e-06, parameters=None, weight_decay=None, grad_clip=None, name=None, initial_accumulator_value=0.0, *, maximize=False) Adaptive Gradient 优化器（自适应梯度优化器，简称 Adagrad）可以针对不同参数样本数不平均的问题，自适应地为各个参数分配不同的学习率。 @@ -27,8 +27,8 @@ Adaptive Gradient 优化器（自适应梯度优化器，简称 Adagrad）可以 - **learning_rate** (float|Tensor) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个值为浮点型的 Tensor。 - **epsilon** (float，可选) - 维持数值稳定性的浮点型值，默认值为 1e-06。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数，可以是待更新 Tensor 的列表或元组；也可以是参数组字典的列表，以为不同参数组指定学习率、权重衰减等选项。参数组中的 ``learning_rate`` 表示基础学习率的缩放比例。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，此时所有参数都将被优化。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 正则化方法。可以是 int 或 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 :ref:`cn_api_paddle_regularizer_L2Decay`。如果一个参数已经在 :ref:`cn_api_paddle_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； 如果没有在 :ref:`cn_api_paddle_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为 None，表示没有正则化。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 @@ -36,6 +36,11 @@ Adaptive Gradient 优化器（自适应梯度优化器，简称 Adagrad）可以 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - **initial_accumulator_value** (float，可选) - moment 累加器的初始值，默认值为 0.0。 +关键字参数 +:::::::::::: + + - **maximize** (bool，可选) - 是否对参数最大化目标函数，而非最小化。默认值为 False。 + 代码示例 :::::::::::: diff --git a/docs/api/paddle/optimizer/AdamW_cn.rst b/docs/api/paddle/optimizer/AdamW_cn.rst index 29b8a7b993d..522b29ed7e2 100755 --- a/docs/api/paddle/optimizer/AdamW_cn.rst +++ b/docs/api/paddle/optimizer/AdamW_cn.rst @@ -3,7 +3,7 @@ AdamW ------------------------------- -.. py:class:: paddle.optimizer.AdamW(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=0.01, lr_ratio=None, apply_decay_param_fun=None, grad_clip=None, lazy_mode=False, multi_precision=False, amsgrad=False, name=None) +.. py:class:: paddle.optimizer.AdamW(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=0.01, use_lowprecision_moment=False, lr_ratio=None, apply_decay_param_fun=None, grad_clip=None, lazy_mode=False, multi_precision=False, amsgrad=False, name=None, *, maximize=False) @@ -33,12 +33,13 @@ AdamW 优化器出自 `DECOUPLED WEIGHT DECAY REGULARIZATION ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 @@ -48,6 +49,11 @@ AdamW 优化器出自 `DECOUPLED WEIGHT DECAY REGULARIZATION `，默认为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **maximize** (bool，可选) - 是否对参数最大化目标函数，而非最小化。默认值为 False。 + 代码示例 :::::::::::: @@ -56,17 +62,21 @@ COPY-FROM: paddle.optimizer.AdamW 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -94,8 +104,8 @@ tuple(optimize_ops, params_grads)，其中 optimize_ops 为参数优化 OP 列 COPY-FROM: paddle.optimizer.AdamW.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 @@ -103,6 +113,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.AdamW.clear_grad diff --git a/docs/api/paddle/optimizer/Adam_cn.rst b/docs/api/paddle/optimizer/Adam_cn.rst index 450995d2207..5c9c81e923b 100755 --- a/docs/api/paddle/optimizer/Adam_cn.rst +++ b/docs/api/paddle/optimizer/Adam_cn.rst @@ -3,7 +3,7 @@ Adam ------------------------------- -.. py:class:: paddle.optimizer.Adam(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=None, grad_clip=None, name=None, lazy_mode=False, multi_precision=False, use_multi_tensor=False, amsgrad=False, name=None) +.. py:class:: paddle.optimizer.Adam(learning_rate=0.001, beta1=0.9, beta2=0.999, epsilon=1e-08, parameters=None, weight_decay=None, grad_clip=None, lazy_mode=False, multi_precision=False, use_multi_tensor=False, amsgrad=False, name=None) @@ -30,20 +30,20 @@ Adam 优化器出自 `Adam 论文 `_ 的第二 参数 :::::::::::: - - **learning_rate** (float|_LRScheduler) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 - - **beta1** (float|Tensor，可选) - 一阶矩估计的指数衰减率，是一个 float 类型或者一个 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 0.9。 - - **beta2** (float|Tensor，可选) - 二阶矩估计的指数衰减率，是一个 float 类型或者一个 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 0.999。 - - **epsilon** (float，可选) - 保持数值稳定性的短浮点类型值，默认值为 1e-08。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 + - **learning_rate** (float|LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 + - **beta1** (float|Tensor，可选) - 一阶矩估计的指数衰减率，是一个 float 类型或者形状为 ``[]``、数据类型为 float32 的 0-D Tensor。默认值为 0.9。 + - **beta2** (float|Tensor，可选) - 二阶矩估计的指数衰减率，是一个 float 类型或者形状为 ``[]``、数据类型为 float32 的 0-D Tensor。默认值为 0.999。 + - **epsilon** (float|Tensor，可选) - 保持数值稳定性的浮点值，可以是 float 类型或者形状为 ``[]``、数据类型为 float32 的 0-D Tensor。默认值为 1e-08。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数，可以是待更新 Tensor 的列表或元组；也可以是参数组字典的列表，以为不同参数组指定学习率、权重衰减等选项。参数组中的 ``learning_rate`` 表示基础学习率的缩放比例。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，此时所有参数都将被优化。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 正则化方法。可以是 int 或 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 :ref:`cn_api_paddle_regularizer_L2Decay`。如果一个参数已经在 :ref:`cn_api_paddle_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； 如果没有在 :ref:`cn_api_paddle_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为 None，表示没有正则化。 - - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 + - **grad_clip** (GradientClipBase，可选) - 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 - **lazy_mode** （bool，可选） - 设为 True 时，仅更新当前具有梯度的元素。官方 Adam 算法有两个移动平均累加器（moving-average accumulators）。累加器在每一步都会更新。在密集模式和稀疏模式下，两条移动平均线的每个元素都会更新。如果参数非常大，那么更新可能很慢。lazy mode 仅更新当前具有梯度的元素，所以它会更快。但是这种模式与原始的算法有不同的描述，可能会导致不同的结果，默认为 False。 - **multi_precision** （bool，可选） - 是否在权重更新期间使用 multi-precision，默认为 False。 - **use_multi_tensor** （bool，可选） - 是否使用 multi-tensor 策略一次性更新所有参数，默认为 False。 - - **amsgrad** （bool，可选） - 是否使用该算法的 AMSGrad 变体 :ref:`On the Convergence of Adam and Beyond `，默认为 False。 + - **amsgrad** （bool，可选） - 是否使用该算法的 AMSGrad 变体，参见论文 `On the Convergence of Adam and Beyond `_ ，默认为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 @@ -56,17 +56,21 @@ COPY-FROM: paddle.optimizer.Adam:code-example2 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -111,8 +115,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Adam.minimize -clear_grad() -'''''''''''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 @@ -120,6 +124,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.Adam.clear_grad @@ -200,7 +208,7 @@ set_state_dict(state_dict) COPY-FROM: paddle.optimizer.Adam.set_state_dict -state_dict(state_dict) +state_dict() ''''''''''''''''''''''''''' 从优化器中获取 state_dict 信息，其中包含所有优化器所需的值，对于 Adam 优化器，包含 beta1，beta2，momentum 等。 diff --git a/docs/api/paddle/optimizer/Lamb_cn.rst b/docs/api/paddle/optimizer/Lamb_cn.rst index 36f9596f55b..a18899e8b94 100755 --- a/docs/api/paddle/optimizer/Lamb_cn.rst +++ b/docs/api/paddle/optimizer/Lamb_cn.rst @@ -3,7 +3,7 @@ Lamb ------------------------------- -.. py:class:: paddle.optimizer.Lamb(learning_rate=0.001, lamb_weight_decay=0.01, beta1=0.9, beta2=0.999, epsilon=1e-06, parameters=None, grad_clip=None, exclude_from_weight_decay_fn=None, name=None) +.. py:class:: paddle.optimizer.Lamb(learning_rate=0.001, lamb_weight_decay=0.01, beta1=0.9, beta2=0.999, epsilon=1e-06, parameters=None, grad_clip=None, exclude_from_weight_decay_fn=None, multi_precision=False, always_adapt=False, name=None) @@ -29,14 +29,16 @@ LAMB（Layer-wise Adaptive Moments optimizer for Batching training）优化器 参数 :::::::::::: - - **learning_rate** (float|Tensor，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个 Tensor，默认值为 0.001。 + - **learning_rate** (float|Tensor，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者数据类型为 float32 的 Tensor，默认值为 0.001。 - **lamb_weight_decay** (float，可选) – LAMB 权重衰减率。默认值为 0.01。 - - **beta1** (float，可选) - 第一个动量估计的指数衰减率。默认值为 0.9。 - - **beta2** (float，可选) - 第二个动量估计的指数衰减率。默认值为 0.999。 - - **epsilon** (float，可选) - 保持数值稳定性的短浮点类型值，默认值为 1e-06。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 + - **beta1** (float|Tensor，可选) - 第一个动量估计的指数衰减率。默认值为 0.9。 + - **beta2** (float|Tensor，可选) - 第二个动量估计的指数衰减率。默认值为 0.999。 + - **epsilon** (float|Tensor，可选) - 保持数值稳定性的浮点值，默认值为 1e-06。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数，可以是待更新 Variable 的列表或元组；也可以是参数组字典的列表，以为不同参数组指定学习率、权重衰减等选项。参数组中的 ``learning_rate`` 表示基础学习率的缩放比例。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，此时所有参数都将被优化。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue `。默认值为 None，此时将不进行梯度裁剪。 - - **exclude_from_weight_decay_fn** (function) - 当某个参数作为输入该函数返回值为 True 时，为该参数跳过权重衰减。 + - **exclude_from_weight_decay_fn** (Callable|None，可选) - 当某个参数作为输入该函数返回值为 True 时，为该参数跳过权重衰减。默认值为 None。 + - **multi_precision** (bool，可选) - 是否在参数更新时使用多精度。默认值为 False。 + - **always_adapt** (bool，可选) - 是否始终使用逐层学习率自适应。默认情况下，对被排除权重衰减的参数跳过自适应；若为 True，则始终启用学习率自适应。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 .. note:: @@ -49,17 +51,21 @@ COPY-FROM: paddle.optimizer.Lamb 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -85,8 +91,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Lamb.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 @@ -94,6 +100,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.Lamb.clear_grad diff --git a/docs/api/paddle/optimizer/Momentum_cn.rst b/docs/api/paddle/optimizer/Momentum_cn.rst index 85dc9598a85..ebadbee7cce 100644 --- a/docs/api/paddle/optimizer/Momentum_cn.rst +++ b/docs/api/paddle/optimizer/Momentum_cn.rst @@ -3,7 +3,7 @@ Momentum ------------------------------- -.. py:class:: paddle.optimizer.Momentum(learning_rate=0.001, momentum=0.9, parameters=None, use_nesterov=False, weight_decay=None, grad_clip=None, name=None) +.. py:class:: paddle.optimizer.Momentum(learning_rate=0.001, momentum=0.9, parameters=None, use_nesterov=False, weight_decay=None, grad_clip=None, multi_precision=False, rescale_grad=1.0, use_multi_tensor=False, name=None) 含有速度状态的 Simple Momentum 优化器。 @@ -23,13 +23,16 @@ Momentum 参数 :::::::::::: - - **learning_rate** (float|_LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 - - **momentum** (float，可选) - 动量因子。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 + - **learning_rate** (float|Tensor|LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值、浮点类型的 Tensor 或者一个 LRScheduler 类，默认值为 0.001。 + - **momentum** (float，可选) - 动量因子。默认值为 0.9. + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。可通过由 dict 构成的参数组列表为不同参数组指定学习率、权重衰减等选项。 - **use_nesterov** (bool，可选) - 赋能牛顿动量，默认值 False。 - - **weight_decay** (float|Tensor，可选) - 权重衰减系数，是一个 float 类型或者 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 0.01。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 权重衰减系数，可以是 L2 正则化系数的 int 或 float，也可以是 :ref:`cn_api_paddle_regularizer_L1Decay` 或 :ref:`cn_api_paddle_regularizer_L2Decay`。若参数已通过 :ref:`cn_api_paddle_ParamAttr` 设置正则化器，则忽略优化器中的设置；否则该设置生效。默认值为 None，即不进行正则化。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 + - **multi_precision** (bool，可选) - 是否在参数更新时使用多精度。默认值为 False。 + - **rescale_grad** (float，可选) - 在更新前与梯度相乘的系数。通常可设为 ``1.0 / batch_size``。默认值为 1.0。 + - **use_multi_tensor** (bool，可选) - 是否使用多 Tensor 策略同时更新全部参数。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 @@ -42,17 +45,21 @@ COPY-FROM: paddle.optimizer.Momentum 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -80,8 +87,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Momentum.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 @@ -89,6 +96,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.Momentum.clear_grad diff --git a/docs/api/paddle/optimizer/Optimizer_cn.rst b/docs/api/paddle/optimizer/Optimizer_cn.rst index 72923ce6957..becfb68497e 100755 --- a/docs/api/paddle/optimizer/Optimizer_cn.rst +++ b/docs/api/paddle/optimizer/Optimizer_cn.rst @@ -3,7 +3,7 @@ Optimizer ------------------------------- -.. py:class:: paddle.optimizer.Optimizer(learning_rate, parameters=None, weight_decay=None, grad_clip=None, name=None) +.. py:class:: paddle.optimizer.Optimizer(learning_rate, parameters=None, weight_decay=None, grad_clip=None, name=None, *, maximize=False) @@ -12,15 +12,20 @@ Optimizer 参数 :::::::::::: - - **learning_rate** (float|_LRSeduler) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 - - **parameters** (list|tuple，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|WeightDecayRegularizer，可选) - 正则化方法。可以是 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 + - **learning_rate** (float|LRScheduler) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个 LRScheduler 类。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。也可传入参数组字典列表，为不同参数组设置学习率、权重衰减等选项；参数组中的学习率表示基础学习率的缩放比例。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 正则化方法。可以是 int 或 float 类型的 L2 正则化系数或者正则化策略：:ref:`cn_api_paddle_regularizer_L1Decay` 、 :ref:`cn_api_paddle_regularizer_L2Decay`。如果一个参数已经在 :ref:`cn_api_paddle_ParamAttr` 中设置了正则化，这里的正则化设置将被忽略； 如果没有在 :ref:`cn_api_paddle_ParamAttr` 中设置正则化，这里的设置才会生效。默认值为 None，表示没有正则化。 - - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 + - **grad_clip** (GradientClipBase，可选) - 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **maximize** (bool，可选) - 是否对参数最大化目标函数，而非最小化。默认值为 False。 + 代码示例 :::::::::::: @@ -36,7 +41,7 @@ step(closure=None) 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 - 执行一次优化器并进行参数更新。 +执行一次优化器并进行参数更新。 **参数** @@ -72,15 +77,19 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Optimizer.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 - 清除需要优化的参数的梯度。 +清除需要优化的参数的梯度。 + +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 **代码示例** diff --git a/docs/api/paddle/optimizer/Rprop_cn.rst b/docs/api/paddle/optimizer/Rprop_cn.rst index 75981acfbd4..49dc0d4dc2a 100644 --- a/docs/api/paddle/optimizer/Rprop_cn.rst +++ b/docs/api/paddle/optimizer/Rprop_cn.rst @@ -3,7 +3,7 @@ Rprop ------------------------------- -.. py:class:: paddle.optimizer.Rprop(learning_rate=0.001, learning_rate_range=(1e-5, 50), parameters=None, etas=(0.5, 1.2), grad_clip=None, name=None) +.. py:class:: paddle.optimizer.Rprop(learning_rate=0.001, learning_rate_range=(1e-5, 50), parameters=None, etas=(0.5, 1.2), grad_clip=None, multi_precision=False, name=None) .. note:: @@ -39,12 +39,13 @@ Rprop 算法的优化器。有关详细信息，请参阅： 参数 :::::::::::: - - **learning_rate** (float|_LRScheduleri，可选) - 初始学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类。默认值为 0.001。 + - **learning_rate** (float|Tensor|LRScheduler，可选) - 初始学习率，用于参数更新的计算。可以是浮点值、浮点类型的 Tensor 或 LRScheduler。默认值为 0.001。 - **learning_rate_range** (tuple，可选) - 学习率的范围。学习率不能小于元组的第一个元素；学习率不能大于元组的第二个元素。默认值为 (1e-5, 50)。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，此时所有参数都将被优化。 - **etas** (tuple，可选) - 用于更新学习率的元组。元组的第一个元素是乘法递减因子；元组的第二个元素是乘法增加因子。默认值为 (0.5, 1.2)。 - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 + - **multi_precision** (bool，可选) - 在基于 GPU 的混合精度训练中，是否保存与 float16 参数等值的 float32 参数副本以保证梯度更新的数值稳定性。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 @@ -56,8 +57,8 @@ COPY-FROM: paddle.optimizer.Rprop 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -65,9 +66,13 @@ step() 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -94,8 +99,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.Rprop.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -104,6 +109,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.Rprop.clear_grad @@ -115,7 +124,7 @@ get_lr() 该 API 只在 `Dygraph <../../user_guides/howto/dygraph/DyGraph.html>`_ 模式下生效。 -获取当前步骤的学习率。当不使用_LRScheduler 时，每次调用的返回值都相同，否则返回当前步骤的学习率。 +获取当前步骤的学习率。当不使用 LRScheduler 时，每次调用的返回值都相同，否则返回当前步骤的学习率。 **返回** diff --git a/docs/api/paddle/optimizer/SGD_cn.rst b/docs/api/paddle/optimizer/SGD_cn.rst index 5a9ffa6565c..4ef2be340c2 100644 --- a/docs/api/paddle/optimizer/SGD_cn.rst +++ b/docs/api/paddle/optimizer/SGD_cn.rst @@ -3,7 +3,7 @@ SGD ------------------------------- -.. py:class:: paddle.optimizer.SGD(learning_rate=0.001, parameters=None, weight_decay=None, grad_clip=None, name=None) +.. py:class:: paddle.optimizer.SGD(learning_rate=0.001, parameters=None, weight_decay=None, grad_clip=None, multi_precision=False, name=None, *, maximize=False) 随机梯度下降算法的优化器。 @@ -16,13 +16,19 @@ SGD 参数 :::::::::::: - - **learning_rate** (float|_LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个_LRScheduler 类，默认值为 0.001。 - - **parameters** (list，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 - - **weight_decay** (float|Tensor，可选) - 权重衰减系数，是一个 float 类型或者 shape 为[1]，数据类型为 float32 的 Tensor 类型。默认值为 0.01。 - - **grad_clip** (GradientClipBase，可选) – 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 + - **learning_rate** (float|LRScheduler，可选) - 学习率，用于参数更新的计算。可以是一个浮点型值或者一个 LRScheduler 类，默认值为 0.001。 + - **parameters** (list|tuple|None，可选) - 指定优化器需要优化的参数。在动态图模式下必须提供该参数；在静态图模式下默认值为 None，这时所有的参数都将被优化。 + - **weight_decay** (int|float|WeightDecayRegularizer|None，可选) - 权重衰减系数，可以是 L2 正则化系数的 int 或 float，也可以是 :ref:`cn_api_paddle_regularizer_L1Decay` 或 :ref:`cn_api_paddle_regularizer_L2Decay`。若参数已通过 :ref:`cn_api_paddle_ParamAttr` 设置正则化器，则忽略优化器中的设置；否则该设置生效。默认值为 None，即不进行正则化。 + - **grad_clip** (GradientClipBase，可选) - 梯度裁剪的策略，支持三种裁剪策略：:ref:`paddle.nn.ClipGradByGlobalNorm ` 、 :ref:`paddle.nn.ClipGradByNorm ` 、 :ref:`paddle.nn.ClipGradByValue ` 。 默认值为 None，此时将不进行梯度裁剪。 + - **multi_precision** (bool，可选) - 是否在参数更新时使用多精度。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + + - **maximize** (bool，可选) - 是否对参数最大化目标函数，而非最小化。默认值为 False。 + 代码示例 @@ -32,8 +38,8 @@ COPY-FROM: paddle.optimizer.SGD 方法 :::::::::::: -step() -''''''''' +step(closure=None) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -41,9 +47,13 @@ step() 执行一次优化器并进行参数更新。 +**参数** + + - **closure** (Callable[[], Tensor], 可选) - 用于评估模型并返回损失的闭包函数。闭包函数应接受 0 个参数并返回 Tensor。适用于需要多次评估损失的优化过程。默认值为 None。 + **返回** -无。 +Tensor 或 None。若传入 closure 参数则返回其输出的损失，否则返回 None。 **代码示例** @@ -70,8 +80,8 @@ minimize(loss, startup_program=None, parameters=None, no_grad_set=None) COPY-FROM: paddle.optimizer.SGD.minimize -clear_grad() -''''''''' +clear_grad(set_to_zero=True) +'''''''''''''''''''''''''''''''''''''''' .. note:: @@ -80,6 +90,10 @@ clear_grad() 清除需要优化的参数的梯度。 +**参数** + + - **set_to_zero** (bool，可选) - 是否将梯度置零。若为 False，则删除梯度。默认值为 True。 + **代码示例** COPY-FROM: paddle.optimizer.SGD.clear_grad diff --git a/docs/api/paddle/outer_cn.rst b/docs/api/paddle/outer_cn.rst index f71af5b65a7..95cc1919b1a 100644 --- a/docs/api/paddle/outer_cn.rst +++ b/docs/api/paddle/outer_cn.rst @@ -3,7 +3,7 @@ outer ------------------------------- -.. py:function:: paddle.outer(x, y, name=None) +.. py:function:: paddle.outer(x, y, name=None, *, out=None) 计算两个 Tensor 的外积。 @@ -20,6 +20,10 @@ outer - **y** (Tensor) - 一个 N 维 Tensor 或者标量 Tensor。别名： ``vec2``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/permute_cn.rst b/docs/api/paddle/permute_cn.rst index 8556dd22de8..514abaa14a4 100644 --- a/docs/api/paddle/permute_cn.rst +++ b/docs/api/paddle/permute_cn.rst @@ -3,7 +3,7 @@ permute ------------------------------- -.. py:function:: paddle.permute(input, dims, name=None) +.. py:function:: paddle.permute(input, *dims) 根据 dims 对输入的多维 Tensor 进行数据重排。返回多维 Tensor 的第 i 维对应输入 Tensor 的 dims[i] 维。 @@ -11,8 +11,7 @@ permute :::::::::::: - **input** (Tensor) - 输入：input:[N_1, N_2, ..., N_k, D]多维 Tensor，可选的数据类型为 bool, float16, bfloat16, float32, float64, int8, int16, int32, int64, uint8, uint16, complex64, complex128。 - - **dims** (list|tuple) - dims 长度必须和 input 的维度相同，并依照 dims 中的数据进行重排。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **dims** (tuple|list|int) - 目标维度顺序。可作为可变长度位置参数传入（如 ``paddle.permute(input, 1, 0, 2)``），也可作为单个 list 或 tuple 传入。dims 的长度必须和 input 的维度相同，并依照 dims 中的数据进行重排。 返回 :::::::::::: diff --git a/docs/api/paddle/prod_cn.rst b/docs/api/paddle/prod_cn.rst index 6ab87c2ef24..fda1e2098c1 100644 --- a/docs/api/paddle/prod_cn.rst +++ b/docs/api/paddle/prod_cn.rst @@ -3,7 +3,7 @@ prod ------------------------------- -.. py:function:: paddle.prod(x, axis=None, keepdim=False, dtype=None, name=None) +.. py:function:: paddle.prod(x, axis=None, keepdim=False, dtype=None, name=None, *, out=None) @@ -15,14 +15,16 @@ prod 参数 :::::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：bfloat16、float16、float32、float64、int32、int64、complex64、complex128。 - 别名： ``input`` - - **axis** (int|list|tuple，可选) - 求乘积运算的维度。如果是 None，则计算所有元素的乘积并返回包含单个元素的 Tensor，否则该参数必须在 :math:`[-x.ndim, x.ndim)` 范围内。如果 :math:`axis[i] < 0`，则维度将变为 :math:`x.ndim + axis[i]`，默认为 None。 - 别名： ``dim`` + - **x** (Tensor) - 输入的 Tensor，数据类型为：bfloat16、float16、float32、float64、int32、int64、complex64、complex128。别名 ``input``。 + - **axis** (int|list|tuple，可选) - 求乘积运算的维度。如果是 None，则计算所有元素的乘积并返回包含单个元素的 Tensor，否则该参数必须在 :math:`[-x.ndim, x.ndim)` 范围内。如果 :math:`axis[i] < 0`，则维度将变为 :math:`x.ndim + axis[i]`，默认为 None。别名 ``dim``。 - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留输入的维度。除非 keepdim 为 True，否则输出 Tensor 的维度将比输入 Tensor 小一维，默认值为 False。 - - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 int32、int64、float32、float64。如果指定了该参数，那么在执行操作之前，输入 Tensor 将被转换为 dtype 类型。这对于防止数据类型溢出非常有用。若参数为空，则输出变量的数据类型和输入变量相同，默认为：None。 + - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float16、bfloat16、float32、float64、int32、int64、complex64、complex128。如果指定了该参数，那么在执行操作之前，输入 Tensor 将被转换为 dtype 类型。这对于防止数据类型溢出非常有用。若参数为空，则输出变量的数据类型和输入变量相同，默认为：None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: 输入 Tensor 在指定 axis 上的累乘的结果。 diff --git a/docs/api/paddle/qr_cn.rst b/docs/api/paddle/qr_cn.rst index cef3336d8fc..813a7a68b2c 100644 --- a/docs/api/paddle/qr_cn.rst +++ b/docs/api/paddle/qr_cn.rst @@ -3,27 +3,46 @@ qr ------------------------------- -.. py:function:: paddle.qr(input, some=True, *, out=None) +.. py:function:: paddle.qr(x, mode='reduced', name=None, *, out=None) -计算一个或一批矩阵的 QR 分解。 +.. note:: -该 API 是 ``paddle.linalg.qr`` 的封装，并提供 ``some`` 参数来控制 QR 分解的返回形式。 + 本 API 支持两种签名方式： + + 1. ``paddle.qr(x, mode='reduced', name=None, *, out=None)``（Paddle 风格）：通过 ``mode`` 字符串参数控制 QR 分解。 + 2. ``paddle.qr(input, some=True, *, out=None)``（PyTorch 风格）：通过 ``some`` 布尔参数控制 QR 分解。 + +计算一个或一批矩阵的正交三角分解，也称 QR 分解（暂不支持反向）。 + +记 :math:`X` 为一个矩阵，则计算的结果为 2 个矩阵 :math:`Q` 和 :math:`R`，则满足公式： + +.. math:: + X = Q * R + +其中，:math:`Q` 是正交矩阵，:math:`R` 是上三角矩阵。 参数 :::::::::::: - - **input** (Tensor) - 输入 Tensor，形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度。 - - **some** (bool，可选) - 控制 QR 分解的行为。若为 ``True``（默认），返回 reduced 的 Q 和 R 矩阵， - 即 Q 的形状为 ``[*, M, K]``，R 的形状为 ``[*, K, N]``，其中 ``K = min(M, N)``。 - 若为 ``False``，返回 complete 的 Q 和 R 矩阵，即 Q 的形状为 ``[*, M, M]``，R 的形状为 ``[*, M, N]`` + - **x** (Tensor)：输入进行正交三角分解的一个或一批矩阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32、float64、complex64、complex128。别名 ``input``, ``A``。 + - **mode** (str，可选)：控制正交三角分解的行为，默认是 ``reduced``，假设 ``x`` 形状应为 ``[*, M, N]`` 和 ``K = min(M, N)``： + 如果 ``mode = "reduced"``，则 :math:`Q` 形状为 ``[*, M, K]`` 和 :math:`R` 形状为 ``[*, K, N]``； + 如果 ``mode = "complete"``，则 :math:`Q` 形状为 ``[*, M, M]`` 和 :math:`R` 形状为 ``[*, M, N]``； + 如果 ``mode = "r"``，则**只返回**缩减的 :math:`R`，其形状为 ``[*, K, N]``。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 :::::::::::: - - **out** (tuple[Tensor, Tensor]，可选) - 输出 (Q, R) 的元组。默认值为 None。 + - **out** (Tensor|tuple，可选) - 指定输出的张量。 + 当 ``mode = "r"`` 时，为一个 Tensor 用于存储 R； + 否则为一个 ``(Q, R)`` 张量元组，默认值为 None。 返回 :::::::::::: -tuple[Tensor, Tensor]，QR 分解后的 (Q, R) 元组。 + - 如果 ``mode = "r"``，返回 Tensor R，即缩减的上三角矩阵。 + - 否则返回 ``QrRetType(Q, R)`` 具名元组： + - Tensor Q，正交三角分解的 Q 正交矩阵。 + - Tensor R，正交三角分解的 R 上三角矩阵。 代码示例 :::::::::::: diff --git a/docs/api/paddle/quantile_cn.rst b/docs/api/paddle/quantile_cn.rst index c3f1f328b2d..bf3ac4e220a 100644 --- a/docs/api/paddle/quantile_cn.rst +++ b/docs/api/paddle/quantile_cn.rst @@ -3,19 +3,23 @@ quantile ------------------------------- -.. py:function:: paddle.quantile(x, q, axis=None, keepdim=False, interpolation='linear', name=None) +.. py:function:: paddle.quantile(x, q, axis=None, keepdim=False, interpolation='linear', name=None, *, out=None) 沿给定的轴 ``axis`` 计算 ``x`` 中元素的分位数。 参数 :::::::::: - - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64、int32、int64。 + - **x** (Tensor) - 输入的 Tensor，数据类型为：float32、float64、int32、int64。别名 ``input``。 - **q** (int|float|list|Tensor) - 待计算的分位数，需要在符合取值范围[0, 1]。如果 ``q`` 是 List 或者 1-D Tensor，其中的每一个 q 分位数都会被计算，并且输出的首维大小与列表或 Tensor 中元素的数量相同。如果 ``q`` 是 0-D Tensor ，则会被当作 float 和 int 对待。 - - **axis** (int|list，可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是 int 或内部元素为 int 类型的 list。``axis`` 值应该在范围[-D, D)内，D 是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于 0，则等价于 :math:`axis + D`。如果 ``axis`` 是 list，对给定的轴上的所有元素计算分位数。如果 ``axis`` 是 None，则对 ``x`` 的全部元素计算分位数。默认值为 None。 + - **axis** (int|list，可选) - 指定对 ``x`` 进行计算的轴。``axis`` 可以是 int 或内部元素为 int 类型的 list。``axis`` 值应该在范围[-D, D)内，D 是 ``x`` 的维度。如果 ``axis`` 或者其中的元素值小于 0，则等价于 :math:`axis + D`。如果 ``axis`` 是 list，对给定的轴上的所有元素计算分位数。如果 ``axis`` 是 None，则对 ``x`` 的全部元素计算分位数。默认值为 None。别名 ``dim``。 - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留减小的维度。如果 ``keepdim`` 为 True，则输出 Tensor 和 ``x`` 具有相同的维度(减少的维度除外，减少的维度的大小为 1)。否则，输出 Tensor 的形状会在 ``axis`` 上进行 squeeze 操作。默认值为 False。 - **interpolation** (str，可选) - 计算分位数的插值方法，可以是 ``linear`` , ``lower`` , ``higher`` , ``nearest`` 或者 ``midpoint`` 。 默认值为 ``linear`` 。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::: ``Tensor``，沿着 ``axis`` 进行分位数计算的结果。与输入数据类型一致。 diff --git a/docs/api/paddle/rand_cn.rst b/docs/api/paddle/rand_cn.rst index 88ea6315ed3..3e3d1b11a63 100644 --- a/docs/api/paddle/rand_cn.rst +++ b/docs/api/paddle/rand_cn.rst @@ -3,16 +3,23 @@ rand ---------------------- -.. py:function:: paddle.rand(shape, dtype=None, name=None) +.. py:function:: paddle.rand(shape, dtype=None, name=None, *, out=None, device=None, pin_memory=False, requires_grad=False) 返回符合均匀分布的、范围在[0, 1)的 Tensor，形状为 ``shape``，数据类型为 ``dtype``。 参数 :::::::::: - - **shape** (list|tuple|Tensor) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1-D Tensor。 - - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float32、float64。当该参数值为 None 时，输出 Tensor 的数据类型为 float32。使用全局默认 dtype（详细信息请见 :ref:`get_default_dtype` ）。默认值为 None。 + - **shape** (list|tuple|Tensor) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1-D Tensor。参数名别名为 ``size``，例如 ``rand(size=[2, 3])`` 等价于 ``rand(shape=[2, 3])``；也可直接以可变长度整数参数传入形状，如 ``rand(2, 3)``。 + - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float32、float64。默认值为 None，此时使用全局默认数据类型（详细信息请见 :ref:`cn_api_paddle_get_default_dtype` ）。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。 + - **pin_memory** (bool，可选) - 若为 True，返回 Tensor 分配在锁页内存中。仅对 CPU Tensor 生效。默认值为 False。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 :::::::::: Tensor：符合均匀分布的范围为[0, 1)的随机 Tensor，形状为 ``shape``，数据类型为 ``dtype``。 diff --git a/docs/api/paddle/randint_like_cn.rst b/docs/api/paddle/randint_like_cn.rst index d1068134fae..717ecacb13c 100644 --- a/docs/api/paddle/randint_like_cn.rst +++ b/docs/api/paddle/randint_like_cn.rst @@ -3,18 +3,24 @@ randint_like ------------------------------- -.. py:function:: paddle.randint_like(x, low=0, high=None, dtype=None, name=None) +.. py:function:: paddle.randint_like(x, low=0, high=None, dtype=None, name=None, *, device=None, pin_memory=False, requires_grad=False) 返回服从均匀分布的、范围在[``low``, ``high``)的随机 Tensor，输出的形状与 x 的形状一致，当数据类型 ``dtype`` 为 None 时（默认），输出的数据类型与 x 的数据类型一致，当数据类型 ``dtype`` 不为 None 时，将输出用户指定的数据类型。当 ``high`` 为 None 时（默认），均匀采样的区间为[0, ``low``)。 参数 :::::::::: - - **x** (Tensor) – 输入的多维 Tensor，数据类型可以是 bool，int32，int64，float16，float32，float64。输出 Tensor 的形状和 ``x`` 相同。如果 ``dtype`` 为 None，则输出 Tensor 的数据类型与 ``x`` 相同。 + - **x** (Tensor) – 输入的多维 Tensor，数据类型可以是 bool，int32，int64，float16，float32，float64。输出 Tensor 的形状和 ``x`` 相同。如果 ``dtype`` 为 None，则输出 Tensor 的数据类型与 ``x`` 相同。别名 ``input``。 - **low** (int，可选) - 要生成的随机值范围的下限，``low`` 包含在范围中。当 ``high`` 为 None 时，均匀采样的区间为[0, ``low``)。默认值为 0。 - **high** (int，可选) - 要生成的随机值范围的上限，``high`` 不包含在范围中。默认值为 None，此时范围是[0, ``low``)。 - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 bool，int32，int64，float16，float32，float64。当该参数值为 None 时，输出 Tensor 的数据类型与输入 Tensor 的数据类型一致。默认值为 None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。为 None 时，默认使用 ``x`` 所在设备。 + - **pin_memory** (bool，可选) - 若为 True，返回 Tensor 分配在锁页内存中。仅对 CPU Tensor 生效。默认值为 False。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 :::::::::: Tensor：从区间[``low``，``high``)内均匀分布采样的随机 Tensor，形状为 ``x.shape``，数据类型为 ``dtype``。 diff --git a/docs/api/paddle/randn_cn.rst b/docs/api/paddle/randn_cn.rst index 69b608df4ca..922fd2e40ac 100644 --- a/docs/api/paddle/randn_cn.rst +++ b/docs/api/paddle/randn_cn.rst @@ -3,7 +3,7 @@ randn ------------------------------- -.. py:function:: paddle.randn(shape, dtype=None, name=None, *, out=None, device=None, requires_grad=False, pin_memory=False) +.. py:function:: paddle.randn(shape, dtype=None, name=None, *, out=None, device=None, pin_memory=False, requires_grad=False) 返回符合标准正态分布（均值为 0，标准差为 1 的正态随机分布）的随机 Tensor，形状为 ``shape``，数据类型为 ``dtype``。 @@ -24,8 +24,8 @@ randn :::::::::::: - **out** (Tensor，可选) - 用于保存输出结果的 Tensor。默认值为 None。 - **device** (PlaceLike|None，可选) - 指定返回 Tensor 所在的设备。默认值为 None，表示使用当前全局设备（可通过 ``paddle.device.set_device`` 设置）。 - - **requires_grad** (bool，可选) - 是否在返回的 Tensor 上记录 autograd 的操作。默认值为 False。 - **pin_memory** (bool，可选) - 如果设置为 True，返回的 Tensor 会分配在锁页内存中。默认值为 False。 + - **requires_grad** (bool，可选) - 是否在返回的 Tensor 上记录 autograd 的操作。默认值为 False。 返回 :::::::::: diff --git a/docs/api/paddle/randn_like_cn.rst b/docs/api/paddle/randn_like_cn.rst index 584635d1acd..c4d95e36692 100644 --- a/docs/api/paddle/randn_like_cn.rst +++ b/docs/api/paddle/randn_like_cn.rst @@ -3,16 +3,21 @@ randn_like ------------------------------- -.. py:function:: paddle.randn_like(x, dtype=None, name=None) +.. py:function:: paddle.randn_like(x, dtype=None, name=None, *, device=None, requires_grad=False) 返回一个与输入张量尺寸相同的张量，其元素服从均值为 0、方差为 1 的标准正态分布。 参数 :::::::::: - - **x** (Tensor) – 输入的多维 Tensor，数据类型可以是 float16，bfloat16，float32，float64，complex64，complex128。输出 Tensor 的形状和 ``x`` 相同。如果 ``dtype`` 为 None，则输出 Tensor 的数据类型与 ``x`` 相同。 + - **x** (Tensor) – 输入的多维 Tensor，数据类型可以是 float16，bfloat16，float32，float64，complex64，complex128。输出 Tensor 的形状和 ``x`` 相同。如果 ``dtype`` 为 None，则输出 Tensor 的数据类型与 ``x`` 相同。别名 ``input``。 - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float16，bfloat16，float32，float64，complex64，complex128。当该参数值为 None 时，输出 Tensor 的数据类型与输入 Tensor 的数据类型一致。默认值为 None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **device** (str|paddle.Place|None，可选) - 创建的 Tensor 所在设备。为 None 时，使用输入 Tensor 所在设备。默认值为 None。 + - **requires_grad** (bool，可选) - 是否计算创建 Tensor 的梯度。默认值为 False。 + 返回 :::::::::: Tensor：服从均值为 0、方差为 1 的标准正态分布 Tensor，形状为 ``x.shape``，数据类型为 ``dtype``。 diff --git a/docs/api/paddle/random/get_rng_state_cn.rst b/docs/api/paddle/random/get_rng_state_cn.rst index 3618023e306..ff17e8c2a0f 100644 --- a/docs/api/paddle/random/get_rng_state_cn.rst +++ b/docs/api/paddle/random/get_rng_state_cn.rst @@ -3,10 +3,15 @@ get_rng_state ------------------------------- -.. py:function:: paddle.random.get_rng_state() +.. py:function:: paddle.random.get_rng_state(device=None) -``paddle.device.cpu.get_rng_state`` 的别名，请参考 :ref:`cn_api_paddle_get_rng_state`。 +获取默认随机数生成器的随机状态。 + +参数 +::::::::: + + - **device** (_CPUPlaceLike|None，可选) - 要获取随机状态的设备。默认值为 None。 返回 ::::::::: -Tensor：CPU 随机数生成器的初始种子值。 +Tensor：随机状态 Tensor。 diff --git a/docs/api/paddle/random/set_rng_state_cn.rst b/docs/api/paddle/random/set_rng_state_cn.rst index d746f64fbc1..4211244941f 100644 --- a/docs/api/paddle/random/set_rng_state_cn.rst +++ b/docs/api/paddle/random/set_rng_state_cn.rst @@ -3,13 +3,14 @@ set_rng_state ------------------------------- -.. py:function:: paddle.random.set_rng_state(new_state) +.. py:function:: paddle.random.set_rng_state(new_state, device=None) -``paddle.device.cpu.set_rng_state`` 的别名，请参考 :ref:`cn_api_paddle_set_rng_state`。 +设置指定设备的随机数生成器状态。 参数 ::::::::: - - **new_state** (Tensor) - 要设置的 CPU 随机数生成器的初始种子值。通过 ``get_rng_state()`` 获得。 + - **new_state** (core.GeneratorState) - 要设置的随机数生成器状态，应由 ``get_rng_state()`` 获得。 + - **device** (DeviceLike，可选) - 要设置随机状态的设备。未指定时使用当前默认设备；可以是设备对象、整数设备 ID 或设备字符串。默认值为 None。 返回 diff --git a/docs/api/paddle/randperm_cn.rst b/docs/api/paddle/randperm_cn.rst index f08e981532e..a216aa1f443 100644 --- a/docs/api/paddle/randperm_cn.rst +++ b/docs/api/paddle/randperm_cn.rst @@ -3,7 +3,7 @@ randperm ------------------------------- -.. py:function:: paddle.randperm(n, dtype="int64", name=None) +.. py:function:: paddle.randperm(n, dtype="int64", name=None, *, out=None, device=None, pin_memory=False, requires_grad=False) 返回一个数值在 0 到 n-1、随机排列的 1-D Tensor，数据类型为 ``dtype``。 @@ -13,6 +13,13 @@ randperm - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 int32、int64、float32、float64。默认值为 int64。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。 + - **pin_memory** (bool，可选) - 若为 True，返回 Tensor 分配在锁页内存中。仅对 CPU Tensor 生效。默认值为 False。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 :::::::::: Tensor：一个数值在 0 到 n-1、随机排列的 1-D Tensor，数据类型为 ``dtype`` 。 diff --git a/docs/api/paddle/row_stack_cn.rst b/docs/api/paddle/row_stack_cn.rst index 9ba489aa91b..ad4637e98c4 100644 --- a/docs/api/paddle/row_stack_cn.rst +++ b/docs/api/paddle/row_stack_cn.rst @@ -3,7 +3,7 @@ row_stack ------------------------------- -.. py:function:: paddle.row_stack(x, name=None) +.. py:function:: paddle.row_stack(x, name=None, *, out=None) :ref:`cn_api_paddle_vstack` 的别名。沿垂直轴堆叠输入 ``x`` 中的所有张量。所有张量必须具有相同的数据类型。 @@ -16,9 +16,13 @@ row_stack 参数 :::::::::::: - - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。 + - **x** (list[Tensor]|tuple[Tensor]) - 输入 ``x`` 可以是张量的 list 或 tuple， ``x`` 中张量的数据类型必须相同。支持的数据类型： ``float16`` 、 ``float32`` 、 ``float64`` 、 ``int8`` 、 ``int32`` 、 ``int64`` 或 ``bfloat16`` 。别名 ``tensors``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，与输入数据类型相同的堆叠张量。 diff --git a/docs/api/paddle/scale_cn.rst b/docs/api/paddle/scale_cn.rst index 0e54add08ea..e36a49b294a 100644 --- a/docs/api/paddle/scale_cn.rst +++ b/docs/api/paddle/scale_cn.rst @@ -3,7 +3,7 @@ scale ------------------------------- -.. py:function:: paddle.scale(x, scale=1.0, bias=0.0, bias_after_scale=True, act=None, name=None) +.. py:function:: paddle.scale(x, scale=1.0, bias=0.0, bias_after_scale=True, act=None, name=None, *, out=None) 对输入 Tensor 进行缩放和偏置，其公式如下： @@ -27,6 +27,10 @@ scale - **act** (str，可选) - 应用于输出的激活函数，如 tanh、softmax、sigmoid、relu 等。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，缩放后的计算结果。 diff --git a/docs/api/paddle/scatter_cn.rst b/docs/api/paddle/scatter_cn.rst index 3babaf0ef72..2fd21139019 100644 --- a/docs/api/paddle/scatter_cn.rst +++ b/docs/api/paddle/scatter_cn.rst @@ -12,7 +12,7 @@ scatter ===== -.. py:function:: paddle.scatter(x, index, updates, overwrite=True, name=None) +.. py:function:: paddle.scatter(x, index, updates, overwrite=True, name=None, out=None) 通过基于 ``updates`` 来更新选定索引 ``index`` 上的输入来获得输出。具体行为如下： @@ -35,6 +35,7 @@ COPY-FROM: paddle.scatter:scatter-example-1 - **updates** （Tensor）- 根据 ``index`` 使用 ``update`` 参数更新输入 ``x``。当 ``index`` 为一维 tensor 时，``updates`` 形状应与输入 ``x`` 相同，并且 ``dim>1`` 的 dim 值应与输入 ``x`` 相同。当 ``index`` 为零维 tensor 时，``updates`` 应该是一个 ``(N-1)-D`` 的 Tensor，并且 ``updates`` 的第 i 个维度应该与 ``x`` 的 ``i+1`` 个维度相同。 - **overwrite** （bool，可选）- 指定索引 ``index`` 相同时，更新输出的方式。如果为 True，则使用覆盖模式更新相同索引的输出，如果为 False，则使用累加模式更新相同索引的输出。默认值为 True。 - **name** （str，可选） - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **out** (Tensor，可选) - 用于引用式传入输出值。动态图下 ``out`` 可以是任意 Tensor，默认值为 ``None``。 返回 ::::::::: @@ -49,7 +50,7 @@ COPY-FROM: paddle.scatter:scatter-example-2 ===== -.. py:function:: paddle.scatter(input, dim, index, src, reduce=None, out=None) +.. py:function:: paddle.scatter(input, dim, index, src=None, reduce=None, out=None, value=None) PyTorch 兼容的 scatter 函数。基于 :ref:`cn_api_paddle_put_along_axis` 实现，等效于 ``paddle.put_along_axis(..., broadcast=False)``。详细的用法见 :ref:`cn_api_paddle_put_along_axis`。 diff --git a/docs/api/paddle/searchsorted_cn.rst b/docs/api/paddle/searchsorted_cn.rst index 36917323956..9da55def69a 100644 --- a/docs/api/paddle/searchsorted_cn.rst +++ b/docs/api/paddle/searchsorted_cn.rst @@ -3,18 +3,24 @@ searchsorted ------------------------------- -.. py:function:: paddle.searchsorted(sorted_sequence, values, out_int32=False, right=False, name=None) +.. py:function:: paddle.searchsorted(sorted_sequence, values, out_int32=False, right=False, name=None, *, side=None, out=None, sorter=None) 根据给定的 ``values`` 在 ``sorted_sequence`` 的最后一个维度查找合适的索引。 参数 :::::::: - **sorted_sequence** (Tensor) - 输入的 N 维或一维 Tensor，支持的数据类型：bfloat16、float16、float32、float64、int32、int64。该 Tensor 的数值在其最后一个维度递增。 - - **values** (Tensor) - 输入的 N 维 Tensor，支持的数据类型：bfloat16、float16、float32、float64、int32、int64。 + - **values** (Tensor) - 输入的 N 维 Tensor，支持的数据类型：bfloat16、float16、float32、float64、int32、int64。别名 ``input``。 - **out_int32** (bool，可选) - 输出的数据类型支持 int32、int64。默认值为 False，表示默认的输出数据类型为 int64。 - **right** (bool，可选) - 根据给定 ``values`` 在 ``sorted_sequence`` 查找对应的上边界或下边界。如果 ``sorted_sequence`` 的值为 nan 或 inf，则返回最内层维度的大小。默认值为 False，表示在 ``sorted_sequence`` 的查找给定 ``values`` 的下边界。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **side** (str|None，可选) - 与 ``right`` 作用相同，但推荐使用该参数。``"left"`` 对应 ``right=False``，``"right"`` 对应 ``right=True``；若其为 ``"left"`` 且 ``right=True``，会报错。默认值为 None。 + - **out** (Tensor|None，可选) - 输出 Tensor。默认值为 None。 + - **sorter** (Tensor|None，可选) - 可选的索引 Tensor，形状应与未排序的 ``sorted_sequence`` 相同；其索引序列应能在最后一维将 ``sorted_sequence`` 升序排序。 + 返回 :::::::: Tensor(与 ``values`` 维度相同)，如果参数 ``out_int32`` 为 False，则返回数据类型为 int64 的 Tensor，否则将返回 int32 的 Tensor。 diff --git a/docs/api/paddle/sin_cn.rst b/docs/api/paddle/sin_cn.rst index 84ebb5f5ea0..038785b4a4e 100644 --- a/docs/api/paddle/sin_cn.rst +++ b/docs/api/paddle/sin_cn.rst @@ -3,7 +3,7 @@ sin ------------------------------- -.. py:function:: paddle.sin(x, name=None, *, out=out) +.. py:function:: paddle.sin(x, name=None, *, out=None) 计算输入的正弦值。 @@ -15,7 +15,7 @@ sin 参数 :::::::::::: - - **x** (Tensor) - 支持任意维度的 Tensor。数据类型为 float32，float64，float16，complex64，complex128。别名 ``input``。 + - **x** (Tensor) - 支持任意维度的 Tensor。数据类型为 float32、float64、float16、bfloat16、uint8、int8、int16、int32、int64、complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 关键字参数 @@ -25,7 +25,7 @@ sin 返回 :::::::::::: -返回类型为 Tensor，数据类型同输入一致。 +返回类型为 Tensor，形状与输入相同；整数类型输入会自动转换为 float32。 代码示例 :::::::::::: diff --git a/docs/api/paddle/slice_scatter_cn.rst b/docs/api/paddle/slice_scatter_cn.rst index 6a67b0198a0..12cd5af4790 100644 --- a/docs/api/paddle/slice_scatter_cn.rst +++ b/docs/api/paddle/slice_scatter_cn.rst @@ -3,13 +3,13 @@ slice_scatter ------------------------------- -.. py:function:: paddle.slice_scatter(x, value, axes=None, starts=None, ends=None, strides=None) +.. py:function:: paddle.slice_scatter(x, value, axes=[0], starts=[0], ends=None, strides=[1]) 沿着 ``axes`` 将 ``value`` 矩阵的值嵌入到 ``x`` 矩阵。返回一个新的 Tensor 而不是视图。 ``axes`` 需要与 ``starts``, ``ends`` 和 ``strides`` 尺寸一致。 .. note:: 此 API 有两种调用方式： - 1. ``paddle.slice_scatter(x, value, axes=None, starts=None, ends=None, strides=None)`` (Paddle 风格)：沿多个维度嵌入 value 张量 + 1. ``paddle.slice_scatter(x, value, axes=[0], starts=[0], ends=None, strides=[1])`` (Paddle 风格)：沿多个维度嵌入 value 张量 2. ``paddle.slice_scatter(input, src, dim=0, start=None, end=None, step=1)`` (PyTorch 风格)：沿单个维度嵌入 src 张量 图示展示了示例二 ——一个形状为 [3, 9] 的张量 x，在 axis 1 上使用 slice scatter 操作，将 [3, 1] 的 value 张量嵌入到指定的范围内。图中显示了原始张量、value 张量以及操作后的结果。 @@ -23,10 +23,10 @@ slice_scatter ::::::::: - **x** (Tensor) - 输入的 Tensor 作为目标矩阵，数据类型为： ``bool``、 ``float16``、 ``float32``、 ``float64``、 ``uint8``、 ``int8``、 ``int16``、 ``int32``、 ``int64``、 ``bfloat16``、 ``complex64``、 ``complex128``。别名 ``input``。 - **value** (Tensor) - 需要插入的值，数据类型为： ``bool``、 ``float16``、 ``float32``、 ``float64``、 ``uint8``、 ``int8``、 ``int16``、 ``int32``、 ``int64``、 ``bfloat16``、 ``complex64``、 ``complex128``。别名 ``src``。 - - **axes** (list|tuple，可选) - 指定沿着哪几个维度嵌入对应的值。别名 ``dim``。 - - **starts** (list|tuple，可选) - 嵌入的起始索引。别名 ``start``。 + - **axes** (list|tuple，可选) - 指定沿着哪几个维度嵌入对应的值。默认值为 ``[0]``。别名 ``dim``。 + - **starts** (list|tuple，可选) - 嵌入的起始索引。默认值为 ``[0]``。别名 ``start``。 - **ends** (list|tuple，可选) - 嵌入的截止索引。别名 ``end``。 - - **strides** (list|tuple，可选) - 嵌入的步长。别名 ``step``。 + - **strides** (list|tuple，可选) - 嵌入的步长。默认值为 ``[1]``。别名 ``step``。 返回 ::::::::: diff --git a/docs/api/paddle/standard_normal_cn.rst b/docs/api/paddle/standard_normal_cn.rst index 214886c337a..ad093ee2811 100644 --- a/docs/api/paddle/standard_normal_cn.rst +++ b/docs/api/paddle/standard_normal_cn.rst @@ -3,16 +3,22 @@ standard_normal ------------------------------- -.. py:function:: paddle.standard_normal(shape, dtype=None, name=None) +.. py:function:: paddle.standard_normal(shape, dtype=None, name=None, *, out=None, device=None, requires_grad=False) 返回符合标准正态分布（均值为 0，标准差为 1 的正态随机分布）的随机 Tensor，形状为 ``shape``，数据类型为 ``dtype``。 参数 :::::::::: - **shape** (list|tuple|Tensor) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1-D Tensor。 - - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float16、bfloat16、float32、float64、complex64、complex128。当该参数值为 None 时，输出 Tensor 的数据类型为 float32。默认值为 None。 + - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float16、bfloat16、float32、float64、complex64、complex128。默认值为 None，此时使用全局默认数据类型（详细信息请见 :ref:`cn_api_paddle_get_default_dtype` ）。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。为 None 时，使用当前默认 Tensor 类型的当前设备。默认值为 None。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 :::::::::: Tensor：符合标准正态分布的随机 Tensor，形状为 ``shape``，数据类型为 ``dtype``。 diff --git a/docs/api/paddle/static/IpuCompiledProgram_cn.rst b/docs/api/paddle/static/IpuCompiledProgram_cn.rst index 12ba0eb556a..d9450f1275e 100644 --- a/docs/api/paddle/static/IpuCompiledProgram_cn.rst +++ b/docs/api/paddle/static/IpuCompiledProgram_cn.rst @@ -4,7 +4,7 @@ IpuCompiledProgram ------------------------------- -.. py:class:: paddle.static.IpuCompiledProgram(program, scope=None, ipu_strategy=None) +.. py:class:: paddle.static.IpuCompiledProgram(program=None, scope=None, ipu_strategy=None) IpuCompiledProgram 将输入的 Program 转换和优化成 IPU 所需要的形式，例如：前向图提取、计算图转化、无用的 scale 算子删除等。 @@ -26,8 +26,8 @@ COPY-FROM: paddle.static.IpuCompiledProgram 方法 :::::::::::: -compile(self, feed_list, fetch_list) -''''''''' +compile(feed_list, fetch_list) +'''''''''''''''''''''''''''''''''''''' 将 Program 进行编译，以便在 ipu 上运行。用户可以通过 ``feed_list`` 、``fetch_list`` 传入计算图输入和输出的名字。 diff --git a/docs/api/paddle/static/append_backward_cn.rst b/docs/api/paddle/static/append_backward_cn.rst index 6ea55ee1cb7..a2acf222514 100644 --- a/docs/api/paddle/static/append_backward_cn.rst +++ b/docs/api/paddle/static/append_backward_cn.rst @@ -4,7 +4,7 @@ append_backward ------------------------------- -.. py:function:: paddle.static.append_backward(loss, parameter_list=None, no_grad_set=None, callbacks=None) +.. py:function:: paddle.static.append_backward(loss, parameter_list=None, no_grad_set=None, callbacks=None, checkpoints=None, distop_context=None) @@ -20,13 +20,16 @@ append_backward :::::::::::: - **loss** (Tensor) - 表示网络损失的 Tensor 。 - - **parameter_list** （list [Tensor|str]，可选）- 指定优化器需要更新的参数或参数名称列表。如果为 ``None``，则将更新所有参数。默认值为 ``None``。 - - **no_grad_set** （set [Tensor|str]，可选）- 在 ``block0`` ( :ref:`api_guide_Block` ) 中要忽略梯度的 Tensor 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 Tensor 的名字都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None``。 - - **callbacks** （list [callable object]，可选）- 回调函数列表。用于在反向传播构建中执行一些自定义作业。每次将新的梯度 OP 添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数：:ref:`api_guide_Block` 和 ``context`` 。 :ref:`api_guide_Block` 是将被添加到新梯度算子的块。``context`` 是一个映射，其键是梯度 Tensor 名，值是对应的原始 Tensor。除此之外，``context`` 还有另一个特殊的键值对：键是字符串 ``__ current_op_desc__``，值是刚刚触发可调用对象的梯度 OP 的 ``op_desc``。默认值为 ``None``。 + - **parameter_list** (list[Tensor|str]|tuple[Tensor|str]，可选) - 指定优化器需要更新的参数或参数名称列表。如果为 ``None``，则将更新所有参数。默认值为 ``None``。 + - **no_grad_set** (set[Tensor|str]，可选) - 在 ``block0`` ( :ref:`api_guide_Block` ) 中要忽略梯度的 Tensor 名称集合。所有 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的 Tensor 名称都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认集合中。默认值为 ``None``。 + - **callbacks** (list[callable object]|tuple[callable object]，可选) - 回调函数列表或元组。用于在反向传播构建中执行一些自定义作业。每次将新的梯度 OP 添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数：:ref:`api_guide_Block` 和 ``context``。:ref:`api_guide_Block` 是将被添加到新梯度算子的块。``context`` 是一个映射，其键是梯度 Tensor 名，值是对应的原始 Tensor。除此之外，``context`` 还有另一个特殊的键值对：键是字符串 ``__current_op_desc__``，值是刚刚触发可调用对象的梯度 OP 的 ``op_desc``。默认值为 ``None``。该参数在 PIR 模式中已弃用。 + - **checkpoints** (list[Tensor]|None，可选) - 检查点 Tensor 列表。默认值为 None。 + - **distop_context** (DistributedContext|None，可选) - 分布式算子上下文。默认值为 None。 返回 :::::::::::: - list[(Tensor , Tensor)]，参数及其梯度 Tensor 的元组的列表。元组的第一个值为参数，第二个值为该参数的梯度 Tensor 。 + + 当 ``checkpoints`` 为 None 或空列表时，返回 list[(Tensor, Tensor)]，即参数及其梯度 Tensor 的元组列表。元组的第一个值为参数，第二个值为该参数的梯度 Tensor。当传入非空 ``checkpoints`` 时，返回 ``(params_and_grads, checkpoint_names)``，其中 ``checkpoint_names`` 为检查点名称列表。 代码示例 :::::::::::: diff --git a/docs/api/paddle/static/nn/batch_norm_cn.rst b/docs/api/paddle/static/nn/batch_norm_cn.rst index d018ba31276..c1e0e005de2 100644 --- a/docs/api/paddle/static/nn/batch_norm_cn.rst +++ b/docs/api/paddle/static/nn/batch_norm_cn.rst @@ -4,7 +4,7 @@ batch_norm ------------------------------- -.. py:function:: paddle.static.nn.batch_norm(input, act=None, is_test=False, momentum=0.9, epsilon=1e-05, param_attr=None, bias_attr=None, data_layout='NCHW', in_place=False, name=None, moving_mean_name=None, moving_variance_name=None, do_model_average_for_mean_and_var=False, use_global_stats=False) +.. py:function:: paddle.static.nn.batch_norm(input, act=None, is_test=False, momentum=0.9, epsilon=1e-05, param_attr=None, bias_attr=None, data_layout='NCHW', in_place=False, name=None, moving_mean_name=None, moving_variance_name=None, do_model_average_for_mean_and_var=True, use_global_stats=False) @@ -49,19 +49,19 @@ moving_mean 和 moving_var 是训练过程中统计得到的全局均值和方 :::::::::::: - **input** (Tensor) - batch_norm 算子的输入特征，是一个 Tensor 类型，输入维度可以是 2, 3, 4, 5。数据类型：float16, float32, float64。 - - **act** （string）- 激活函数类型，可以是 leaky_realu、relu、prelu 等。默认：None。 - - **is_test** （bool） - 指示它是否在测试阶段，非训练阶段使用训练过程中统计到的全局均值和全局方差。默认：False。 - - **momentum** （float|Tensor）- 此值用于计算 moving_mean 和 moving_var，是一个 float 类型或者一个 shape 为[1]，数据类型为 float32 的 Tensor 类型。更新公式为：:math:`moving\_mean = moving\_mean * momentum + new\_mean * (1. - momentum)` ， :math:`moving\_var = moving\_var * momentum + new\_var * (1. - momentum)`，默认：0.9。 - - **epsilon** （float）- 加在分母上为了数值稳定的值。默认：1e-5。 + - **act** (string) - 激活函数类型，可以是 linear、relu、prelu 等。默认：None。 + - **is_test** (bool) - 指示它是否在测试阶段，非训练阶段使用训练过程中统计到的全局均值和全局方差。默认：False。 + - **momentum** (float|Tensor) - 此值用于计算 moving_mean 和 moving_var，是一个 float 类型或者一个 shape 为 ``[]`` 的 0-D、数据类型为 float32 的 Tensor。更新公式为：:math:`moving\_mean = moving\_mean * momentum + new\_mean * (1. - momentum)` ， :math:`moving\_var = moving\_var * momentum + new\_var * (1. - momentum)`，默认：0.9。 + - **epsilon** (float) - 加在分母上为了数值稳定的值。默认：1e-5。 - **param_attr** (ParamAttr|None)：指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。batch_norm 算子默认的权重初始化是 1.0。 - - **bias_attr** （ParamAttr|None）- 指定偏置参数属性的对象。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。batch_norm 算子默认的偏置初始化是 0.0。 - - **data_layout** （string) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度。默认值："NCHW"。 - - **in_place** （bool）- batch_norm 的输出复用输入的 tensor，可以节省显存。默认：False。 + - **bias_attr** (ParamAttr|None) - 指定偏置参数属性的对象。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。batch_norm 算子默认的偏置初始化是 0.0。 + - **data_layout** (string) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCHW"和"NHWC"。N 是批尺寸，C 是通道数，H 是特征高度，W 是特征宽度。默认值："NCHW"。 + - **in_place** (bool) - batch_norm 的输出复用输入的 tensor，可以节省显存。默认：False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - - **moving_mean_name** （string）- moving_mean 的名称，存储全局均值。如果将其设置为 None, ``batch_norm`` 将随机命名全局均值；否则，``batch_norm`` 将命名全局均值为 ``moving_mean_name``。默认：None。 - - **moving_variance_name** （string）- moving_variance 的名称，存储全局变量。如果将其设置为 None, ``batch_norm`` 将随机命名全局方差；否则，``batch_norm`` 将命名全局方差为 ``moving_variance_name``。默认：None。 - - **do_model_average_for_mean_and_var** （bool，默认 False）- 是否为 mean 和 variance 做模型均值。 - - **use_global_stats** （bool） – 是否使用全局均值和方差。在预测或测试模式下，将 use_global_stats 设置为 true 或将 is_test 设置为 true，并且行为是等效的。在训练模式中，当设置 use_global_stats 为 True 时，在训练期间也使用全局均值和方差。默认：False。 + - **moving_mean_name** (string) - moving_mean 的名称，存储全局均值。如果将其设置为 None, ``batch_norm`` 将随机命名全局均值；否则，``batch_norm`` 将命名全局均值为 ``moving_mean_name``。默认：None。 + - **moving_variance_name** (string) - moving_variance 的名称，存储全局变量。如果将其设置为 None, ``batch_norm`` 将随机命名全局方差；否则，``batch_norm`` 将命名全局方差为 ``moving_variance_name``。默认：None。 + - **do_model_average_for_mean_and_var** (bool，默认 True) - 是否为 mean 和 variance 做模型均值。 + - **use_global_stats** (bool) - 是否使用全局均值和方差。在预测或测试模式下，将 use_global_stats 设置为 true 或将 is_test 设置为 true，并且行为是等效的。在训练模式中，当设置 use_global_stats 为 True 时，在训练期间也使用全局均值和方差。默认：False。 返回 :::::::::::: diff --git a/docs/api/paddle/static/nn/sparse_embedding_cn.rst b/docs/api/paddle/static/nn/sparse_embedding_cn.rst index 2c684d1ae10..a643a650cff 100644 --- a/docs/api/paddle/static/nn/sparse_embedding_cn.rst +++ b/docs/api/paddle/static/nn/sparse_embedding_cn.rst @@ -4,7 +4,7 @@ sparse_embedding ------------------------------- -.. py:function:: paddle.static.nn.sparse_embedding(input, size, padding_idx=None, is_test=False, entry=None, table_class="CommonSparseTable", param_attr=None, dtype='float32') +.. py:function:: paddle.static.nn.sparse_embedding(input, size, padding_idx=None, is_test=False, entry=None, table_class="MemorySparseTable", param_attr=None, dtype='float32', slot=None) 在飞桨参数服务器模式的大规模稀疏训练中作为 embedding lookup 层的算子，而不是使用 paddle.nn.functional.embedding。 @@ -62,11 +62,12 @@ sparse_embedding - **input** (Variable) - 存储 id 信息的 Tensor，数据类型必须为：int64，输入的 shape 最后一维须为 1。input 中的 id 必须满足 ``0 <= id < size[0]`` 。 - **size** (tuple|list) - embedding 矩阵的维度(vocab_size，emb_size)。必须包含两个元素，第一个元素为 vocab_size(词表大小)，第二个为 emb_size（embedding 层维度）。大规模稀疏场景下，参数规模初始为 0，会随着训练的进行逐步扩展，因此如果 vocab_size 暂时无用，其值可以为任意整数，emb_size 则为词嵌入权重参数的维度配置。 - **padding_idx** (int|long|None，可选) - padding_idx 需在区间 ``[-vocab_size, vocab_size)`` ，否则不生效， ``padding_idx < 0`` 时，padding_idx 会被改成 ``vocab_size + padding_idx`` ，input 中等于 padding_index 的 id 对应的 embedding 信息会被设置为 0，且这部分填充数据在训练时将不会被更新。如果为 None，不作处理，默认为 None。 - - **is_test** (bool，可选) - 表示训练/预测模式。在预测模式(is_test=False)下，遇到不存在的特征，不会初始化及创建，会直接以 0 填充后返回。默认值为 False。 + - **is_test** (bool，可选) - 表示训练/预测模式。在预测模式(is_test=True)下，遇到不存在的特征，不会初始化及创建，会直接以 0 填充后返回。默认值为 False。 - **entry** (str，可选) - 准入策略配置，目前支持概率准入 ProbabilityEntry、频次准入 CountFilterEntry 和曝光点击准入 ShowClickEntry。默认为 None。 - - **table_class** (str，可选) - 稀疏表的类型，其值可以为 CommonSparseTable、SSDSparseTable 和 MemorySparseTable。默认为 CommonSparseTable。 + - **table_class** (str，可选) - 稀疏表的类型，其值可以为 CommonSparseTable、SSDSparseTable 和 MemorySparseTable。默认为 MemorySparseTable。 - **param_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_paddle_ParamAttr` 。此外，可以通过 ``param_attr`` 参数加载用户自定义或预训练的词向量。只需将本地词向量转为 numpy 数据格式，且保证本地词向量的 shape 和 embedding 的 ``size`` 参数一致，然后使用 :ref:`cn_api_paddle_to_tensor` 进行初始化，即可实现加载自定义或预训练的词向量。 - - **dtype** (str) - 输出 Tensor 的数据类型，数据类型必须为：float32 或 float64，默认为 float32。 + - **dtype** (str，可选) - 输出 Tensor 的数据类型，数据类型必须为：float32 或 float64，默认为 float32。 + - **slot** (int|None，可选) - 稀疏查找表使用的 slot 属性。为 None 时使用 0。默认值为 None。 返回 :::::::: diff --git a/docs/api/paddle/static/normalize_program_cn.rst b/docs/api/paddle/static/normalize_program_cn.rst index 5f726a4cd3a..e6d83705907 100644 --- a/docs/api/paddle/static/normalize_program_cn.rst +++ b/docs/api/paddle/static/normalize_program_cn.rst @@ -4,7 +4,7 @@ normalize_program ------------------------------- -.. py:function:: paddle.static.normalize_program(program, feed_vars, fetch_vars) +.. py:function:: paddle.static.normalize_program(program, feed_vars, fetch_vars, **kwargs) @@ -14,9 +14,11 @@ normalize_program 参数 :::::::::::: - - **program** - 指定想要优化的 program。 + - **program** (Program) - 指定想要优化的 program。 - **feed_vars** (Variable | list[Variable]) – 模型的输入变量。 - **fetch_vars** (Variable | list[Variable]) – 模型的输出变量。 + - **kwargs** - 支持键 ``skip_prune_program``。 + - **skip_prune_program** (bool，可选) - 是否跳过 program 裁剪。默认值为 False。 返回 :::::::::::: diff --git a/docs/api/paddle/strided_slice_cn.rst b/docs/api/paddle/strided_slice_cn.rst index 37623c66a3a..11fa5bcbdde 100644 --- a/docs/api/paddle/strided_slice_cn.rst +++ b/docs/api/paddle/strided_slice_cn.rst @@ -2,7 +2,7 @@ strided_slice ------------------------------- -.. py:function:: paddle.strided_slice(x, axes, starts, ends, strides, name) +.. py:function:: paddle.strided_slice(x, axes, starts, ends, strides, name=None) @@ -48,7 +48,7 @@ strided_slice 算子。 :::::::::::: - - **x** （Tensor）- 多维 ``Tensor``，数据类型为 ``bool``, ``float32``，``float64``，``int32``，或 ``int64``。 + - **x** （Tensor）- 多维 ``Tensor``，数据类型为 ``bool``、``float16``、``float32``、``float64``、``int32`` 或 ``int64``。 - **axes** （list|tuple）- 数据类型是 ``int32``。表示进行切片的轴。 - **starts** （list|tuple|Tensor）- 数据类型是 ``int32``。如果 ``starts`` 的类型是 list 或 tuple，它的元素可以是整数或者形状为[]的 ``0-D Tensor``。如果 ``starts`` 的类型是 ``Tensor``，则是 1-D ``Tensor``。表示在各个轴上切片的起始索引值。 - **ends** （list|tuple|Tensor）- 数据类型是 ``int32``。如果 ``ends`` 的类型是 list 或 tuple，它的元素可以是整数或者形状为[]的 ``0-D Tensor``。如果 ``ends`` 的类型是 ``Tensor``，则是 1-D ``Tensor``。表示在各个轴上切片的结束索引值。 diff --git a/docs/api/paddle/sum_cn.rst b/docs/api/paddle/sum_cn.rst index 7a6892643c9..92aac0e2e07 100644 --- a/docs/api/paddle/sum_cn.rst +++ b/docs/api/paddle/sum_cn.rst @@ -3,7 +3,14 @@ sum ------------------------------- -.. py:function:: paddle.sum(x, axis=None, dtype=None, keepdim=False, name=None) +.. py:function:: paddle.sum(x, axis=None, dtype=None, keepdim=False, name=None, *, out=None) + +.. note:: + + 本 API 支持两种签名： + + 1. ``paddle.sum(x, axis=None, dtype=None, keepdim=False, name=None, *, out=None)`` （Paddle 风格）。 + 2. ``paddle.sum(input, dim=None, keepdim=False, dtype=None, *, out=None)`` （PyTorch 风格）。 对指定维度上的 Tensor 元素进行求和运算，并输出相应的计算结果。 @@ -21,6 +28,11 @@ sum - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出变量的数据类型。若参数为空，则输出变量的数据类型和输入变量相同，默认值为 None。 - **keepdim** (bool，可选) - 是否在输出 Tensor 中保留减小的维度。如 keepdim 为 true，否则结果 Tensor 的维度将比输入 Tensor 小，默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: diff --git a/docs/api/paddle/take_along_axis_cn.rst b/docs/api/paddle/take_along_axis_cn.rst index 420f252d370..bd3846a9691 100644 --- a/docs/api/paddle/take_along_axis_cn.rst +++ b/docs/api/paddle/take_along_axis_cn.rst @@ -3,7 +3,7 @@ take_along_axis ------------------------------- -.. py:function:: paddle.take_along_axis(arr, indices, axis, broadcast=True) +.. py:function:: paddle.take_along_axis(arr, indices, axis, broadcast=True, *, out=None) 基于输入索引矩阵，沿着指定 axis 从 arr 矩阵里选取 1d 切片。索引矩阵必须和 arr 矩阵有相同的维度，需要能够 broadcast 与 arr 矩阵对齐。 @@ -20,6 +20,10 @@ take_along_axis 别名： ``dim`` - **broadcast** (bool，可选) - 是否广播 ``index`` 矩阵，默认为 ``True``。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: diff --git a/docs/api/paddle/tanh_cn.rst b/docs/api/paddle/tanh_cn.rst index 2c2d25c6a0c..780c0624715 100644 --- a/docs/api/paddle/tanh_cn.rst +++ b/docs/api/paddle/tanh_cn.rst @@ -3,7 +3,7 @@ tanh ------------------------------- -.. py:function:: paddle.tanh(x, name=None) +.. py:function:: paddle.tanh(x, name=None, *, out=None) tanh 激活函数 @@ -15,12 +15,16 @@ tanh 激活函数 ::::::::: - - **x** (Tensor) - Tanh 算子的输入，多维 Tensor，数据类型为 bfloat16，float16，float32 或 float64。 + - **x** (Tensor) - Tanh 算子的输入，多维 Tensor，数据类型为 bfloat16、float16、float32、float64、uint8、int8、int16、int32 或 int64。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 ::::::::: -tanh 的输出 Tensor，和输入有着相同类型和 shape。 +tanh 的输出 Tensor，和输入具有相同的类型和 shape；整数类型输入会自动转换为 float32。 代码示例 diff --git a/docs/api/paddle/tensordot_cn.rst b/docs/api/paddle/tensordot_cn.rst index 2fba030f78b..5160c8b98f2 100644 --- a/docs/api/paddle/tensordot_cn.rst +++ b/docs/api/paddle/tensordot_cn.rst @@ -3,7 +3,7 @@ tensordot ------------------------------- -.. py:function:: paddle.tensordot(x, y, axes=2, name=None, *, out=None) +.. py:function:: paddle.tensordot(x, y, axes=2, out=None, name=None) Tensor 缩并运算（Tensor Contraction），即沿着 axes 给定的多个轴对两个 Tensor 对应元素的乘积进行加和操作。 @@ -31,11 +31,8 @@ shape = [2,2,3]的 ``res`` 张量为 a,b 两个张量沿着 a 张量的最后一 3. ``axes`` 可以是一个 tuple 或 list，其中包含一个或两个一维的整数 tuple|list|Tensor。如果 ``axes`` 包含一个 tuple|list|Tensor，则对 ``x`` 和 ``y`` 的相同轴做缩并运算，具体轴下标由该 tuple|list|Tensor 中的整数值指定。如果 ``axes`` 包含两个 tuple|list|Tensor，则第一个指定 ``x`` 做缩并运算的轴下标，第二个指定 ``y`` 的对应轴下标。如果 ``axes`` 包含两个以上的 tuple|list|Tensor，只有前两个会被作为轴下标序列使用，其它的将被忽略。 4. ``axes`` 可以是一个 Tensor，这种情况下该 Tensor 会被转换成 list，然后应用前述规则确定做缩并运算的轴。请注意，输入 Tensor 类型的 ``axes`` 只在动态图模式下可用。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 - -关键字参数 -:::::::::::: - **out** (Tensor，可选) - 输出 Tensor。默认值为 None。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 :::::::::::: diff --git a/docs/api/paddle/uniform_cn.rst b/docs/api/paddle/uniform_cn.rst index 7cb7a45cf4d..65f5a987f58 100644 --- a/docs/api/paddle/uniform_cn.rst +++ b/docs/api/paddle/uniform_cn.rst @@ -3,7 +3,7 @@ uniform ------------------------------- -.. py:function:: paddle.uniform(shape, dtype=None, min=-1.0, max=1.0, seed=0, name=None) +.. py:function:: paddle.uniform(shape, dtype=None, min=0, max=1.0, seed=0, name=None, *, out=None, device=None, requires_grad=False) @@ -22,12 +22,18 @@ uniform :::::::::::: - **shape** (list|tuple|Tensor) - 生成的随机 Tensor 的形状。如果 ``shape`` 是 list、tuple，则其中的元素可以是 int，或者是形状为[]且数据类型为 int32、int64 的 0-D Tensor。如果 ``shape`` 是 Tensor，则是数据类型为 int32、int64 的 1-D Tensor。 - - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float32、float64。默认值为 None。 - - **min** (float|int，可选) - 要生成的随机值范围的下限，min 包含在范围中。支持的数据类型：float、int。默认值为-1.0。 + - **dtype** (str|paddle.dtype|np.dtype，可选) - 输出 Tensor 的数据类型，支持 float32、float64、complex64、complex128。默认值为 None，此时使用全局默认数据类型，详细信息请参见 :ref:`cn_api_paddle_get_default_dtype` 。 + - **min** (float|int，可选) - 要生成的随机值范围的下限，min 包含在范围中。支持的数据类型：float、int。默认值为 0。 - **max** (float|int，可选) - 要生成的随机值范围的上限，max 不包含在范围中。支持的数据类型：float、int。默认值为 1.0。 - **seed** (int，可选) - 随机种子，用于生成样本。0 表示使用系统生成的种子。注意如果种子不为 0，该操作符每次都生成同样的随机数。支持的数据类型：int。默认为 0。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **out** (Tensor，可选) - 输出 Tensor。 + - **device** (PlaceLike|None，可选) - 返回 Tensor 的期望设备。为 None 时使用当前设备。默认值为 None。 + - **requires_grad** (bool，可选) - 是否由自动微分记录返回 Tensor 上的操作。默认值为 False。 + 返回 :::::::::::: diff --git a/docs/api/paddle/utils/cpp_extension/get_build_directory_cn.rst b/docs/api/paddle/utils/cpp_extension/get_build_directory_cn.rst index 693ddb63354..c24f17fe1de 100644 --- a/docs/api/paddle/utils/cpp_extension/get_build_directory_cn.rst +++ b/docs/api/paddle/utils/cpp_extension/get_build_directory_cn.rst @@ -3,9 +3,14 @@ get_build_directory ------------------------------- -.. py:function:: paddle.utils.cpp_extension.get_build_directory() +.. py:function:: paddle.utils.cpp_extension.get_build_directory(verbose=False) -此接口返回编译自定义 OP 时生成动态链接库所在的 build 目录路径。此目录可以通过 ``export PADDLE_EXTENSION_DIR=XXX`` 来设置。若未设定，则默认使用 ``~/.cache/paddle_extension`` 作为 build 目录。 +此接口返回编译自定义 OP 时生成动态链接库所在的 build 目录路径。此目录可以通过 ``export PADDLE_EXTENSION_DIR=XXX`` 来设置。若未设定，则默认使用 ``~/.cache/paddle_extensions`` 作为 build 目录。 + +参数 +:::::::::::: + + - **verbose** (bool，可选) - 当未设置 ``PADDLE_EXTENSION_DIR`` 时，是否打印所使用的默认目录信息。默认值为 False。 返回 diff --git a/docs/api/paddle/utils/cpp_extension/load_cn.rst b/docs/api/paddle/utils/cpp_extension/load_cn.rst index e76e16557c4..734f78a0a2f 100644 --- a/docs/api/paddle/utils/cpp_extension/load_cn.rst +++ b/docs/api/paddle/utils/cpp_extension/load_cn.rst @@ -3,7 +3,7 @@ load ------------------------------- -.. py:function:: paddle.utils.cpp_extension.load(name, sources, extra_cxx_cflags=None, extra_cuda_cflags=None, extra_ldflags=None, extra_include_paths=None, build_directory=None, verbose=False) +.. py:function:: paddle.utils.cpp_extension.load(name, sources, extra_cxx_cflags=None, extra_cuda_cflags=None, extra_ldflags=None, extra_include_paths=None, extra_library_paths=None, build_directory=None, verbose=False) 此接口将即时编译（Just-In-Time）传入的自定义 OP 对应的 cpp 和 cuda 源码文件，返回一个包含自定义算子 API 的 ``Module`` 对象。 @@ -49,8 +49,9 @@ load - **extra_cuda_cflags** (list[str]，可选) - 用于指定编译 cuda 源文件时额外的编译选项。默认情况下，Paddle 框架相关的必要选项均已被隐式地包含；``nvcc`` 相关的编译选项请参考：`CUDA Compiler Driver NVCC `_ 。默认值为 None 。 - **extra_ldflags** (list[str]，可选) - 用于指定编译自定义 OP 时额外的链接选项。GCC 支持的链接选项请参考：`GCC Link Options `_ 。默认值为 None 。 - **extra_include_paths** (list[str]，可选) - 用于指定编译 cpp 或 cuda 源文件时，额外的头文件搜索目录。默认情况下，Paddle 框架相关头文件所在目录 ``site-packages/paddle/include`` 已被隐式地包含。默认值为 None 。 + - **extra_library_paths** (list[str]，可选) - 用于指定编译自定义 OP 时额外的库文件搜索目录。默认情况下，Paddle 框架相关库文件所在目录 ``site-packages/paddle/libs`` 已被隐式地包含。默认值为 None 。 - **build_directory** (str，可选) - 用于指定存放生成动态链接库的目录。若为 None，则会使用环境变量 ``PADDLE_EXTENSION_DIR`` 的值作为默认的存放目录。可使用 :ref:`cn_api_paddle_utils_cpp_extension_get_build_directory` 接口查看当前的目录设置。默认值为 None 。 - - **verbose** (str，可选) - 用于指定是否需要输出编译过程中的日志信息，默认为 False。 + - **verbose** (bool，可选) - 用于指定是否需要输出编译过程中的日志信息，默认为 False。 返回 :::::::::::: diff --git a/docs/api/paddle/utils/data/default_collate_cn.rst b/docs/api/paddle/utils/data/default_collate_cn.rst index 2b7c5edadf2..148972290c9 100644 --- a/docs/api/paddle/utils/data/default_collate_cn.rst +++ b/docs/api/paddle/utils/data/default_collate_cn.rst @@ -3,6 +3,16 @@ default_collate ------------------------------- -.. py:function:: paddle.utils.data.default_collate() +.. py:function:: paddle.utils.data.default_collate(batch) -``paddle.io.dataloader.collate.default_collate_fn`` 的别名，请参考 :ref:`cn_api_paddle_io_DataLoader`。 +``paddle.io.dataloader.collate.default_collate_fn`` 的别名。该函数接收样本数据组成的列表，递归处理其中的列表、字典、字符串、数值、NumPy 数组和 Tensor，并沿第 0 维堆叠数值、NumPy 数组和 Tensor。请参考 :ref:`cn_api_paddle_io_DataLoader`。 + +参数 +::::::::: + + - **batch** (list) - 样本数据组成的列表。 + +返回 +::::::::: + +批处理后的数据；输入中的数值、NumPy 数组和 paddle.Tensor 会被堆叠为 batch 数据。 diff --git a/docs/api/paddle/utils/data/random_split_cn.rst b/docs/api/paddle/utils/data/random_split_cn.rst index de45cf0badb..9cda4c97dfd 100644 --- a/docs/api/paddle/utils/data/random_split_cn.rst +++ b/docs/api/paddle/utils/data/random_split_cn.rst @@ -3,6 +3,18 @@ random_split ------------------------------- -.. py:function:: paddle.utils.data.random_split() +.. py:function:: paddle.utils.data.random_split(dataset, lengths, generator=None) -``paddle.io.random_split`` 的别名，请参考 :ref:`cn_api_paddle_io_random_split`。 +``paddle.io.random_split`` 的别名。将数据集随机划分为给定长度的互不重叠的新数据集。 + +参数 +::::::::: + + - **dataset** (Dataset) - 要划分的数据集。 + - **lengths** (Sequence) - 各划分的长度或比例。 + - **generator** (Generator，可选) - 用于随机排列的生成器。默认值为 None，此时使用 ``manual_seed()`` 中的默认生成器。 + +返回 +::::::::: + +list[Subset]，原始数据集的互不重叠子数据集列表。 diff --git a/docs/api/paddle/utils/deprecated_cn.rst b/docs/api/paddle/utils/deprecated_cn.rst index af7dfaab988..ecf405fc96c 100644 --- a/docs/api/paddle/utils/deprecated_cn.rst +++ b/docs/api/paddle/utils/deprecated_cn.rst @@ -3,7 +3,7 @@ deprecated ------------------------------- -.. py:function:: paddle.utils.deprecated(update_to="", since="", reason="") +.. py:function:: paddle.utils.deprecated(update_to="", since="", reason="", level=0) 对于即将废弃的 API 可以加入该装饰器，在调用对应 PaddlePaddle API 时，可以做如下两件事情： @@ -14,9 +14,10 @@ deprecated :::::::::::: - - **since** (str) - 即将废弃相对应的版本号。 - - **update_to** (str) - 新的 API 名称。 - - **reason** (str) - 即将废弃该 API 的原因。 + - **update_to** (str，可选) - 新的 API 名称。 + - **since** (str，可选) - 即将废弃相对应的版本号。 + - **reason** (str，可选) - 即将废弃该 API 的原因。 + - **level** (int，可选) - 废弃警告的日志级别，只能为 0、1 或 2。为 0 时不显示警告信息；为 1 时正常显示警告信息；为 2 时抛出 ``RuntimeError``。默认值为 0。 返回 :::::::::::: diff --git a/docs/api/paddle/utils/unique_name/switch_cn.rst b/docs/api/paddle/utils/unique_name/switch_cn.rst index 8fda0c235be..f31328e7783 100644 --- a/docs/api/paddle/utils/unique_name/switch_cn.rst +++ b/docs/api/paddle/utils/unique_name/switch_cn.rst @@ -3,7 +3,7 @@ switch ------------------------------- -.. py:function:: paddle.utils.unique_name.switch(new_generator=None) +.. py:function:: paddle.utils.unique_name.switch(new_generator=None, new_para_name_checker=None) @@ -13,11 +13,12 @@ switch 参数 :::::::::::: - - **new_generator** (UniqueNameGenerator，可选) - 要切换到的新命名空间，一般无需设置。缺省值为 None，表示切换到一个匿名的新命名空间。 + - **new_generator** (UniqueNameGenerator，可选) - 要切换到的新命名空间，一般无需设置。缺省值为 None，表示切换到一个匿名的新命名空间。 + - **new_para_name_checker** (DygraphParameterNameChecker，可选) - 要切换到的参数名称检查器，一般无需设置。缺省值为 None，表示切换到新的参数名称检查器。 返回 :::::::::::: -UniqueNameGenerator，先前的命名空间，一般无需操作该返回值。 +tuple[UniqueNameGenerator, DygraphParameterNameChecker]，分别为先前的命名空间和参数名称检查器，一般无需操作该返回值。 代码示例 ::::::::::::