diff --git a/docs/api/paddle/Overview_cn.rst b/docs/api/paddle/Overview_cn.rst index e7bbbcc3fbe..5265fcb91b1 100755 --- a/docs/api/paddle/Overview_cn.rst +++ b/docs/api/paddle/Overview_cn.rst @@ -215,6 +215,7 @@ tensor 数学操作原位（inplace）版本 " :ref:`paddle.put_along_axis_ ` ", "Inplace 版本的 put_along_axis API，对输入 x 采用 Inplace 策略" " :ref:`paddle.cauchy_ ` ", "直接修改输入 x，将所有元素替换为从柯西分布中随机采样的数值" " :ref:`paddle.ceil_ ` ", "Inplace 版本的 ceil API，对输入 x 采用 Inplace 策略" + " :ref:`paddle.clamp_ ` ", "Inplace 版本的 clamp API，对输入 x 采用 Inplace 策略" " :ref:`paddle.clip_ ` ", "Inplace 版本的 clip API，对输入 x 采用 Inplace 策略" " :ref:`paddle.copysign_ ` ", "Inplace 版本的 copysign API，对输入 x 采用 Inplace 策略" " :ref:`paddle.cumprod_ ` ", "Inplace 版本的 cumprod API，对输入 x 采用 Inplace 策略" diff --git a/docs/api/paddle/amp/GradScaler_cn.rst b/docs/api/paddle/amp/GradScaler_cn.rst index 4bcb9bb2f17..bfde5a3a3e0 100644 --- a/docs/api/paddle/amp/GradScaler_cn.rst +++ b/docs/api/paddle/amp/GradScaler_cn.rst @@ -7,7 +7,7 @@ GradScaler -GradScaler 用于动态图模式下的"自动混合精度"的训练。它控制 loss 的缩放比例，有助于避免浮点数溢出的问题。这个类具有 ``scale()``、 ``unscale_()``、 ``step()``、 ``update()``、 ``minimize()`` 和参数的 ``get()/set()`` 等方法。 +GradScaler 用于动态图模式下的"自动混合精度"的训练。它控制 loss 的缩放比例，有助于避免浮点数溢出的问题。这个类具有 ``scale()``、 ``unscale_()``、 ``minimize()``、 ``step()``、 ``update()`` 和参数的 ``get()/set()`` 共十九个方法。 ``scale()`` 用于让 loss 乘上一个缩放的比例。 ``unscale_()`` 用于让 loss 除去一个缩放的比例。 @@ -96,10 +96,14 @@ step(optimizer) COPY-FROM: paddle.amp.GradScaler.step -update() +update(new_scale=None) ''''''''' -更新缩放比例。 +更新 loss scaling 比例。 + +**参数** + +- **new_scale** (float，可选) - 新的 loss scaling 因子。如果提供，loss scaling 因子将直接设置为 ``new_scale`` 并重置内部步数计数。默认值为 None。 **代码示例** @@ -301,3 +305,16 @@ load_state_dict(state_dict) **代码示例** COPY-FROM: paddle.amp.GradScaler.load_state_dict + +get_scale() +''''''''' + +返回当前的缩放因子，类型为 Python float。如果 loss scaling 未启用，则返回 0.0。 + +**返回** + +float，当前 loss scaling 因子，如果禁用则返回 0.0。 + +**代码示例** + +COPY-FROM: paddle.amp.GradScaler.get_scale diff --git a/docs/api/paddle/clamp__cn.rst b/docs/api/paddle/clamp__cn.rst new file mode 100644 index 00000000000..bdefb0cdec6 --- /dev/null +++ b/docs/api/paddle/clamp__cn.rst @@ -0,0 +1,15 @@ +.. _cn_api_paddle_clamp_: + +clamp\_ +------------------------------- + +.. py:function:: paddle.clamp_(x, min=None, max=None, name=None) + +``clip_`` 的别名，请参考 :ref:`cn_api_paddle_clip_`。 + +.. note:: + 别名支持：参数名 ``input`` 可替代 ``x``，如 ``clamp_(input=tensor_x)`` 等价于 ``clamp_(x=tensor_x)``。 + +更多关于 inplace 操作的介绍请参考 `3.1.3 原位（Inplace）操作和非原位操作的区别`_ 了解详情。 + +.. _3.1.3 原位（Inplace）操作和非原位操作的区别: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/beginner/tensor_cn.html#id3 diff --git a/docs/api/paddle/clamp_max_cn.rst b/docs/api/paddle/clamp_max_cn.rst new file mode 100644 index 00000000000..2ffff083b7b --- /dev/null +++ b/docs/api/paddle/clamp_max_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_clamp_max: + +clamp_max +------------------------------- + +.. py:function:: paddle.clamp_max(input, max, *, out=None) + +将输入中的所有元素裁剪到区间 [min=None, max] 内。 + +该接口是 ``paddle.clip`` 的封装，仅设置上界。 + +参数 +:::::::::::: + + - **input** (Tensor) - 输入的 Tensor。 + - **max** (float|Tensor) - 裁剪的最大值。 + +关键字参数 +:::::::::::: + - **out** (Tensor，可选) - 输出 Tensor。默认值为 None。 + +返回 +:::::::::::: +输出 Tensor，与 ``input`` 维度相同。 + +代码示例 +:::::::::::: + +COPY-FROM: paddle.clamp_max diff --git a/docs/api/paddle/cross_cn.rst b/docs/api/paddle/cross_cn.rst index 0356d90752c..7b393ade2c6 100644 --- a/docs/api/paddle/cross_cn.rst +++ b/docs/api/paddle/cross_cn.rst @@ -6,15 +6,15 @@ cross .. py:function:: paddle.cross(x, y, axis=9, name=None) -计算 Tensor ``x`` 和 ``y`` 在 ``axis`` 维度上的向量积（叉积）。 +计算两个 Tensor 在 ``axis`` 维度上的向量积（叉积）。 -``x`` 和 ``y`` 必须有相同的形状，且指定的 ``axis`` 的长度必须为 3。如果未指定 ``axis``，默认选取第一个长度为 3 的 ``axis`` 。 +输入 Tensor 必须有相同的形状，且指定维度的长度必须为 3。如果未指定 ``axis``，默认选取第一个长度为 3 的维度。 参数 ::::::::: - **x** (Tensor) - 第一个输入 Tensor，数据类型为：float16、float32、float64、int32、int64、complex64、complex128。别名 ``input``。 - **y** (Tensor) - 第二个输入 Tensor，数据类型为：float16、float32、float64、int32、int64、complex64、complex128。别名 ``other``。 - - **axis** (int，可选) - 沿着此维进行向量积操作。别名 ``dim``。默认值是 9，意思是选取第一个长度为 3 的 ``axis`` 。 + - **axis** (int，可选) - 沿着此维度进行向量积操作。默认值为 9，表示选取第一个长度为 3 的维度。别名 ``dim``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/device/set_default_device_cn.rst b/docs/api/paddle/device/set_default_device_cn.rst new file mode 100644 index 00000000000..d075f57ced0 --- /dev/null +++ b/docs/api/paddle/device/set_default_device_cn.rst @@ -0,0 +1,28 @@ +.. _cn_api_paddle_device_set_default_device: + +set_default_device +------------------------------- + +.. py:function:: paddle.device.set_default_device(device=None) + +Paddle 支持在各种类型的设备上运行，包括 CPU、GPU、XPU、NPU 和 IPU。 +该函数可以指定 OP 运行的全局设备。 + +参数 +::::::::: + + - **device** (str|Place|paddle.device|int|None，可选) - 此参数确定特定的运行设备。可以是 ``cpu``、``gpu``、``xpu``、``npu``、``gpu:x``、``xpu:x``、``npu:x`` 和 ``ipu``， + 其中 ``x`` 是 GPU、XPU 或 NPU 的索引。也可以是 ``paddle.device`` 对象或 int 类型的设备索引。默认为 ``None``，表示当前设备。 + +返回 +::::::::: + + 无。 + +代码示例 +::::::::: + +.. code-block:: pycon + + >>> import paddle + >>> paddle.device.set_default_device("cpu") diff --git a/docs/api/paddle/expand_copy_cn.rst b/docs/api/paddle/expand_copy_cn.rst new file mode 100644 index 00000000000..aa3c96ab119 --- /dev/null +++ b/docs/api/paddle/expand_copy_cn.rst @@ -0,0 +1,30 @@ +.. _cn_api_paddle_expand_copy: + +expand_copy +------------------------------- + +.. py:function:: paddle.expand_copy(x, shape, name=None) + +根据 ``shape`` 指定的形状扩展 ``x``，扩展后返回一个新的 Tensor，不会修改原 Tensor。 + +这是 :ref:`cn_api_paddle_expand` 的非原位版本，始终返回新的 Tensor 而非视图。 + +.. note:: + 该接口有两个签名： + 1. ``paddle.expand_copy(x, shape, name=None)`` (Paddle 风格)：根据广播语义返回扩展后的新 Tensor。 + 2. ``paddle.expand_copy(input, *size)`` (PyTorch 风格)：通过可变长 size 参数返回扩展后的新 Tensor。 + +参数 +::::::::::: + - **x** (Tensor) - 输入的 Tensor。别名 ``input``。 + - **shape** (tuple|list|Tensor) - 目标扩展形状。维度数必须大于或等于 ``x`` 的维度数。若 shape 为 list 或 tuple，其中的元素值应全为整数或 0-D 或 1-D Tensor（数据类型为 int32）。别名 ``size``。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::::: +Tensor，数据类型与 ``x`` 相同。 + +代码示例 +::::::::::: + +COPY-FROM: paddle.expand_copy diff --git a/docs/api/paddle/histc_cn.rst b/docs/api/paddle/histc_cn.rst index 95cc8cdc54a..9c3ec213d8c 100644 --- a/docs/api/paddle/histc_cn.rst +++ b/docs/api/paddle/histc_cn.rst @@ -7,7 +7,7 @@ histc 计算 Tensor 的直方图。 -元素被分配到 min 和 max 之间的等宽区间中。如果 min 和 max 都为零，则使用数据的最小值和最大值。 +元素被分配到 min 和 max 之间的等宽区间中（包含边界）。如果 min 和 max 都为零，则使用数据的最小值和最大值。 参数 ::::::::: diff --git a/docs/api/paddle/hstack_cn.rst b/docs/api/paddle/hstack_cn.rst index e6a3b03e539..dec1978a3e2 100644 --- a/docs/api/paddle/hstack_cn.rst +++ b/docs/api/paddle/hstack_cn.rst @@ -3,16 +3,20 @@ hstack ------------------------------- -.. py:function:: paddle.hstack(x, name=None) +.. py:function:: paddle.hstack(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/linalg/cholesky_cn.rst b/docs/api/paddle/linalg/cholesky_cn.rst index 454b79136d3..e08819a047a 100644 --- a/docs/api/paddle/linalg/cholesky_cn.rst +++ b/docs/api/paddle/linalg/cholesky_cn.rst @@ -3,22 +3,23 @@ cholesky ------------------------------- -.. py:function:: paddle.linalg.cholesky(x, upper=False, name=None) - - - +.. py:function:: paddle.linalg.cholesky(x, upper=False, name=None, *, out=None) 计算一个对称正定矩阵或一批对称正定矩阵的 Cholesky 分解。如果 ``upper`` 是 ``True``， -则分解形式为 :math:`A = U ^ {T} U`，返回的矩阵 U 是上三角矩阵。 -否则，分解形式为 :math:`A = LL ^ {T}`，并返回矩阵 :math:`L` 是下三角矩阵。 +则分解形式为 :math:`A = U^{T}U`，返回的矩阵 U 是上三角矩阵。 +否则，分解形式为 :math:`A = LL^{T}`，并返回矩阵 :math:`L` 是下三角矩阵。 参数 :::::::::::: - - **x** （Tensor）- 输入变量为多维 Tensor，它的维度应该为 ``[*, M, M]``，其中*为零或更大的批次尺寸，并且最里面的两个维度上的矩阵都应为对称的正定矩阵，支持数据类型为 float32、float64。 + - **x** （Tensor）- 输入变量为多维 Tensor，它的维度应该为 ``[*, M, M]``，其中*为零或更大的批次尺寸，并且最里面的两个维度上的矩阵都应为对称的正定矩阵，支持数据类型为 float32、float64。别名 ``input``。 - **upper** （bool）- 指示是否返回上三角矩阵或下三角矩阵。默认值：False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，若不为 ``None``，计算结果将保存在该 Tensor 中，默认值为 ``None``。 + 返回 :::::::::::: Tensor，与 ``x`` 具有相同形状和数据类型。它代表了 Cholesky 分解生成的三角矩阵。 diff --git a/docs/api/paddle/linalg/det_cn.rst b/docs/api/paddle/linalg/det_cn.rst index dcb0e78ef65..67fd75e40f8 100644 --- a/docs/api/paddle/linalg/det_cn.rst +++ b/docs/api/paddle/linalg/det_cn.rst @@ -3,18 +3,24 @@ det ------------------------------- -.. py:function:: paddle.linalg.det(x) -计算批量矩阵的行列式值。 +.. py:function:: paddle.linalg.det(x, name=None, *, out=None) + +计算一个或批量方阵的行列式值。 参数 :::::::::::: - - **x** (Tensor)：输入一个或批量矩阵。``x`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32、float64。别名 ``input``。 + - **x** (Tensor)：输入一个或批量方阵。``x`` 的形状应为 ``[*, n, n]``，其中 ``*`` 为零或更大的批次维度。别名 ``input``。 + - **name** (str|None，可选) - 该参数用于打印调试信息，具体用法请参见 :ref:`api_guide_Name`，默认值为 None。 + +关键字参数 +:::::::::::: + - **out** (Tensor，可选) - 指定输出的存储结果的 Tensor，如果提供，返回值将是 ``out`` 本身。默认值为 ``None``。 返回 :::::::::::: -Tensor，输出矩阵的行列式值 Shape 为 ``[*]`` 。 +Tensor，输出方阵的行列式值。Shape 为 ``[*]`` 。 代码示例 :::::::::: diff --git a/docs/api/paddle/linalg/eigh_cn.rst b/docs/api/paddle/linalg/eigh_cn.rst index 1b21026bc43..5139e2cbded 100644 --- a/docs/api/paddle/linalg/eigh_cn.rst +++ b/docs/api/paddle/linalg/eigh_cn.rst @@ -3,21 +3,27 @@ eigh ------------------------------- -.. py:function:: paddle.linalg.eigh(x, UPLO='L', name=None) +.. py:function:: paddle.linalg.eigh(x, UPLO='L', name=None, *, out=None) 计算厄米特矩阵或者实数对称矩阵的特征值和特征向量。 参数 :::::::::::: - - **x** (Tensor)：输入一个或一批厄米特矩阵或者实数对称矩阵。``x`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32、float64、complex64、complex128。 + - **x** (Tensor)：输入一个或一批厄米特矩阵或者实数对称矩阵。``x`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32、float64、complex64、complex128。别名 ``input``。 - **UPLO** (str，可选)：表示计算上三角或者下三角矩阵，默认值为 'L'，表示计算下三角矩阵的特征值和特征向量，'U'表示计算上三角矩阵的特征值和特征向量。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **out** (tuple[Tensor, Tensor]，可选) - 输出 Tensor 元组，若不为 ``None``，计算结果将保存在该 Tensor 元组中，默认值为 ``None``。 + 返回 :::::::::::: - - Tensor out_value，输出矩阵的特征值，输出顺序按照从小到大进行排序。Shape 为 ``[*, M]`` 。 - - Tensor out_vector，输出矩阵的特征向量，与特征值一一对应，Shape 为 ``[*, M, M]`` 。 + 包含两项的元组： + + - **out_value** (Tensor)：输出矩阵的特征值，输出顺序按照从小到大进行排序。Shape 为 ``[*, N]``，数据类型为 float32 和 float64。 + - **out_vector** (Tensor)：输出矩阵的特征向量，与特征值一一对应，Shape 为 ``[*, N, N]``，数据类型为 float32、float64、complex64 和 complex128。 代码示例 :::::::::: diff --git a/docs/api/paddle/linalg/qr_cn.rst b/docs/api/paddle/linalg/qr_cn.rst index 3aab06aad47..5a7cd3ed219 100644 --- a/docs/api/paddle/linalg/qr_cn.rst +++ b/docs/api/paddle/linalg/qr_cn.rst @@ -3,8 +3,14 @@ qr ------------------------------- -.. py:function:: paddle.linalg.qr(x, mode="reduced", name=None) +.. py:function:: paddle.linalg.qr(x, mode='reduced', name=None, *, out=None) +.. note:: + + 本 API 支持两种签名方式： + + 1. ``paddle.linalg.qr(x, mode='reduced', name=None, *, out=None)``（Paddle 风格）：通过 ``mode`` 字符串参数控制 QR 分解。 + 2. ``paddle.linalg.qr(input, some=True, *, out=None)``（PyTorch 风格）：通过 ``some`` 布尔参数控制 QR 分解。 计算一个或一批矩阵的正交三角分解，也称 QR 分解（暂不支持反向）。 @@ -15,19 +21,29 @@ qr 其中，:math:`Q` 是正交矩阵，:math:`R` 是上三角矩阵。 - 参数 :::::::::::: - - **x** (Tensor)：输入进行正交三角分解的一个或一批方阵，类型为 Tensor。 ``x`` 的形状应为 ``[*, M, N]``，其中 ``*`` 为零或更大的批次维度，数据类型支持 float32， float64。 - - **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:`Q`，只返回 :math:`R` 且形状为 ``[*, K, 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** (Tensor|tuple，可选) - 指定输出的张量。 + 当 ``mode = "r"`` 时，为一个 Tensor 用于存储 R； + 否则为一个 ``(Q, R)`` 张量元组，默认值为 None。 + 返回 :::::::::::: - - Tensor Q，正交三角分解的 Q 正交矩阵，需注意如果 ``mode = "reduced"``，则不返回 Q 矩阵，只返回 R 矩阵。 - - Tensor R，正交三角分解的 R 上三角矩阵。 + - 如果 ``mode = "r"``，返回 Tensor R，即缩减的上三角矩阵。 + - 否则返回 ``QrRetType(Q, R)`` 具名元组： + - Tensor Q，正交三角分解的 Q 正交矩阵。 + - Tensor R，正交三角分解的 R 上三角矩阵。 代码示例 :::::::::: diff --git a/docs/api/paddle/logdet_cn.rst b/docs/api/paddle/logdet_cn.rst new file mode 100644 index 00000000000..c17bf1ef2ba --- /dev/null +++ b/docs/api/paddle/logdet_cn.rst @@ -0,0 +1,27 @@ +.. _cn_api_paddle_logdet: + +logdet +------------------------------- + +.. py:function:: paddle.logdet(input, name=None) + +计算一个或一批方阵的行列式的自然对数。 + +对于行列式为负数的矩阵，返回 ``nan``。 +对于行列式为零的矩阵，返回 ``-inf``。 + +参数 +:::::::::::: + + - **input** (Tensor) - 输入一个或批量方阵。``input`` 的形状应为 ``[*, n, n]``，其中 ``*`` 为零或更大的批次维度。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +:::::::::::: + +Tensor：输出矩阵的行列式的自然对数值，Shape 为 ``[*]``。 + +代码示例 +:::::::::::: + +COPY-FROM: paddle.logdet diff --git a/docs/api/paddle/masked_fill__cn.rst b/docs/api/paddle/masked_fill__cn.rst index 1217c2e39c9..90a205f7464 100644 --- a/docs/api/paddle/masked_fill__cn.rst +++ b/docs/api/paddle/masked_fill__cn.rst @@ -3,9 +3,13 @@ masked_fill\_ ------------------------------- -.. py:function:: paddle.masked_fill_(x) +.. py:function:: paddle.masked_fill_(x, mask, value, name=None) + Inplace 版本的 :ref:`cn_api_paddle_masked_fill` API，对输入 x 采用 Inplace 策略。 +.. note:: + 别名支持：参数名 ``input`` 可替代 ``x``，如 ``masked_fill_(input=tensor_x, mask=tensor_mask, value=val)`` 等价于 ``masked_fill_(x=tensor_x, mask=tensor_mask, value=val)``。 + 更多关于 inplace 操作的介绍请参考 `3.1.3 原位（Inplace）操作和非原位操作的区别`_ 了解详情。 .. _3.1.3 原位（Inplace）操作和非原位操作的区别: https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/beginner/tensor_cn.html#id3 diff --git a/docs/api/paddle/masked_fill_cn.rst b/docs/api/paddle/masked_fill_cn.rst index 47351dfbe76..87aa6dfb1c3 100644 --- a/docs/api/paddle/masked_fill_cn.rst +++ b/docs/api/paddle/masked_fill_cn.rst @@ -5,8 +5,7 @@ masked_fill .. py:function:: paddle.masked_fill(x, mask, value, name=None) - -返回一个 1-D 的 Tensor，Tensor 的值是根据 ``mask`` 信息，将 ``value`` 中的值填充到 ``x`` 中 ``mask`` 对应为 ``True`` 的位置，``mask`` 的数据类型是 bool。 +在 mask 为 True 的位置用 value 填充 x 中的元素。mask 的形状必须与 x 的形状可广播。 下图展示了一个例子：假设我们有一个所有元素值为 1 的 3x3 矩阵 ``x`` 和一个相同尺寸的掩码矩阵 ``Mask``，``Value`` 值为 3。 @@ -18,13 +17,13 @@ masked_fill :::::::::::: - **x** (Tensor) - 输入 Tensor，数据类型为 float，double，int，int64_t，float16 或者 bfloat16。别名 ``input``。 - - **mask** (Tensor) - 布尔张量，表示要填充的位置。mask 的数据类型必须为 bool。 - - **value** (Scalar or 0-D Tensor)：用于填充目标张量的值，数据类型为 float，double，int，int64_t，float16 或者 bfloat16。 + - **mask** (Tensor) - 布尔张量，表示要填充的位置。mask 的形状必须与 x 的形状可广播。mask 的数据类型必须为 bool。 + - **value** (Scalar or 0-D Tensor) - 用于填充目标张量的值，数据类型为 float，double，int，int64_t，float16 或者 bfloat16。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 :::::::::::: -返回一个根据 ``mask`` 将对应位置填充为 ``value`` 的 Tensor，数据类型与 ``x`` 相同。 +Tensor，与 ``x`` 具有相同形状和数据类型的 Tensor。 代码示例 :::::::::::: diff --git a/docs/api/paddle/moveaxis_cn.rst b/docs/api/paddle/moveaxis_cn.rst index fe9b7b306e6..7d2d1c28b37 100644 --- a/docs/api/paddle/moveaxis_cn.rst +++ b/docs/api/paddle/moveaxis_cn.rst @@ -5,7 +5,7 @@ moveaxis .. py:function:: paddle.moveaxis(x, source, destination, name=None) -将输入 Tensor ``x`` 的轴从 ``source`` 位置移动到 ``destination`` 位置，其他轴按原来顺序排布。同时根据新的 shape，重排 Tensor 中的数据。 +将输入 Tensor ``x`` 的轴从 ``source`` 位置移动到 ``destination`` 位置，其他未被移动的轴保持原有顺序。 下图展示了代码示例中的第一个操作 diff --git a/docs/api/paddle/nn/ELU_cn.rst b/docs/api/paddle/nn/ELU_cn.rst index 1c08ca8aa27..b0249e08f34 100644 --- a/docs/api/paddle/nn/ELU_cn.rst +++ b/docs/api/paddle/nn/ELU_cn.rst @@ -2,7 +2,7 @@ ELU ------------------------------- -.. py:class:: paddle.nn.ELU(alpha=1.0, name=None) +.. py:class:: paddle.nn.ELU(alpha=1.0, inplace=False, name=None) ELU 激活层（ELU Activation Operator） @@ -23,7 +23,8 @@ ELU 激活层（ELU Activation Operator） 参数 :::::::::: - **alpha** (float，可选) - ELU 的 alpha 值，默认值为 1.0。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **inplace** (bool，可选) - 是否使用 inplace 操作。默认值为 False。 + - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 形状 :::::::::: diff --git a/docs/api/paddle/nn/functional/batch_norm_cn.rst b/docs/api/paddle/nn/functional/batch_norm_cn.rst index 1b3f7bea238..928ebbd9fd1 100644 --- a/docs/api/paddle/nn/functional/batch_norm_cn.rst +++ b/docs/api/paddle/nn/functional/batch_norm_cn.rst @@ -5,6 +5,8 @@ batch_norm .. py:function:: paddle.nn.functional.batch_norm(x, running_mean, running_var, weight=None, bias=None, training=False, momentum=0.9, epsilon=1e-05, data_format='NCHW', use_global_stats=None, name=None) +对输入数据进行批归一化（Batch Normalization），详见论文 Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift 。 + 推荐使用 nn.BatchNorm1D，nn.BatchNorm2D, nn.BatchNorm3D，由内部调用此方法。 详情见 :ref:`cn_api_paddle_nn_BatchNorm1D` 。 @@ -12,17 +14,17 @@ batch_norm 参数 :::::::::::: - - **x** (int) - 输入，数据类型为 float32, float64。 - - **running_mean** (Tensor) - 均值的 Tensor。 - - **running_var** (Tensor) - 方差的 Tensor。 - - **weight** (Tensor，可选) - 权重的 Tensor，默认为 None。 - - **bias** (Tensor，可选) - 偏置的 Tensor，默认为 None。 - - **training** (bool，可选) – 当该值为 True 时，表示为训练模式（train mode），即使用批数据计算并在训练期间跟踪全局均值和方差。为 False 时，表示使用推理模式（inference mode），即使用训练期间计算出的全局均值及方差计算。默认值为 False。 - - **momentum** (float，可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var``。默认值：0.9。更新公式如上所示。 - - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 - - **data_format** (str，可选) - 指定输入数据格式。数据格式可以为 ``"NC"``、``"NCL"``、``"NCHW"`` 或者 ``"NCDHW"``，其中 N 是批大小，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度，L 是特征长度。默认值为 ``"NCHW"``。 - - **use_global_stats** (bool|None，可选) - 指示是否使用全局均值和方差。若设置为 False，则使用一个 mini-batch 的统计数据。若设置为 True 时，将使用全局统计数据。若设置为 None，则会在测试阶段使用全局统计数据，在训练阶段使用一个 mini-batch 的统计数据。默认值为 None。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **x** (Tensor) - 输入，数据类型为 float32, float64。 + - **running_mean** (Tensor) - 运行均值。 + - **running_var** (Tensor) - 运行方差。 + - **weight** (Tensor，可选) - batch_norm 权重的 Tensor，默认为 None。 + - **bias** (Tensor，可选) - batch_norm 偏置的 Tensor，默认为 None。 + - **training** (bool，可选) - 如果为 True，表示为训练模式，即使用批数据计算并在训练期间跟踪全局均值和方差。如果为 False，表示使用推理模式，即使用训练期间计算出的全局均值及方差计算。默认值为 False。 + - **momentum** (float，可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var``。默认值：0.9。 + - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-5。 + - **data_format** (str，可选) - 指定输入数据格式，可以为 "NC"、"NCL"、"NCHW"、"NCDHW"、"NLC"、"NHWC" 或 "NDHWC"，其中 N 是批大小，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度，L 是特征长度。默认值为 "NCHW"。 + - **use_global_stats** (bool|None，可选) - 指示是否使用全局均值和方差。若设置为 False，则使用一个 mini-batch 的统计数据。若设置为 True，则使用全局统计数据。若设置为 None，则在测试阶段使用全局统计数据，在训练阶段使用一个 mini-batch 的统计数据。默认值为 None。 + - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/nn/functional/elu_cn.rst b/docs/api/paddle/nn/functional/elu_cn.rst index 81118671f3f..d1509f42f65 100644 --- a/docs/api/paddle/nn/functional/elu_cn.rst +++ b/docs/api/paddle/nn/functional/elu_cn.rst @@ -3,7 +3,7 @@ elu ------------------------------- -.. py:function:: paddle.nn.functional.elu(x, alpha=1.0, name=None) +.. py:function:: paddle.nn.functional.elu(x, alpha=1.0, inplace=False, name=None) elu 激活层（ELU Activation Operator） @@ -23,8 +23,9 @@ elu 激活层（ELU Activation Operator） 参数 :::::::::: - - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float32、float64。 + - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float32、float64。别名 ``input``。 - **alpha** (float，可选) - elu 的 alpha 值，默认值为 1.0。 + - **inplace** (bool，可选) - 是否使用 inplace 操作。默认值为 False。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 diff --git a/docs/api/paddle/nn/functional/gumbel_softmax_cn.rst b/docs/api/paddle/nn/functional/gumbel_softmax_cn.rst index e62cb84c81e..26426cbd81c 100644 --- a/docs/api/paddle/nn/functional/gumbel_softmax_cn.rst +++ b/docs/api/paddle/nn/functional/gumbel_softmax_cn.rst @@ -4,7 +4,7 @@ gumbel_softmax ------------------------------- .. py:function:: paddle.nn.functional.gumbel_softmax(x, temperature = 1.0, hard = False, axis = -1, name = None) -实现了按 Gumbel-Softmax 分布进行采样的功能，通过 hard 可选择是否离散化。记 temperature 为 ``t``，涉及到的等式如下： +该算子实现了从 Gumbel-Softmax 分布中采样，通过 hard 可选择是否离散化。记 temperature 为 ``t``，计算过程如下： 1. 产生 gumbel 噪声 @@ -18,24 +18,29 @@ gumbel_softmax v = [x_1 + G_1,...,x_n + G_n] -3. 计算 gumbel_softmax +3. 计算 gumbel_softmax 并生成样本 .. math:: gumbel\_softmax(v_i)=\frac{e^{v_i/t}}{\sum_{j=1}^n{e^{v_j/t}}},i=1,2,3...n +.. note:: + 此 API 有两种调用格式： + 1. ``paddle.nn.functional.gumbel_softmax(x, temperature=1.0, hard=False, axis=-1, name=None)`` (Paddle 风格)：标准 Paddle API 签名。 + 2. ``paddle.nn.functional.gumbel_softmax(logits, tau=1.0, hard=False, eps=1e-10, dim=-1)`` (PyTorch 风格)：兼容 PyTorch 的签名，其中 ``logits`` 是 ``x`` 的别名，``tau`` 是 ``temperature`` 的别名，``dim`` 是 ``axis`` 的别名，``eps`` 参数被接受但不产生任何作用（已废弃）。 + 参数 :::::::::: - - **x** (Tensor) - 一个 N-D Tensor，前 N-1 维用于独立分布 batch 的索引，最后一维表示每个类别的概率，dtype 类型为 float16，float，double。 - - **temperature** (float，可选) - 大于 0 的标量。默认值：1.0。 - - **hard** (bool，可选) - 如果是 True，返回离散的 one-hot 向量。如果是 False，返回软样本。默认值：False。 - - **axis** (int，可选) - 按照维度 axis 计算 softmax。默认值：-1。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **x** (Tensor) - 一个 N-D Tensor，前 N-1 维用于独立分布 batch 的索引，最后一维表示每个类别的概率向量，dtype 类型为 float16、float32、float64。别名 ``logits``。 + - **temperature** (float，可选) - 非负标量温度值。默认值：1.0。别名 ``tau``。 + - **hard** (bool，可选) - 如果为 True，返回的样本将被离散化为 one-hot 向量，但在自动求导时仍按软样本进行微分。如果为 False，返回软样本。默认值：False。 + - **axis** (int，可选) - 沿着该维度计算 softmax。默认值：-1。别名 ``dim``。 + - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 :::::::::: - 与 ``x`` 形状相同的符合 gumbel-softmax 分布的 ``Tensor``。如果 ``hard=True``，则返回的样本将是 one-hot。如果 ``hard=False``，则返回的向量将是各维度加起来等于 1 的概率。 + 与 ``x`` 形状相同的从 Gumbel-Softmax 分布采样的 ``Tensor``。如果 ``hard=True``，则返回的样本将是 one-hot 向量；如果 ``hard=False``，则返回的向量将是沿 ``axis`` 维度之和为 1 的概率分布。 代码示例 :::::::::: diff --git a/docs/api/paddle/nn/functional/instance_norm_cn.rst b/docs/api/paddle/nn/functional/instance_norm_cn.rst index bf0c9570b2c..37cb01b0bab 100644 --- a/docs/api/paddle/nn/functional/instance_norm_cn.rst +++ b/docs/api/paddle/nn/functional/instance_norm_cn.rst @@ -3,23 +3,28 @@ instance_norm ------------------------------- -.. py:class:: paddle.nn.functional.instance_norm(x, running_mean=None, running_var=None, weight=None, bias=None, use_input_stats=True, momentum=0.9, eps=1e-05, data_format='NCHW', name=None) +.. py:function:: paddle.nn.functional.instance_norm(x, running_mean=None, running_var=None, weight=None, bias=None, use_input_stats=True, momentum=0.9, eps=1e-05, data_format='NCHW', name=None) + +.. note:: + 此 API 有两种调用方式： + 1. ``paddle.nn.functional.instance_norm(x, running_mean=None, running_var=None, weight=None, bias=None, use_input_stats=True, momentum=0.9, eps=1e-05, data_format='NCHW', name=None)`` (Paddle 风格)。 + 2. ``paddle.nn.functional.instance_norm(input, running_mean=None, running_var=None, weight=None, bias=None, use_input_stats=True, momentum=0.1, eps=1e-05)`` (PyTorch 风格)。 推荐使用 :ref:`cn_api_paddle_nn_InstanceNorm1D`，:ref:`cn_api_paddle_nn_InstanceNorm2D`，:ref:`cn_api_paddle_nn_InstanceNorm3D`，由内部调用此方法。 参数 :::::::::::: - - **x** (Tensor) - 输入，数据类型为 float32, float64。 - - **running_mean** (Tensor，可选) - 均值的 Tensor。过时（已被删除，无法使用） - - **running_var** (Tensor，可选) - 方差的 Tensor。过时（已被删除，无法使用） - - **weight** (Tensor，可选) - 权重的 Tensor。默认值：None. 如果 weight 为 None 则 weight 被初始化为全 1 的 Tensor. - - **bias** (Tensor，可选) - 偏置的 Tensor。默认值：None. 如果 bias 为 None 则 bias 被初始化为值等于 0 的 Tensor. - - **use_input_stats** (bool，可选) - 默认是 True。过时（已被删除，无法使用） - - **momentum** (float，可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var``。默认值：0.9。更新公式如上所示。 - - **eps** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 - - **data_format** (string，可选) - 指定输入数据格式，数据格式可以为“NC", "NCL", "NCHW" 或者"NCDHW"。默认值："NCHW"。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **x** (Tensor) - 输入，数据类型为 float32, float64。别名 ``input``。 + - **running_mean** (Tensor，可选) - 运行均值。默认值：None。过时（已被删除，无法使用） + - **running_var** (Tensor，可选) - 运行方差。默认值：None。过时（已被删除，无法使用） + - **weight** (Tensor，可选) - instance_norm 权重的 Tensor。默认值：None。如果 weight 为 None 则 weight 被初始化为全 1 的 Tensor。 + - **bias** (Tensor，可选) - instance_norm 偏置的 Tensor。默认值：None。如果 bias 为 None 则 bias 被初始化为值等于 0 的 Tensor。 + - **eps** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-5。 + - **momentum** (float，可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var``。默认值：0.9。 + - **use_input_stats** (bool，可选) - 默认值是 True。过时（已被删除，无法使用） + - **data_format** (str，可选) - 指定输入数据格式，数据格式可以为 "NC", "NCL", "NCHW" 或者 "NCDHW"。默认值："NCHW"。 + - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 :::::::::::: diff --git a/docs/api/paddle/nn/functional/prelu_cn.rst b/docs/api/paddle/nn/functional/prelu_cn.rst index 8a5f421c96a..78133acb7ca 100644 --- a/docs/api/paddle/nn/functional/prelu_cn.rst +++ b/docs/api/paddle/nn/functional/prelu_cn.rst @@ -5,7 +5,7 @@ prelu .. py:function:: paddle.nn.functional.prelu(x, weight, data_format="NCHW", name=None) -prelu 激活层（PRelu Activation Operator）。计算公式如下： +prelu 激活。计算公式如下： .. math:: @@ -15,13 +15,13 @@ prelu 激活层（PRelu Activation Operator）。计算公式如下： 参数 :::::::::: - - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float32、float64。 - - **weight** (Tensor) - 可训练参数，数据类型同``x`` 一致，形状支持：[]、[1] 或者 [in]，其中 ``in`` 为输入的通道数。 - - **data_format** (str，可选) – 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是 "NC", "NCL", "NCHW", "NCDHW", "NLC", "NHWC" 或者 "NDHWC"。默认值："NCHW"。 - - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **x** (Tensor) - 输入的 ``Tensor``，数据类型为：float32、float64。别名 ``input``。 + - **weight** (Tensor) - 可训练参数，数据类型同 ``x`` 一致，形状支持：[]、[1] 或者 [in]，其中 ``in`` 为输入 ``x`` 的通道数。 + - **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + - **data_format** (str，可选) - 指定输入的数据格式，可以是 "NC", "NCL", "NCHW", "NCDHW", "NLC", "NHWC" 或 "NDHWC"。默认值："NCHW"。 返回 -:::::::::: +::::::::: ``Tensor``，数据类型和形状同 ``x`` 一致。 代码示例 diff --git a/docs/api/paddle/nn/functional/rms_norm_cn.rst b/docs/api/paddle/nn/functional/rms_norm_cn.rst index e6b094395b1..8320adcff87 100644 --- a/docs/api/paddle/nn/functional/rms_norm_cn.rst +++ b/docs/api/paddle/nn/functional/rms_norm_cn.rst @@ -5,24 +5,21 @@ rms_norm .. py:function:: paddle.nn.functional.rms_norm(x, normalized_shape, weight=None, epsilon=1e-05, name=None) -推荐使用 nn.LayerNorm。 - -详情见 :ref:`cn_api_paddle_nn_LayerNorm` 。 - +对输入 Tensor 的最后一维应用 RMS Layer Normalization，使用 CUDA 实现。 参数 :::::::::::: - - **x** (int) - 输入，数据类型为 bfloat16 、 float16 、 float32 或 float64。 - - **normalized_shape** (list|tuple) - 期望的输入是 :math:`[*, normalized_shape[0], normalized_shape[1], ..., normalized_shape[-1]]`，如果是一个整数，会作用在最后一个维度。 - - **weight** (Tensor，可选) - 权重的 Tensor，默认为 None。 - - **eps** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **x** (Tensor) - 输入 Tensor，形状为 [rows, cols] 或更高维（会被展平为 2 维），数据类型为 bfloat16、float16、float32 或 float64。 + - **normalized_shape** (list|tuple) - 期望输入的形状 :math:`[*, normalized_shape[0], normalized_shape[1], ..., normalized_shape[-1]]`。如果是一个整数，会对最后一维进行归一化，该维度的大小需为指定值。 + - **weight** (Tensor，可选) - rms_norm 权重的 Tensor，默认为 None。 + - **epsilon** (float|None，可选) - 为了数值稳定加在分母上的小值。如果为 None，则使用计算类型的机器精度：``float64`` 输入使用 ``np.finfo(np.float64).eps``（双精度），其他所有类型使用 ``np.finfo(np.float32).eps``（单精度）。默认值：None。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 返回 :::::::::::: -无 + out (Tensor) - 与输入形状相同的归一化 Tensor。 代码示例 :::::::::::: diff --git a/docs/api/paddle/qr_cn.rst b/docs/api/paddle/qr_cn.rst new file mode 100644 index 00000000000..cef3336d8fc --- /dev/null +++ b/docs/api/paddle/qr_cn.rst @@ -0,0 +1,31 @@ +.. _cn_api_paddle_qr: + +qr +------------------------------- + +.. py:function:: paddle.qr(input, some=True, *, out=None) + +计算一个或一批矩阵的 QR 分解。 + +该 API 是 ``paddle.linalg.qr`` 的封装，并提供 ``some`` 参数来控制 QR 分解的返回形式。 + +参数 +:::::::::::: + + - **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]`` + +关键字参数 +:::::::::::: + - **out** (tuple[Tensor, Tensor]，可选) - 输出 (Q, R) 的元组。默认值为 None。 + +返回 +:::::::::::: +tuple[Tensor, Tensor]，QR 分解后的 (Q, R) 元组。 + +代码示例 +:::::::::::: + +COPY-FROM: paddle.qr diff --git a/docs/api/paddle/real_cn.rst b/docs/api/paddle/real_cn.rst index 5c22ad48175..df4f2c3fa94 100644 --- a/docs/api/paddle/real_cn.rst +++ b/docs/api/paddle/real_cn.rst @@ -3,7 +3,7 @@ real ------ -.. py:function:: paddle.real(x, name=None) +.. py:function:: paddle.real(x, name=None, *, out=None) 返回一个包含输入复数 Tensor 的实部数值的新 Tensor。 @@ -13,6 +13,10 @@ real - **x** (Tensor) - 输入 Tensor，其数据类型可以为 complex64 或 complex128。别名 ``input``。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **out** (Tensor，可选) - 输出 Tensor，默认值为 None。 + 返回 :::::::::::: Tensor，包含原复数 Tensor 的实部数值。 diff --git a/docs/api/paddle/set_grad_enabled_cn.rst b/docs/api/paddle/set_grad_enabled_cn.rst index fb845df776b..be96064b23c 100644 --- a/docs/api/paddle/set_grad_enabled_cn.rst +++ b/docs/api/paddle/set_grad_enabled_cn.rst @@ -5,19 +5,15 @@ set_grad_enabled .. py:function:: paddle.set_grad_enabled(mode) - -创建启用或禁用动态图梯度计算的上下文。 - +创建一个启用或禁用动态图梯度计算的上下文。 参数 ::::::::: - - **mode** (bool) - 启用（True）或禁用（False）动态图梯度计算。 - + - **mode** (bool) - 启用（True）或禁用（False）梯度计算。 返回 ::::::::: -None - +无 代码示例 ::::::::: diff --git a/docs/api/paddle/tensordot_cn.rst b/docs/api/paddle/tensordot_cn.rst index 5ebf3576197..2fba030f78b 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) +.. py:function:: paddle.tensordot(x, y, axes=2, name=None, *, out=None) Tensor 缩并运算（Tensor Contraction），即沿着 axes 给定的多个轴对两个 Tensor 对应元素的乘积进行加和操作。 @@ -33,6 +33,10 @@ shape = [2,2,3]的 ``res`` 张量为 a,b 两个张量沿着 a 张量的最后一 4. ``axes`` 可以是一个 Tensor，这种情况下该 Tensor 会被转换成 list，然后应用前述规则确定做缩并运算的轴。请注意，输入 Tensor 类型的 ``axes`` 只在动态图模式下可用。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 +关键字参数 +:::::::::::: + - **out** (Tensor，可选) - 输出 Tensor。默认值为 None。 + 返回 :::::::::::: 一个 ``Tensor``，表示 Tensor 缩并的结果，数据类型与 ``x`` 和 ``y`` 相同。一般情况下，有 :math:`output.ndim = x.ndim + y.ndim - 2 \times n_{axes}`，其中 :math:`n_{axes}` 表示做 Tensor 缩并的轴数量。 diff --git a/docs/api/paddle/true_divide__cn.rst b/docs/api/paddle/true_divide__cn.rst new file mode 100644 index 00000000000..8612efefab3 --- /dev/null +++ b/docs/api/paddle/true_divide__cn.rst @@ -0,0 +1,24 @@ +.. _cn_api_paddle_true_divide_: + +true_divide_ +------------------------------- + +.. py:function:: paddle.true_divide_(input, other, name=None) + +该 API 是 ``true_divide`` 的 inplace 版本，对输入 Tensor 进行原地除法操作。 + +参数 +:::::::::::: + + - **input** (Tensor) - 输入的 Tensor，会被原地修改。 + - **other** (Tensor) - 输入的 Tensor，作为除数。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +:::::::::::: +Tensor，与 ``input`` 是同一个 Tensor，包含逐元素除法后的结果。 + +代码示例 +:::::::::::: + +COPY-FROM: paddle.true_divide_ diff --git a/docs/api/paddle/vstack_cn.rst b/docs/api/paddle/vstack_cn.rst index d43b4e7f387..b1237711138 100644 --- a/docs/api/paddle/vstack_cn.rst +++ b/docs/api/paddle/vstack_cn.rst @@ -3,16 +3,20 @@ vstack ------------------------------- -.. py:function:: paddle.vstack(x, name=None) +.. py:function:: paddle.vstack(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/dev_guides/coding_agent/api_compatibility/.claude/skills/cpp-sink/SKILL.md b/docs/dev_guides/coding_agent/api_compatibility/.claude/skills/cpp-sink/SKILL.md index be7ebe28b08..c9bedab9c3a 100644 --- a/docs/dev_guides/coding_agent/api_compatibility/.claude/skills/cpp-sink/SKILL.md +++ b/docs/dev_guides/coding_agent/api_compatibility/.claude/skills/cpp-sink/SKILL.md @@ -36,7 +36,7 @@ disable-model-invocation: false ### Step 2：迁移文档到 `_paddle_docs.py` -使用 `add_doc_and_signature` 函数迁移文档，关键要点： +使用 `add_doc_and_signature` 装饰器迁移文档，关键要点： 1. **Alias 说明格式**：在 Args 部分为有别名的参数添加 `Alias: ``alias_name``` 2. **out 参数处理**：keyword-only 参数放在 `Keyword Args:` 部分，位置参数放在 `Args:` 部分，如下： @@ -58,28 +58,43 @@ Args: **示例**： ```python -add_doc_and_signature( - "log2", - r""" - Calculates the log to the base 2 of the given input tensor, element-wise. - ... - Args: - x (Tensor): Input tensor. Alias: ``input``. - ... - Keyword Args: - out (Tensor, optional): The output tensor. Default: None. - Returns: - ... -""", - """ +@add_doc_and_signature def log2( x: Tensor, name: str | None = None, *, out: Tensor | None = None, -) -> Tensor -""", -) +) -> Tensor: + r""" + Calculates the log to the base 2 of the given input tensor, element-wise. + + .. math:: + + Out = \log_2x + + Args: + x (Tensor): Input tensor must be one of the following types: int32, int64, float16, bfloat16, float32, float64, complex64, complex128. + name (str|None, optional): Name for the operation (optional, default is None). For more information, please refer to :ref:`api_guide_Name`. + out (Tensor, optional): The output Tensor. If set, the result will be stored in this Tensor. Default: None. + + Returns: + Tensor: The log to the base 2 of the input Tensor computed element-wise. + + Examples: + + .. code-block:: pycon + + >>> import paddle + + >>> # example 1: x is a float + >>> x_i = paddle.to_tensor([[1.0], [2.0]]) + >>> res = paddle.log2(x_i) + >>> res + Tensor(shape=[2, 1], dtype=float32, place=Place(cpu), stop_gradient=True, + [[0.], + [1.]]) + """ + ... ``` **注意**： @@ -95,10 +110,10 @@ def log2( 2. 直接**删除**原有的 Python 函数实现 ```python -# 在文件最上方合适位置导入（不要添加注释） +# 在文件最上方合适位置导入 from paddle._C_ops import log2 # noqa: F401 -# 以下内容全部删除（不要添加注释） +# 以下内容全部删除 # def log2(x: Tensor, name: str | None = None) -> Tensor: # ... ``` @@ -234,7 +249,7 @@ Returns: 1. 严格按标准工作流程执行，杜绝自行臆断和跳过步骤 2. 若 Python API 参数顺序与`_C_ops` API 不同，属于特殊情况，Cpp 下沉方案无法实现，需要使用 Python 装饰器方案 3. 代码中不允许提交中文，代码注释采用英文 -4. 若 API 需支持`out`参数，必须修改`add_doc_and_signature`中的字符串，增加 out 参数 +4. 若 API 需支持`out`参数，必须在 API 签名中 out 参数 5. 不要修改`generated_tensor_methods_patch.py`，该文件是自动生成的，修改没有意义，如无法对齐可考虑放弃 C++下沉方案而不是改动该文件 6. 示例代码若涉及多种数据类型，可能触发类型检查误报，添加注释忽略： ```python diff --git a/docs/dev_guides/coding_agent/api_compatibility/.claude/skills/update-docs/SKILL.md b/docs/dev_guides/coding_agent/api_compatibility/.claude/skills/update-docs/SKILL.md index 9c3ea2bd468..d9c3d1c9153 100644 --- a/docs/dev_guides/coding_agent/api_compatibility/.claude/skills/update-docs/SKILL.md +++ b/docs/dev_guides/coding_agent/api_compatibility/.claude/skills/update-docs/SKILL.md @@ -43,6 +43,8 @@ Step 3. **更新中文文档与英文一致** 6. **文档描述原则** - 不要在文档中强调"PyTorch 风格"、"PyTorch 签名"、"PyTorch 适配"等 Pytorch 相关内容 - 参数别名说明只需简单注明"别名 xxx" +7. 无需修改 `${ROOT_DIR}/docs/guides/model_convert/convert_from_pytorch` 目录中的映射文档 + # 四、常见修改模式 diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/output_args_type_diff/torch.Tensor.logical_and_.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/output_args_type_diff/torch.Tensor.logical_and_.md index c1aa7db60cb..4b1d22e15ce 100644 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/output_args_type_diff/torch.Tensor.logical_and_.md +++ b/docs/guides/model_convert/convert_from_pytorch/api_difference/output_args_type_diff/torch.Tensor.logical_and_.md @@ -31,3 +31,4 @@ x.logical_and_(tensor_y) # Paddle 写法 _x_dtype_ = x.dtype x.logical_and_(tensor_y).cast(_x_dtype_) +``` diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.nn.functional.elu.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.nn.functional.elu.md deleted file mode 100644 index 53db8503b7d..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.nn.functional.elu.md +++ /dev/null @@ -1,20 +0,0 @@ -## [ torch 参数更多 ]torch.nn.functional.elu -### [torch.nn.functional.elu](https://docs.pytorch.org/docs/stable/generated/torch.nn.functional.elu.html#torch.nn.functional.elu) -```python -torch.nn.functional.elu(input, alpha=1.0, inplace=False) -``` - -### [paddle.nn.functional.elu](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/nn/functional/elu_cn.html#paddle.nn.functional.elu) -```python -paddle.nn.functional.elu(x, alpha=1.0, name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------- | ------------ | --------------------------------------------------------------------------------------------------------------- | -| input | x | 输入的 Tensor，仅参数名不一致。 | -| alpha | alpha | alpha 参数。 | -| inplace | - | 表示在不更改变量的内存地址的情况下，直接修改变量的值，Paddle 无此参数，一般对网络训练结果影响不大，可直接删除。 | diff --git a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.qr.md b/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.qr.md deleted file mode 100644 index a7d5f2b5ba5..00000000000 --- a/docs/guides/model_convert/convert_from_pytorch/api_difference/torch_more_args/torch.qr.md +++ /dev/null @@ -1,47 +0,0 @@ -## [ torch 参数更多 ]torch.qr -### [torch.qr](https://docs.pytorch.org/docs/stable/generated/torch.qr.html#torch.qr) -```python -torch.qr(input, some=True, *, out=None) -``` - -### [paddle.linalg.qr](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/linalg/qr_cn.html#paddle.linalg.qr) -```python -paddle.linalg.qr(x, mode='reduced', name=None) -``` - -PyTorch 相比 Paddle 支持更多其他参数，具体如下： - -### 参数映射 - -| PyTorch | PaddlePaddle | 备注 | -| ------------- | ------------ | ------------------------------------------------------ | -| input | x | 表示输入 Tensor，仅参数名不一致。 | -| some | mode | 表示 QR 分解的行为。 需进行转写。 | -| out | - | 表示输出的 Tensor 元组。 Paddle 无此参数，需要转写。 | - -### 转写示例 -#### some：控制 QR 分解的行为 -```python -# 当进行完整的 QR 分解时 -# PyTorch 写法 -q, r = torch.qr(x, some=False) - -# Paddle 写法 -q, r = paddle.linalg.qr(x, mode='complete') - -#当进行减少的 QR 分解时 -# PyTorch 写法 -q, r = torch.qr(x, some=True) - -# Paddle 写法 -q, r = paddle.linalg.qr(x, mode='reduced') -``` - -#### out：指定输出 -```python -# PyTorch 写法 -torch.qr(x, out = (q, r) ) - -# Paddle 写法 -q, r = paddle.linalg.qr(x) -```