diff --git a/docs/api/paddle/incubate/sparse/Overview_cn.rst b/docs/api/paddle/incubate/sparse/Overview_cn.rst deleted file mode 100644 index 7683455b0f1..00000000000 --- a/docs/api/paddle/incubate/sparse/Overview_cn.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _cn_overview_paddle: - -paddle.incubate.sparse ---------------------- - -paddle.incubate.sparse 目录包含飞桨框架支持稀疏数据存储和计算相关的 API。具体如下： - -- :ref:`稀疏数据结构相关 ` -- :ref:`数学操作 API ` -- :ref:`NN 相关 API ` - -.. _about_sparse_tensor: - -稀疏数据结构相关 -:::::::::::::::::::: - -.. csv-table:: - :header: "API 名称", "API 功能" - - " :ref:`paddle.incubate.sparse.sparse_coo_tensor ` ", "创建一个 COO 格式的 SparseTensor" - " :ref:`paddle.incubate.sparse.sparse_csr_tensor ` ", "创建一个 CSR 格式的 SparseTensor" - " :ref:`paddle.incubate.sparse.is_same_shape ` ", "判断两个 Tensor 的形状是否相同, 支持 DenseTensor 与 SparseTensor 相互比较" - - -.. _about_sparse_math: - -数学操作相关 -:::::::::::::::::::: - -.. csv-table:: - :header: "API 名称", "API 功能" - - " :ref:`paddle.incubate.sparse.abs` ", "绝对值函数" - " :ref:`paddle.incubate.sparse.add` ", "Sparse Tensor 逐元素相加" - " :ref:`paddle.incubate.sparse.asin` ", "arcsine 函数" - " :ref:`paddle.incubate.sparse.asinh` ", "反双曲正弦函数" - " :ref:`paddle.incubate.sparse.atan` ", "反双曲正切函数" - " :ref:`paddle.incubate.sparse.add ` ", "逐元素加法" - " :ref:`paddle.incubate.sparse.subtract ` ", "逐元素减法" - " :ref:`paddle.incubate.sparse.multiply ` ", "逐元素乘法" - " :ref:`paddle.incubate.sparse.divide ` ", "逐元素除法" - - -.. _about_sparse_nn: - -NN 相关 -:::::::::::::::::::: - -.. csv-table:: - :header: "API 名称", "API 功能" - - " :ref:`paddle.incubate.sparse.nn.Conv3D` ", "三维卷积" - " :ref:`paddle.incubate.sparse.nn.SubmConv3D` ", "三维的 submanifold 卷积" - " :ref:`paddle.incubate.sparse.nn.Relu` ", "激活函数" diff --git a/docs/api/paddle/kthvalue_cn.rst b/docs/api/paddle/kthvalue_cn.rst index 8b79215cadc..9328d9b128f 100644 --- a/docs/api/paddle/kthvalue_cn.rst +++ b/docs/api/paddle/kthvalue_cn.rst @@ -11,7 +11,7 @@ kthvalue ::::::::: - **x** （Tensor） - 一个输入的 N-D ``Tensor``，支持的数据类型：float32、float64、int32、int64。 - **k** （int，Tensor） - 需要沿轴查找的第 ``k`` 小，所对应的 ``k`` 值。 - - **axis** （int，可选） - 指定对输入 Tensor 进行运算的轴，``axis`` 的有效范围是[-R, R），R 是输入 ``x`` 的 Rank， ``axis`` 为负时与 ``axis`` + R 等价。默认值为-1。 + - **axis** （int，可选） - 指定对输入 Tensor 进行运算的轴，``axis`` 的有效范围是[-R, R），R 是输入 ``x`` 的 Rank， ``axis`` 为负时与 ``axis`` + R 等价。默认值为 None, 此时等当于-1。 - **keepdim** (bool，可选）- 是否保留指定的轴。如果是 True，维度会与输入 x 一致，对应所指定的轴的 size 为 1。否则，由于对应轴被展开，输出的维度会比输入小 1。默认值为 1。 - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 diff --git a/docs/api/paddle/sparse/Overview_cn.rst b/docs/api/paddle/sparse/Overview_cn.rst new file mode 100644 index 00000000000..b8bb3ea2997 --- /dev/null +++ b/docs/api/paddle/sparse/Overview_cn.rst @@ -0,0 +1,96 @@ +.. _cn_overview_paddle_sparse: + +paddle.sparse +--------------------- + +paddle.sparse 目录包含飞桨框架支持稀疏数据存储和计算相关的 API。具体如下： + +- :ref:`稀疏 Tensor 创建 ` +- :ref:`稀疏 Tensor 运算 ` +- :ref:`稀疏组网类 ` +- :ref:`稀疏组网类的函数式 API ` + +.. _about_sparse_tensor: + +稀疏 Tensor 创建 +:::::::::::::::::::: + +.. csv-table:: + :header: "API 名称", "API 功能" + + " :ref:`paddle.sparse.sparse_coo_tensor ` ", "创建一个 COO 格式的 SparseTensor" + " :ref:`paddle.sparse.sparse_csr_tensor ` ", "创建一个 CSR 格式的 SparseTensor" + +.. _about_sparse_math: + +稀疏 Tensor 运算 +:::::::::::::::::::: + +.. csv-table:: + :header: "API 名称", "API 功能" + + " :ref:`paddle.sparse.sin ` ", "对稀疏 Tensor 逐元素求正弦" + " :ref:`paddle.sparse.tan ` ", "对稀疏 Tensor 逐元素求正切" + " :ref:`paddle.sparse.asin ` ", "对稀疏 Tensor 逐元素求反正弦" + " :ref:`paddle.sparse.atan ` ", "对稀疏 Tensor 逐元素求反正切" + " :ref:`paddle.sparse.sinh ` ", "对稀疏 Tensor 逐元素求双曲正弦" + " :ref:`paddle.sparse.tanh ` ", "对稀疏 Tensor 逐元素求双曲正切" + " :ref:`paddle.sparse.asinh ` ", "对稀疏 Tensor 逐元素求反双曲正弦" + " :ref:`paddle.sparse.atanh ` ", "对稀疏 Tensor 逐元素求反双曲正切" + " :ref:`paddle.sparse.sqrt ` ", "对稀疏 Tensor 逐元素求算数平方根" + " :ref:`paddle.sparse.square ` ", "对稀疏 Tensor 逐元素求平方" + " :ref:`paddle.sparse.log1p ` ", "对稀疏 Tensor 逐元素计算 ln(x+1)" + " :ref:`paddle.sparse.abs ` ", "对稀疏 Tensor 逐元素求绝对值" + " :ref:`paddle.sparse.pow ` ", "对稀疏 Tensor 逐元素计算 x 的 y 次幂" + " :ref:`paddle.sparse.cast ` ", "对稀疏 Tensor 逐元素转换类型" + " :ref:`paddle.sparse.neg ` ", "对稀疏 Tensor 逐元素计算相反数" + " :ref:`paddle.sparse.deg2rad ` ", "对稀疏 Tensor 逐元素从度转换为弧度" + " :ref:`paddle.sparse.rad2deg ` ", "对稀疏 Tensor 逐元素从弧度转换为度" + " :ref:`paddle.sparse.expm1 ` ", "对稀疏 Tensor 逐元素进行以自然数 e 为底的指数运算并减 1" + " :ref:`paddle.sparse.mv ` ", "稀疏矩阵乘向量，第一个参数为稀疏矩阵，第二个参数为稠密向量" + " :ref:`paddle.sparse.matmul ` ", "稀疏矩阵乘，第一个参数为稀疏矩阵，第二个参数为稠密矩阵或者稀疏矩阵" + " :ref:`paddle.sparse.addmm ` ", "稀疏矩阵乘与加法的组合运算" + " :ref:`paddle.sparse.masked_matmul ` ", "稀疏矩阵乘，第一、二个参数均为稠密矩阵，返回值为稀疏矩阵" + " :ref:`paddle.sparse.add ` ", "对稀疏 Tensor 逐元素相加" + " :ref:`paddle.sparse.subtract ` ", "对稀疏 Tensor 逐元素相减" + " :ref:`paddle.sparse.multiply ` ", "对稀疏 Tensor 逐元素相乘" + " :ref:`paddle.sparse.divide ` ", "对稀疏 Tensor 逐元素相除" + " :ref:`paddle.sparse.is_same_shape ` ", "判断两个稀疏 Tensor 或稠密 Tensor 的 shape 是否一致" + " :ref:`paddle.sparse.reshape ` ", "改变一个 SparseTensor 的形状" + " :ref:`paddle.sparse.coalesce` ", "对 SparseCooTensor 进行排序并合并" + " :ref:`paddle.sparse.transpose ` ", "在不改变数据的情况下改变 ``x`` 的维度顺序, 支持 COO 格式的多维 SparseTensor 以及 COO 格式的 2 维和 3 维 SparseTensor" + +.. _about_sparse_nn: + +稀疏组网类 +:::::::::::::::::::: + +.. csv-table:: + :header: "API 名称", "API 功能" + + " :ref:`paddle.sparse.nn.ReLU ` ", "激活层" + " :ref:`paddle.sparse.nn.ReLU6 ` ", "激活层" + " :ref:`paddle.sparse.nn.LeakyReLU ` ", "激活层" + " :ref:`paddle.sparse.nn.Softmax ` ", "激活层" + " :ref:`paddle.sparse.nn.Conv3D ` ", "三维卷积层" + " :ref:`paddle.sparse.nn.SubmConv3D ` ", "子流形三维卷积层" + " :ref:`paddle.sparse.nn.BatchNorm` ", " Batch Normalization 层" + " :ref:`paddle.sparse.nn.SyncBatchNorm` ", " Synchronized Batch Normalization 层" + " :ref:`paddle.sparse.nn.MaxPool3D` ", "三维最大池化层" + +.. _about_sparse_nn_functional: + +稀疏组网类函数式 API +:::::::::::::::::::: + +.. csv-table:: + :header: "API 名称", "API 功能" + + " :ref:`paddle.sparse.nn.functional.relu ` ", "激活函数" + " :ref:`paddle.sparse.nn.functional.relu6 ` ", "激活函数" + " :ref:`paddle.sparse.nn.functional.leaky_relu ` ", "激活函数" + " :ref:`paddle.sparse.nn.functional.softmax ` ", "激活函数" + " :ref:`paddle.sparse.nn.functional.attention ` ", "稀疏 attention 函数" + " :ref:`paddle.sparse.nn.functional.conv3d ` ", "三维卷积函数" + " :ref:`paddle.sparse.nn.functional.subm_conv3d ` ", "子流形三维卷积函数" + " :ref:`paddle.sparse.nn.functional.max_pool3d ` ", "三维最大池化函数" diff --git a/docs/api/paddle/sparse/abs_cn.rst b/docs/api/paddle/sparse/abs_cn.rst new file mode 100644 index 00000000000..f7fda037455 --- /dev/null +++ b/docs/api/paddle/sparse/abs_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_abs: + +abs +------------------------------- + +.. py:function:: paddle.sparse.abs(x, name=None) + + +逐元素计算输入 :attr:`x` 的绝对值，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = |x| + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.abs diff --git a/docs/api/paddle/incubate/sparse/add_cn.rst b/docs/api/paddle/sparse/add_cn.rst similarity index 78% rename from docs/api/paddle/incubate/sparse/add_cn.rst rename to docs/api/paddle/sparse/add_cn.rst index 9f68cad2ebb..ef892cd8e6a 100644 --- a/docs/api/paddle/incubate/sparse/add_cn.rst +++ b/docs/api/paddle/sparse/add_cn.rst @@ -1,10 +1,9 @@ -.. _cn_api_paddle_incubate_sparse_add: +.. _cn_api_paddle_sparse_add: add ------------------------------- -.. py:function:: paddle.incubate.sparse.add(x, y, name=None) - +.. py:function:: paddle.sparse.add(x, y, name=None) 输入 :attr:`x` 与输入 :attr:`y` 逐元素相加，并将各个位置的输出元素保存到返回结果中。 @@ -14,10 +13,10 @@ add 等式为： .. math:: - Out = X + Y + out = x + y -- :math:`X`：多维稀疏 Tensor。 -- :math:`Y`：多维稀疏 Tensor。 +- :math:`x`：多维稀疏 Tensor。 +- :math:`y`：多维稀疏 Tensor。 参数 ::::::::: @@ -33,4 +32,4 @@ add 代码示例 ::::::::: -COPY-FROM: paddle.incubate.sparse.add +COPY-FROM: paddle.sparse.add diff --git a/docs/api/paddle/sparse/addmm_cn.rst b/docs/api/paddle/sparse/addmm_cn.rst new file mode 100644 index 00000000000..77ee62b5d49 --- /dev/null +++ b/docs/api/paddle/sparse/addmm_cn.rst @@ -0,0 +1,49 @@ +.. _cn_api_paddle_sparse_addmm: + +addmm +------------------------------- + +.. py:function:: paddle.sparse.addmm(input, x, y, beta=1.0, alpha=1.0, name=None) + +.. note:: + 该 API 从 `CUDA 11.0` 开始支持。 + +对输入 :attr:`x` 与输入 :attr:`y` 求稀疏矩阵乘法，并将 `input` 加到计算结果上。 + +数学公式： + +.. math:: + out = alpha * x * y + beta * input + +输入、输出的格式对应关系如下： + +.. note:: + + input[SparseCsrTensor] + x[SparseCsrTensor] @ y[SparseCsrTensor] -> out[SparseCsrTensor] + + input[DenseTensor] + x[SparseCsrTensor] @ y[DenseTensor] -> out[DenseTensor] + + input[SparseCooTensor] + x[SparseCooTensor] @ y[SparseCooTensor] -> out[SparseCooTensor] + + input[DenseTensor] + x[SparseCooTensor] @ y[DenseTensor] -> out[DenseTensor] + +该 API 支持反向传播，`input` 、 `x` 、 `y` 的维度相同且>=2D，不支持自动广播。 + +参数 +::::::::: + - **input** (SparseTensor|DenseTensor) - 输入 Tensor，可以为 Coo 或 Csr 格式 或 DenseTensor。数据类型为 float32、float64。 + - **x** (SparseTensor) - 输入 Tensor，可以为 Coo 或 Csr 格式。数据类型为 float32、float64。 + - **y** (SparseTensor|DenseTensor) - 输入 Tensor，可以为 Coo 或 Csr 格式 或 DenseTensor。数据类型为 float32、float64。 + - **beta** (float, 可选) - `input` 的系数。默认：1.0。 + - **alpha** (float, 可选) - `x * y` 的系数。默认：1.0。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +SparseTensor|DenseTensor: 其 Tensor 类型、dtype、shape 与 `input` 相同。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.addmm diff --git a/docs/api/paddle/sparse/asin_cn.rst b/docs/api/paddle/sparse/asin_cn.rst new file mode 100644 index 00000000000..7b1584681fd --- /dev/null +++ b/docs/api/paddle/sparse/asin_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_asin: + +asin +------------------------------- + +.. py:function:: paddle.sparse.asin(x, name=None) + + +逐元素计算输入 :attr:`x` 的反正弦，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = asin(x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.asin diff --git a/docs/api/paddle/sparse/asinh_cn.rst b/docs/api/paddle/sparse/asinh_cn.rst new file mode 100644 index 00000000000..127485831b9 --- /dev/null +++ b/docs/api/paddle/sparse/asinh_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_asinh: + +asinh +------------------------------- + +.. py:function:: paddle.sparse.asinh(x, name=None) + + +逐元素计算输入 :attr:`x` 的反双曲正弦，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = asinh(x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.asinh diff --git a/docs/api/paddle/sparse/atan_cn.rst b/docs/api/paddle/sparse/atan_cn.rst new file mode 100644 index 00000000000..640b14e1bf3 --- /dev/null +++ b/docs/api/paddle/sparse/atan_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_atan: + +atan +------------------------------- + +.. py:function:: paddle.sparse.atan(x, name=None) + + +逐元素计算输入 :attr:`x` 的反正切，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = atan(x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.atan diff --git a/docs/api/paddle/sparse/atanh_cn.rst b/docs/api/paddle/sparse/atanh_cn.rst new file mode 100644 index 00000000000..4ea48820fe8 --- /dev/null +++ b/docs/api/paddle/sparse/atanh_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_atanh: + +atanh +------------------------------- + +.. py:function:: paddle.sparse.atanh(x, name=None) + + +逐元素计算输入 :attr:`x` 的反双曲正切，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = atanh(x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.atanh diff --git a/docs/api/paddle/sparse/cast_cn.rst b/docs/api/paddle/sparse/cast_cn.rst new file mode 100644 index 00000000000..f408ffffd32 --- /dev/null +++ b/docs/api/paddle/sparse/cast_cn.rst @@ -0,0 +1,26 @@ +.. _cn_api_paddle_sparse_cast: + +cast +------------------------------- + +.. py:function:: paddle.sparse.cast(x, index_dtype=None, value_dtype=None, name=None) + +输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。将稀疏 Tensor 的 index 转换为 `index_dtype` 类型 +（ `SparseCsrTensor` 的 index 指： `crows` 与 `col` ），value 转换为 `value_dtype` 类型， + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **index_dtype** (np.dtype|str, optional) - SparseCooTensor 的 index 类型，SparseCsrTensor 的 crows/cols 类型。可以是 uint8，int8，int16，int32，int64。 + - **value_dtype** (np.dtype|str, optional) - SparseCooTensor 或 SparseCsrTensor 的 value 类型。可以是 uint8，int8，int16，int32，int64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor，稀疏格式与 :attr:`x` 相同，数据类型为被转换后的类型。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.cast diff --git a/docs/api/paddle/sparse/coalesce_cn.rst b/docs/api/paddle/sparse/coalesce_cn.rst new file mode 100644 index 00000000000..07ec3e6959a --- /dev/null +++ b/docs/api/paddle/sparse/coalesce_cn.rst @@ -0,0 +1,22 @@ +.. _cn_api_paddle_sparse_coalesce: + +coalesce +------------------------------- + +.. py:function:: paddle.sparse.coalesce(x, name=None) + +coalesce 操作包含排序和合并相同 indices 两步，执行 coalesce 后，x 变成按 indices 进行有序排序，并行每个 indices 只出现一次。 + +参数 +::::::::: + - **x** (Tensor) - 输入 SparseCooTensor + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +返回 coalesce 后的 SparseCooTensor。 + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.coalesce diff --git a/docs/api/paddle/sparse/deg2rad_cn.rst b/docs/api/paddle/sparse/deg2rad_cn.rst new file mode 100644 index 00000000000..f34825a612d --- /dev/null +++ b/docs/api/paddle/sparse/deg2rad_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_deg2rad: + +deg2rad +------------------------------- + +.. py:function:: paddle.sparse.deg2rad(x, name=None) + + +逐元素将输入 :attr:`x` 从度转换为弧度，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + deg2rad(x) = \pi * x / 180 + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.deg2rad diff --git a/docs/api/paddle/incubate/sparse/divide_cn.rst b/docs/api/paddle/sparse/divide_cn.rst similarity index 78% rename from docs/api/paddle/incubate/sparse/divide_cn.rst rename to docs/api/paddle/sparse/divide_cn.rst index 9247513c42b..d9c78301095 100644 --- a/docs/api/paddle/incubate/sparse/divide_cn.rst +++ b/docs/api/paddle/sparse/divide_cn.rst @@ -1,11 +1,9 @@ -.. _cn_api_paddle_incubate_sparse_divide: +.. _cn_api_paddle_sparse_divide: divide ------------------------------- -.. py:function:: paddle.incubate.sparse.divide(x, y, name=None) - - +.. py:function:: paddle.sparse.divide(x, y, name=None) 输入 :attr:`x` 与输入 :attr:`y` 逐元素相除，并将各个位置的输出元素保存到返回结果中。 @@ -14,10 +12,10 @@ divide 等式为： .. math:: - Out = X / Y + out = x / y -- :math:`X`：多维稀疏 Tensor。 -- :math:`Y`：多维稀疏 Tensor。 +- :math:`x`：多维稀疏 Tensor。 +- :math:`y`：多维稀疏 Tensor。 参数 ::::::::: @@ -33,4 +31,4 @@ divide 代码示例 ::::::::: -COPY-FROM: paddle.incubate.sparse.divide +COPY-FROM: paddle.sparse.divide diff --git a/docs/api/paddle/sparse/expm1_cn.rst b/docs/api/paddle/sparse/expm1_cn.rst new file mode 100644 index 00000000000..ba88b0f1ffa --- /dev/null +++ b/docs/api/paddle/sparse/expm1_cn.rst @@ -0,0 +1,28 @@ +.. _cn_api_paddle_sparse_expm1: + +expm1 +------------------------------- + +.. py:function:: paddle.sparse.expm1(x, name=None) + +逐元素计算输入 :attr:`x` 的 `exp(x)-1` ，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = exp(x) - 1 + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.expm1 diff --git a/docs/api/paddle/incubate/sparse/is_same_shape_cn.rst b/docs/api/paddle/sparse/is_same_shape_cn.rst similarity index 79% rename from docs/api/paddle/incubate/sparse/is_same_shape_cn.rst rename to docs/api/paddle/sparse/is_same_shape_cn.rst index 02f9d5464a8..b22f51b3228 100644 --- a/docs/api/paddle/incubate/sparse/is_same_shape_cn.rst +++ b/docs/api/paddle/sparse/is_same_shape_cn.rst @@ -1,11 +1,9 @@ -.. _cn_api_paddle_incubate_sparse_is_same_shape: +.. _cn_api_paddle_sparse_is_same_shape: is_same_shape ------------------------------- - - -.. py:function:: paddle.incubate.sparse.is_same_shape(x, y) +.. py:function:: paddle.sparse.is_same_shape(x, y) 返回两个 Tensor 形状比较的结果，判断输入 :attr:`x` 与输入 :attr:`y` 的形状是否相同，支持 DenseTensor、SparseCsrTensor 与 SparseCooTensor 之间任意两种的形状比较。 @@ -23,4 +21,4 @@ bool，两个 Tensor 形状比较的结果，相同为 True，不同为 False。 代码示例 ::::::::: -COPY-FROM: paddle.incubate.sparse.is_same_shape +COPY-FROM: paddle.sparse.is_same_shape diff --git a/docs/api/paddle/sparse/log1p_cn.rst b/docs/api/paddle/sparse/log1p_cn.rst new file mode 100644 index 00000000000..29da8106d4d --- /dev/null +++ b/docs/api/paddle/sparse/log1p_cn.rst @@ -0,0 +1,28 @@ +.. _cn_api_paddle_sparse_log1p: + +log1p +------------------------------- + +.. py:function:: paddle.sparse.log1p(x, name=None) + +逐元素计算 :attr:`x+1` 的自然对数，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = ln(1+x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.log1p diff --git a/docs/api/paddle/sparse/masked_matmul_cn.rst b/docs/api/paddle/sparse/masked_matmul_cn.rst new file mode 100644 index 00000000000..4d60b41c7ab --- /dev/null +++ b/docs/api/paddle/sparse/masked_matmul_cn.rst @@ -0,0 +1,40 @@ +.. _cn_api_paddle_sparse_masked_matmul: + +masked_matmul +------------------------------- + +.. py:function:: paddle.sparse.masked_matmul(x, y, mask, name=None) + +.. note:: + 该 API 从 `CUDA 11.3` 开始支持。 + +对输入 :attr:`x` 与输入 :attr:`y` 两个 DenseTensor 求矩阵乘法，同时根据稀疏 Tensor `mask` 进行压缩存储， +返回一个与 `mask` 布局一致的稀疏 Tensor。 + +输入、输出的格式对应关系如下： + +.. note:: + + x[DenseTensor] @ y[DenseTensor] * mask[SparseCooTensor] -> out[SparseCooTensor] + + x[DenseTensor] @ y[DenseTensor] * mask[SparseCsrTensor] -> out[SparseCsrTensor] + +该 API 支持反向传播，`x` 和 `y` 必须 >= 2D，不支持自动广播。 `x` 的 shape 应该为 `[*, M, K]` ， `y` 的 shape 应该为 +`[*, K, N]` ， `mask` 的 shape 应该为 `[*, M, N]` 。其中 `*` 为 0 或者批维度。 + +参数 +::::::::: + - **x** (DenseTensor) - 输入的 DenseTensor。数据类型为 float32、float64。 + - **y** (DenseTensor) - 输入的 DenseTensor。数据类型为 float32、float64。 + - **mask** (SparseTensor) - 输入的稀疏掩码，是一个稀疏 Tensor，可以为 Coo 或 Csr 格式。数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +SparseTensor: 其 Tensor 类型、dtype、shape 均与 `mask` 相同。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.masked_matmul diff --git a/docs/api/paddle/sparse/matmul_cn.rst b/docs/api/paddle/sparse/matmul_cn.rst new file mode 100644 index 00000000000..929ba721b62 --- /dev/null +++ b/docs/api/paddle/sparse/matmul_cn.rst @@ -0,0 +1,42 @@ +.. _cn_api_paddle_sparse_matmul: + +matmul +------------------------------- + +.. py:function:: paddle.sparse.matmul(x, y, name=None) + +.. note:: + 该 API 从 `CUDA 11.0` 开始支持。 + +对输入 :attr:`x` 与输入 :attr:`y` 求稀疏矩阵乘法，`x` 为稀疏 Tensor， `y` 可为稀疏 Tensor 或稠密 Tensor。 + +输入、输出的格式对应关系如下： + +.. note:: + + x[SparseCsrTensor] @ y[SparseCsrTensor] -> out[SparseCsrTensor] + + x[SparseCsrTensor] @ y[DenseTensor] -> out[DenseTensor] + + x[SparseCooTensor] @ y[SparseCooTensor] -> out[SparseCooTensor] + + x[SparseCooTensor] @ y[DenseTensor] -> out[DenseTensor] + +该 API 支持反向传播，`x` 和 `y` 必须 >= 2D，不支持自动广播。 `x` 的 shape 应该为 `[*, M, K]` ， `y` 的 shape 应该为 +`[*, K, N]` ，其中 `*` 为 0 或者批维度。 + +参数 +::::::::: + - **x** (SparseTensor) - 输入的 Tensor，可以为 Coo 或 Csr 格式。数据类型为 float32、float64。 + - **y** (SparseTensor|DenseTensor) - 输入 Tensor，可以为 Coo 或 Csr 格式 或 DenseTensor。数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +SparseTensor|DenseTensor: 其 Tensor 类型由 `x` 和 `y` 共同决定，数据类型与输入相同。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.matmul diff --git a/docs/api/paddle/incubate/sparse/multiply_cn.rst b/docs/api/paddle/sparse/multiply_cn.rst similarity index 77% rename from docs/api/paddle/incubate/sparse/multiply_cn.rst rename to docs/api/paddle/sparse/multiply_cn.rst index b11147861e3..69d4e5b52b5 100644 --- a/docs/api/paddle/incubate/sparse/multiply_cn.rst +++ b/docs/api/paddle/sparse/multiply_cn.rst @@ -1,11 +1,9 @@ -.. _cn_api_paddle_incubate_sparse_multiply: +.. _cn_api_paddle_sparse_multiply: multiply ------------------------------- -.. py:function:: paddle.incubate.sparse.multiply(x, y, name=None) - - +.. py:function:: paddle.sparse.multiply(x, y, name=None) 输入 :attr:`x` 与输入 :attr:`y` 逐元素相乘，并将各个位置的输出元素保存到返回结果中。 @@ -14,10 +12,10 @@ multiply 等式为： .. math:: - Out = X \odot Y + Out = x \odot y -- :math:`X`：多维稀疏 Tensor。 -- :math:`Y`：多维稀疏 Tensor。 +- :math:`x`：多维稀疏 Tensor。 +- :math:`y`：多维稀疏 Tensor。 参数 ::::::::: @@ -33,4 +31,4 @@ multiply 代码示例 ::::::::: -COPY-FROM: paddle.incubate.sparse.multiply +COPY-FROM: paddle.sparse.multiply diff --git a/docs/api/paddle/sparse/mv_cn.rst b/docs/api/paddle/sparse/mv_cn.rst new file mode 100644 index 00000000000..869f79cd940 --- /dev/null +++ b/docs/api/paddle/sparse/mv_cn.rst @@ -0,0 +1,38 @@ +.. _cn_api_paddle_sparse_mv: + +mv +------------------------------- + +.. py:function:: paddle.sparse.mv(x, vec, name=None) + +.. note:: + 该 API 从 `CUDA 11.0` 开始支持。 + +输入 :attr:`x` 为稀疏矩阵，输入 :attr:`vec` 为稠密向量，对 `x` 与 `vec` 计算矩阵与向量相乘。 + +输入、输出的格式对应关系如下： + +.. note:: + + x[SparseCsrTensor] @ vec[DenseTensor] -> out[DenseTensor] + + x[SparseCooTensor] @ vec[DenseTensor] -> out[DenseTensor] + +该 API 支持反向传播。输入 `x` 的 shape 应该为 `[M, N]` ，输入 `vec` 的 shape 应该为 `[N]` ，输出 `out` +的 shape 为 `[M]` 。 + +参数 +::::::::: + - **x** (SparseTensor) - 输入的 2D 稀疏 Tensor，可以为 SparseCooTensor|SparseCsrTensor。数据类型为 float32、float64。 + - **vec** (DenseTensor) - 输入 1D 稠密 Tensor，表示一个向量。数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +DenseTensor: 维度为 1，表示一个向量，数据类型与输入相同。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.mv diff --git a/docs/api/paddle/sparse/neg_cn.rst b/docs/api/paddle/sparse/neg_cn.rst new file mode 100644 index 00000000000..400b7931fdf --- /dev/null +++ b/docs/api/paddle/sparse/neg_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_neg: + +neg +------------------------------- + +.. py:function:: paddle.sparse.neg(x, name=None) + + +逐元素计算 :attr:`x` 的相反数，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = -x + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.neg diff --git a/docs/api/paddle/sparse/nn/BatchNorm_cn.rst b/docs/api/paddle/sparse/nn/BatchNorm_cn.rst new file mode 100644 index 00000000000..b76ac0b0a71 --- /dev/null +++ b/docs/api/paddle/sparse/nn/BatchNorm_cn.rst @@ -0,0 +1,65 @@ +.. _cn_api_paddle_sparse_nn_BatchNorm: + +BatchNorm +------------------------------- + +.. py:class:: paddle.sparse.nn.BatchNorm(num_features, momentum=0.9, epsilon=1e-05, weight_attr=None, bias_attr=None, data_format="NDHWC", use_global_stats=None, name=None) + + +构建稀疏 ``BatchNorm`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。可以处理 4D SparseCooTensor ，实现了批归一化层（Batch Normalization Layer）的功能，可用作卷积和全连接操作的批归一化函数，根据当前批次数据按通道计算的均值和方差进行归一化。更多详情请参考： `Batch Normalization : Accelerating Deep Network Training by Reducing Internal Covariate Shift `_ 。 + +当 use_global_stats = False 时 :math: `\mu_{\beta}` 和 :math: `\sigma_{\beta}^{2}` 是 minibatch 的统计数据。计算公式如下： + +.. math:: + + \mu_{\beta} &\gets \frac{1}{m} \sum_{i=1}^{m} x_i \quad &// mini-batch-mean \\ + \sigma_{\beta}^{2} &\gets \frac{1}{m} \sum_{i=1}^{m}(x_i - \mu_{\beta})^2 \quad &// mini-batch-variance \\ + +- :math:`x` ：批输入数据 +- :math:`m` ：当前批次数据的大小 + +当 use_global_stats = True :math:`\mu_{\beta}` 和 :math:`\sigma_{\beta}^{2}` 是全局（或运行）统计数据（moving_mean 和 moving_variance），通常来自预先训练好的模型。计算公式如下： + +.. math:: + + moving\_mean = moving\_mean * momentum + \mu_{\beta} * (1. - momentum) \quad &// global mean \\ + moving\_variance = moving\_variance * momentum + \sigma_{\beta}^{2} * (1. - momentum) \quad &// global variance \\ + +归一化函数公式如下： + +.. math:: + + \hat{x_i} &\gets \frac{x_i - \mu_\beta} {\sqrt{\sigma_{\beta}^{2} + \epsilon}} \quad &// normalize \\ + y_i &\gets \gamma \hat{x_i} + \beta \quad &// scale-and-shift \\ + +- :math:`\epsilon` ：添加较小的值到方差中以防止除零 +- :math:`\gamma` ：可训练的比例参数 +- :math:`\beta` ：可训练的偏差参数 + +参数 +:::::::::::: + + - **num_features** (int) - 指明输入 ``Tensor`` 的通道数量。 + - **momentum** (float，可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 + - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **weight_attr** (ParamAttr|bool，可选) - 指定权重参数属性的对象。如果为 False，则表示每个通道的伸缩固定为 1，不可改变。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_ParamAttr` 。 + - **bias_attr** (ParamAttr，可选) - 指定偏置参数属性的对象。如果为 False，则表示每一个通道的偏移固定为 0，不可改变。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_ParamAttr` 。 + - **data_format** (string，可选) - 指定输入数据格式，数据格式可以为“NCDHW"。默认值：“NCDHW”。 + - **use_global_stats** (bool，可选) – 指示是否使用全局均值和方差。在预测或测试模式下，将 ``use_global_stats`` 设置为 true 或将 ``is_test`` 设置为 true，这两种行为是等效的。在训练模式中，当设置 ``use_global_stats`` 为 True 时，在训练期间也将使用全局均值和方差。默认值：False。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。 + + +返回 +:::::::::::: +无 + +形状 +:::::::::::: + + - input：形状为（批大小，维度，高度，宽度，通道数）的 5-D SparseCooTensor。 + - output：和输入形状一样。 + +代码示例 +:::::::::::: + +COPY-FROM: paddle.sparse.nn.BatchNorm diff --git a/docs/api/paddle/sparse/nn/Conv3D_cn.rst b/docs/api/paddle/sparse/nn/Conv3D_cn.rst new file mode 100644 index 00000000000..2f593f41b14 --- /dev/null +++ b/docs/api/paddle/sparse/nn/Conv3D_cn.rst @@ -0,0 +1,99 @@ +.. _cn_api_paddle_sparse_nn_Conv3D: + +Conv3D +------------------------------- + +.. py:class:: paddle.sparse.nn.Conv3D(in_channels, out_channels, kernel_size, stride=1, padding=0, dilation=1, groups=1, padding_mode='zeros', weight_attr=None, bias_attr=None, data_format="NDHWC") + +**稀疏三维卷积层** + +稀疏三维卷积层（sparse convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出是 +NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征层高度，W 是特征层宽度。如果 bias_attr 不为 False，卷积计算会添加偏置项。 + +对每个输入 X，有等式： + +.. math:: + + Out = W * X + b + +其中： + + - :math:`X`：输入值，NDHWC 格式的 5-D Tensor + - :math:`W`：卷积核值，DHWCM 格式的 5-D Tensor + - :math:`*`：卷积操作 + - :math:`b`：偏置值，1-D Tensor，形为 ``[M]`` + - :math:`Out`：输出值，NDHWC 格式的 5-D Tensor，和 ``X`` 的形状可能不同 + +参数 +:::::::::::: + + - **in_channels** (int) - 输入图像的通道数。 + - **out_channels** (int) - 由卷积操作产生的输出的通道数。 + - **kernel_size** (int|list|tuple) - 卷积核大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核的深度，高和宽。如果为单个整数，表示卷积核的深度，高和宽都等于该整数。 + - **stride** (int|list|tuple，可选) - 步长大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积沿着深度，高和宽的步长。如果为单个整数，表示沿着高和宽的步长都等于该整数。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有 3 种格式： + + - (1)包含 5 个二元组：当 ``data_format`` 为"NCDHW"时为 [[0,0], [0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为"NDHWC"时为[[0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]； + - (2)包含 6 个整数值：[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]； + - (3)包含 3 个整数值：[padding_depth, padding_height, padding_width]，此时 padding_depth_front = padding_depth_back = padding_depth, padding_height_top = padding_height_bottom = padding_height, padding_width_left = padding_width_right = padding_width。若为一个整数，padding_depth = padding_height = padding_width = padding。默认值：0。 + + - **dilation** (int|list|tuple，可选) - 空洞大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核中的元素沿着深度，高和宽的空洞。如果为单个整数，表示深度，高和宽的空洞都等于该整数。默认值：1。 + - **groups** (int，可选) - 三维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的成组卷积：当 group=n，输入和卷积核分别根据通道数量平均分为 n 组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第 n 组卷积核和第 n 组输入进行卷积计算。默认值：1。 + - **padding_mode** (str，可选) - 填充模式。包括 ``'zeros'``, ``'reflect'``, ``'replicate'`` 或者 ``'circular'``。默认值：``'zeros'`` 。 + - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为 bool 类型，只支持为 False，表示没有偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCDHW"和"NDHWC"。N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度。默认值："NDHWC"。 当前只支持"NDHWC"。 + + +属性 +:::::::::::: + +weight +''''''''' +本层的可学习参数，类型为 ``Parameter`` + +bias +''''''''' +本层的可学习偏置，类型为 ``Parameter`` + +形状 +:::::::::::: + + - 输入：:math:`(N, D_{in}, H_{in}, W_{in}, C_{in})` + - 卷积核：:math:`(K_{d}, K_{h}, K_{w}, C_{in}, C_{out})` + - 偏置：:math:`(C_{out})` + - 输出：:math:`(N, D_{out}, H_{out}, W_{out}, C_{out})` + + 其中 + + .. math:: + + D_{out} &= \frac{\left ( D_{in} + padding\_depth\_front + padding\_depth\_back-\left ( dilation[0]*\left ( kernel\_size[0]-1 \right )+1 \right ) \right )}{stride[0]}+1 + + H_{out} &= \frac{\left ( H_{in} + padding\_height\_top + padding\_height\_bottom-\left ( dilation[1]*\left ( kernel\_size[1]-1 \right )+1 \right ) \right )}{stride[1]}+1 + + W_{out} &= \frac{\left ( W_{in} + padding\_width\_left + padding\_width\_right -\left ( dilation[2]*\left ( kernel\_size[2]-1 \right )+1 \right ) \right )}{stride[2]}+1 + + 如果 ``padding`` = "SAME": + + .. math:: + D_{out} = \frac{(D_{in} + stride[0] - 1)}{stride[0]} + + H_{out} = \frac{(H_{in} + stride[1] - 1)}{stride[1]} + + W_{out} = \frac{(W_{in} + stride[2] - 1)}{stride[2]} + + 如果 ``padding`` = "VALID": + + .. math:: + D_{out} = \frac{\left ( D_{in} -\left ( dilation[0]*\left ( kernel\_size[0]-1 \right )+1 \right ) \right )}{stride[0]}+1 + + H_{out} = \frac{\left ( H_{in} -\left ( dilation[1]*\left ( kernel\_size[1]-1 \right )+1 \right ) \right )}{stride[1]}+1 + + W_{out} = \frac{\left ( W_{in} -\left ( dilation[2]*\left ( kernel\_size[2]-1 \right )+1 \right ) \right )}{stride[2]}+1 + + +代码示例 +:::::::::::: + +COPY-FROM: paddle.sparse.nn.Conv3D diff --git a/docs/api/paddle/sparse/nn/LeakyReLU_cn.rst b/docs/api/paddle/sparse/nn/LeakyReLU_cn.rst new file mode 100644 index 00000000000..5c61d818c2f --- /dev/null +++ b/docs/api/paddle/sparse/nn/LeakyReLU_cn.rst @@ -0,0 +1,33 @@ +.. _cn_api_paddle_sparse_nn_LeakyReLU: + +LeakyReLU +------------------------------- +.. py:class:: paddle.sparse.nn.LeakyReLU(negative_slope=0.01, name=None) + +稀疏 LeakyReLU 激活层，创建一个可调用对象以计算输入 `x` 的 `LeakReLU` 。 + +.. math:: + LeakyReLU(x)= + \left\{ + \begin{array}{rcl} + x, & & if \ x >= 0 \\ + negative\_slope * x, & & otherwise \\ + \end{array} + \right. + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - **negative_slope** (float，可选) - :math:`x < 0` 时的斜率。默认值为 0.01。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +形状 +::::::::: + - input：任意形状的 SparseTensor。 + - output：和 input 具有相同形状和数据类型的 SparseTensor。 + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.LeakyReLU diff --git a/docs/api/paddle/sparse/nn/MaxPool3D_cn.rst b/docs/api/paddle/sparse/nn/MaxPool3D_cn.rst new file mode 100644 index 00000000000..e966be62fb9 --- /dev/null +++ b/docs/api/paddle/sparse/nn/MaxPool3D_cn.rst @@ -0,0 +1,36 @@ +.. _cn_api_paddle_sparse_nn_MaxPool3D: + +MaxPool3D +------------------------------- + +.. py:function:: paddle.sparse.nn.MaxPool3D(kernel_size, stride=None, padding=0, ceil_mode=False, return_mask=False, data_format="NDHWC", name=None) + +构建 `MaxPool3D` 类的一个可调用对象，其将构建一个三维最大池化层，根据输入参数 `kernel_size`, `stride`, +`padding` 等参数对稀疏输入特征做最大池化操作。 输入输出都是 "NDHWC" 格式，其中 N 是批大小， C 是特征的通道数， H 是特征的高， W 是特征的宽。 + +参数 +::::::::: + - **kernel_size** (int|list|tuple) - 池化核大小。如果它是一个元组或列表，它必须包含三个整数值，(pool_size_Depth，pool_size_Height, pool_size_Width)。若为一个整数，则表示 D，H 和 W 维度上均为该值，比如若 kernel_size=2，则池化核大小为[2,2,2]。 + - **stride** (int|list|tuple，可选) - 池化层的步长。如果它是一个元组或列表，它将包含三个整数，(pool_stride_Depth，pool_stride_Height, pool_stride_Width)。若为一个整数，则表示 D, H 和 W 维度上 stride 均为该值。默认值为 None ，这时会使用 kernel_size 作为 stride 。 + - **padding** (str|int|list|tuple，可选) - 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 3 个整数值：[pad_depth, pad_height, pad_width]；(2)包含 6 个整数值：[pad_depth_front, pad_depth_back, pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]；(3)包含 5 个二元组：当 data_format 为"NCDHW"时为[[0,0], [0,0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NDHWC"时为[[0,0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 D、H 和 W 维度上均为该值。默认值：0 。 + - **ceil_mode** (bool，可选) - 是否用 ceil 函数计算输出高度和宽度。如果是 True ，则使用 `ceil` 计算输出形状的大小。默认为 False 。 + - **return_mask** (bool，可选) - 是否返回最大索引和输出。默认为 False 。 + - **data_format** (str，可选) - 输入和输出的数据格式，可以是"NCDHW"和"NDHWC"。N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度。当前只支持："NDHWC" 。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None 。 + + +形状 +::::::::: + - **x** (Tensor)：默认形状为（批大小，通道数，长度，高度，宽度），即 NCDHW 格式的 5-D Tensor。其数据类型为 float16, float32, float64, int32 或 int64。 + - **output** (Tensor)：默认形状为（批大小，通道数，输出特征长度，输出特征高度，输出特征宽度），即 NCDHW 格式的 5-D Tensor。其数据类型与输入相同。 + + +返回 +::::::::: +计算 MaxPool3D 的可调用对象 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.MaxPool3D diff --git a/docs/api/paddle/sparse/nn/ReLU6_cn.rst b/docs/api/paddle/sparse/nn/ReLU6_cn.rst new file mode 100644 index 00000000000..fe6987130eb --- /dev/null +++ b/docs/api/paddle/sparse/nn/ReLU6_cn.rst @@ -0,0 +1,26 @@ +.. _cn_api_paddle_sparse_nn_ReLU6: + +ReLU6 +------------------------------- +.. py:class:: paddle.sparse.nn.ReLU6(name=None) + +稀疏 ReLU6 激活层，创建一个可调用对象以计算输入 `x` 的 `ReLU6` 。 + +.. math:: + ReLU6(x) = min(max(0,x), 6) + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +形状 +::::::::: + - input：任意形状的 SparseTensor。 + - output：和 input 具有相同形状和数据类型的 SparseTensor。 + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.ReLU6 diff --git a/docs/api/paddle/sparse/nn/ReLU_cn.rst b/docs/api/paddle/sparse/nn/ReLU_cn.rst new file mode 100644 index 00000000000..ce8abe3b462 --- /dev/null +++ b/docs/api/paddle/sparse/nn/ReLU_cn.rst @@ -0,0 +1,26 @@ +.. _cn_api_paddle_sparse_nn_ReLU: + +ReLU +------------------------------- +.. py:class:: paddle.sparse.nn.ReLU(name=None) + +稀疏 ReLU 激活层，创建一个可调用对象以计算输入 `x` 的 `ReLU` 。 + +.. math:: + ReLU(x) = max(x, 0) + +其中，:math:`x` 为输入的 Tensor + +参数 +:::::::::: + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +形状 +::::::::: + - input：任意形状的 SparseTensor。 + - output：和 input 具有相同形状和数据类型的 SparseTensor。 + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.ReLU diff --git a/docs/api/paddle/sparse/nn/Softmax_cn.rst b/docs/api/paddle/sparse/nn/Softmax_cn.rst new file mode 100644 index 00000000000..5e8137a4384 --- /dev/null +++ b/docs/api/paddle/sparse/nn/Softmax_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_nn_Softmax: + +Softmax +------------------------------- +.. py:class:: paddle.sparse.nn.Softmax(axis=-1, name=None) + +稀疏 Softmax 激活层，创建一个可调用对象以计算输入 `x` 的 `Softmax` 。 + +当输入 `x` 为 `SparseCsrTensor` 时，仅支持 axis=-1，是由于 Csr 稀疏存储格式，更适合按行读取数据。 + +如果将 `x` 从稀疏矩阵转换为稠密矩阵， :math:`i` 代表行数， :math:`j` 代表列数，且 axis=-1 时有如下公式： + +.. math:: + softmax_ij = \frac{\exp(x_ij - max_j(x_ij))}{\sum_j(exp(x_ij - max_j(x_ij))} + +参数 +:::::::::: + - **axis** (int, 可选) - 指定对输入 SparseTensor 计算 softmax 的轴。对于 SparseCsrTensor，仅支持 axis=-1。默认值：-1。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +形状 +::::::::: + - input：任意形状的 SparseTensor。 + - output：和 input 具有相同形状和数据类型的 SparseTensor。 + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.Softmax diff --git a/docs/api/paddle/sparse/nn/SubmConv3D_cn.rst b/docs/api/paddle/sparse/nn/SubmConv3D_cn.rst new file mode 100644 index 00000000000..645de32af4f --- /dev/null +++ b/docs/api/paddle/sparse/nn/SubmConv3D_cn.rst @@ -0,0 +1,100 @@ +.. _cn_api_paddle_sparse_nn_SubmConv3D: + +SubmConv3D +------------------------------- + +.. py:class:: paddle.sparse.nn.SubmConv3D(in_channels, out_channels, kernel_size, stride=1, padding=0, dilation=1, groups=1, padding_mode='zeros', key=None, weight_attr=None, bias_attr=None, data_format="NDHWC") + +**子流形稀疏三维卷积层** + +子流形稀疏三维卷积层（submanifold sparse convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出是 +NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征层高度，W 是特征层宽度。如果 bias_attr 不为 False，卷积计算会添加偏置项。 + +对每个输入 X，有等式： + +.. math:: + + Out = W * X + b + +其中： + + - :math:`X` ：输入值，NDHWC 格式的 5-D Tensor + - :math:`W` ：卷积核值，DHWCM 格式的 5-D Tensor + - :math:`*` ：子流形稀疏卷积操作的定义参考论文：https://arxiv.org/abs/1706.01307 + - :math:`b` ：偏置值，1-D Tensor，形为 ``[M]`` + - :math:`Out` ：输出值，NDHWC 格式的 5-D Tensor，和 ``X`` 的形状可能不同 + +参数 +:::::::::::: + + - **in_channels** (int) - 输入图像的通道数。 + - **out_channels** (int) - 由卷积操作产生的输出的通道数。 + - **kernel_size** (int|list|tuple) - 卷积核大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核的深度，高和宽。如果为单个整数，表示卷积核的深度，高和宽都等于该整数。 + - **stride** (int|list|tuple，可选) - 步长大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积沿着深度，高和宽的步长。如果为单个整数，表示沿着高和宽的步长都等于该整数。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是 "VALID" 或者 "SAME" ，表示填充算法，计算细节可参考上述 ``padding`` = "SAME" 或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有 3 种格式： + + - (1)包含 5 个二元组：当 ``data_format`` 为 "NCDHW" 时为 [[0,0], [0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为 "NDHWC" 时为[[0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]； + - (2)包含 6 个整数值：[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]； + - (3)包含 3 个整数值：[padding_depth, padding_height, padding_width]，此时 padding_depth_front = padding_depth_back = padding_depth, padding_height_top = padding_height_bottom = padding_height, padding_width_left = padding_width_right = padding_width。若为一个整数，padding_depth = padding_height = padding_width = padding。默认值：0。 + + - **dilation** (int|list|tuple，可选) - 空洞大小。可以为单个整数或包含三个整数的元组或列表，分别表示卷积核中的元素沿着深度，高和宽的空洞。如果为单个整数，表示深度，高和宽的空洞都等于该整数。默认值：1。 + - **groups** (int，可选) - 三维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的成组卷积：当 group = n ，输入和卷积核分别根据通道数量平均分为 n 组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第 n 组卷积核和第 n 组输入进行卷积计算。默认值：1。 + - **padding_mode** (str，可选) - 填充模式。包括 ``'zeros'``, ``'reflect'``, ``'replicate'`` 或者 ``'circular'`` 。默认值：``'zeros'`` 。 + - **key** (str，可选) - 这个 key 是用来保存或者使用相同的 rulebook ，rulebook 的定义参考论文：https://pdfs.semanticscholar.org/5125/a16039cabc6320c908a4764f32596e018ad3.pdf。 默认是 None。 + - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为 bool 类型，只支持为 False，表示没有偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是 "NCDHW" 和 "NDHWC" 。N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度。默认值："NDHWC" 。 当前只支持 "NDHWC" 。 + + +属性 +:::::::::::: + +weight +''''''''' +本层的可学习参数，类型为 ``Parameter`` + +bias +''''''''' +本层的可学习偏置，类型为 ``Parameter`` + +形状 +:::::::::::: + + - 输入：:math:`(N, D_{in}, H_{in}, W_{in}, C_{in})` + - 卷积核：:math:`(K_{d}, K_{h}, K_{w}, C_{in}, C_{out})` + - 偏置：:math:`(C_{out})` + - 输出：:math:`(N, D_{out}, H_{out}, W_{out}, C_{out})` + + 其中 + + .. math:: + + D_{out} &= \frac{\left ( D_{in} + padding\_depth\_front + padding\_depth\_back-\left ( dilation[0]*\left ( kernel\_size[0]-1 \right )+1 \right ) \right )}{stride[0]}+1 + + H_{out} &= \frac{\left ( H_{in} + padding\_height\_top + padding\_height\_bottom-\left ( dilation[1]*\left ( kernel\_size[1]-1 \right )+1 \right ) \right )}{stride[1]}+1 + + W_{out} &= \frac{\left ( W_{in} + padding\_width\_left + padding\_width\_right -\left ( dilation[2]*\left ( kernel\_size[2]-1 \right )+1 \right ) \right )}{stride[2]}+1 + + 如果 ``padding`` = "SAME": + + .. math:: + D_{out} = \frac{(D_{in} + stride[0] - 1)}{stride[0]} + + H_{out} = \frac{(H_{in} + stride[1] - 1)}{stride[1]} + + W_{out} = \frac{(W_{in} + stride[2] - 1)}{stride[2]} + + 如果 ``padding`` = "VALID": + + .. math:: + D_{out} = \frac{\left ( D_{in} -\left ( dilation[0]*\left ( kernel\_size[0]-1 \right )+1 \right ) \right )}{stride[0]}+1 + + H_{out} = \frac{\left ( H_{in} -\left ( dilation[1]*\left ( kernel\_size[1]-1 \right )+1 \right ) \right )}{stride[1]}+1 + + W_{out} = \frac{\left ( W_{in} -\left ( dilation[2]*\left ( kernel\_size[2]-1 \right )+1 \right ) \right )}{stride[2]}+1 + + +代码示例 +:::::::::::: + +COPY-FROM: paddle.sparse.nn.SubmConv3D diff --git a/docs/api/paddle/sparse/nn/SyncBatchNorm_cn.rst b/docs/api/paddle/sparse/nn/SyncBatchNorm_cn.rst new file mode 100644 index 00000000000..578cbcd99c6 --- /dev/null +++ b/docs/api/paddle/sparse/nn/SyncBatchNorm_cn.rst @@ -0,0 +1,83 @@ +.. _cn_api_paddle_sparse_nn_SyncBatchNorm: + +SyncBatchNorm +------------------------------- + +.. py:class:: paddle.sparse.nn.SyncBatchNorm(num_features, epsilon=1e-5, momentum=0.9, weight_attr=None, bias_attr=None, data_format='NCHW', name=None) + +构建 ``SyncBatchNorm`` 类的一个可调用对象，具体用法参照 ``代码示例`` 。实现了跨卡 GPU 同步的批归一化(Cross-GPU Synchronized Batch Normalization Layer)的功能，可用在其他层（类似卷积层和全连接层）之后进行归一化操作。根据所有 GPU 同一批次的数据按照通道计算的均值和方差进行归一化。更多详情请参考：`Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift `_ 。 + +当模型处于训练模式时，:math:`\mu_{\beta}` 和 :math:`\sigma_{\beta}^{2}` 是所有 GPU 上同一 minibatch 的统计数据。计算公式如下： + +.. math:: + \mu_{\beta} &\gets \frac{1}{m} \sum_{i=1}^{m} x_i \quad &// mini-batch-mean \\ + \sigma_{\beta}^{2} &\gets \frac{1}{m} \sum_{i=1}^{m}(x_i - \mu_{\beta})^2 \quad &// mini-batch-variance \\ + +- :math:`x` ：所有 GPU 上同一批输入数据 +- :math:`m` ：所有 GPU 上同一批次数据的大小 + +当模型处于评估模式时，:math:`\mu_{\beta}` 和 :math:`\sigma_{\beta}^{2}` 是全局（或运行）统计数据（moving_mean 和 moving_variance，这两个统计量通常来自预先训练好的模型）。计算公式如下： + +.. math:: + + moving\_mean = moving\_mean * momentum + \mu_{\beta} * (1. - momentum) \quad &// global mean \\ + moving\_variance = moving\_variance * momentum + \sigma_{\beta}^{2} * (1. - momentum) \quad &// global variance \\ + +归一化函数公式如下： + +.. math:: + + \hat{x_i} &\gets \frac{x_i - \mu_\beta} {\sqrt{\sigma_{\beta}^{2} + \epsilon}} \quad &// normalize \\ + y_i &\gets \gamma \hat{x_i} + \beta \quad &// scale-and-shift \\ + +- :math:`\epsilon` ：添加较小的值到方差中以防止除零 +- :math:`\gamma` ：可训练的比例参数 +- :math:`\beta` ：可训练的偏差参数 + +.. note:: + + 如果您想用容器封装您的模型，而且您的模型在预测阶段中包含 ``SyncBatchNorm`` 这个算子的话，请使用 ``nn.LayerList`` 或者 ``nn.Sequential`` 而不要直接使用 ``list`` 来封装模型。 + +参数 +:::::::::::: + + - **num_features** (int) - 指明输入 ``Tensor`` 的通道数量。 + - **epsilon** (float，可选) - 为了数值稳定加在分母上的值。默认值：1e-05。 + - **momentum** (float，可选) - 此值用于计算 ``moving_mean`` 和 ``moving_var`` 。默认值：0.9。更新公式如上所示。 + - **weight_attr** (ParamAttr|bool，可选) - 指定权重参数属性的对象。如果设置为 ``False`` ，则表示本层没有可训练的权重参数。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数属性的对象。如果设置为 ``False`` ，则表示本层没有可训练的偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (string，可选) - 指定输入数据格式，数据格式可以为“NCHW"。默认值：“NCHW”。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。 + +形状 +:::::::::::: + + - input：一个二维到五维的 ``Tensor`` 。 + - output：和 input 相同形状的 ``Tensor`` 。 + +代码示例 +:::::::::::: + +COPY-FROM: paddle.sparse.nn.SyncBatchNorm + +方法 +::::::::: +convert_sync_batchnorm(layer) +''''''''''''''''''''''''''''' + +把 ``BatchNorm`` 层转换为 ``SyncBatchNorm`` 层。 + +参数 +:::::::::::: + + - **layer** (paddle.nn.Layer) - 包含一个或多个 ``BatchNorm`` 层的模型。 + +返回 +:::::::::::: + + 如果原始模型中有 ``BatchNorm`` 层，则把 ``BatchNorm`` 层转换为 ``SyncBatchNorm`` 层的原始模型。 + +代码示例 +:::::::::::: + +COPY-FROM: paddle.sparse.nn.SyncBatchNorm.convert_sync_batchnorm diff --git a/docs/api/paddle/sparse/nn/functional/attention_cn.rst b/docs/api/paddle/sparse/nn/functional/attention_cn.rst new file mode 100644 index 00000000000..5f36ad1c5cc --- /dev/null +++ b/docs/api/paddle/sparse/nn/functional/attention_cn.rst @@ -0,0 +1,41 @@ +.. _cn_api_paddle_sparse_nn_functional_attention: + +attention +------------------------------- +.. py:function:: paddle.sparse.nn.functional.attention(query, key, value, sparse_mask, key_padding_mask=None, attn_mask=None, name=None) + +.. note:: + 该 API 从 `CUDA 11.7` 开始支持。 + +稀疏 Attention，该 API 内部使用 SparseCsrTensor 来存储 Transformer 模块中的 attention 矩阵，从而达到减少显存占用、提高性能的目的。 +参数 `sparse_mask` 描述了稀疏矩阵的非 0 元素索引布局。 + +.. math:: + result = softmax(\frac{ Q * K^T }{\sqrt{d}}) * V + +其中：矩阵 `Q` `K` `V` 表示 attention 模块的三个输入 Tensor，其 shape 均为 `[batch_size, num_heads, seq_len, head_dim]` ， +公式中的 `d` 代表 `head_dim` 。 + +参数 +:::::::::: + - **query** (DenseTensor) - Attention 模块的 `query` 输入，4D Tensor，数据类型为 float32、float64。 + - **key** (DenseTensor) - Attention 模块的 `key` 输入，4D Tensor，数据类型为 float32、float64。 + - **value** (DenseTensor) - Attention 模块的 `value` 输入，4D Tensor，数据类型为 float32、float64。 + - **sparse_mask** (SparseCsrTensor) - Attention 模块的非 0 元素布局，是一个 3D 的 SparseCsrTensor，shape 为 `[batch_size*num_heads, seq_len, seq_len]` 。 + 同时每个批次的非 0 元素个数均相等。`crows` 和 `cols` 的数据类型为 int64，`value` 的数据类型为 float32、float64。 + - **key_padding_mask** (DenseTensor, 可选) - Attention 模块中的 key padding mask，是一个 2D 的 DenseTensor，shape 为 `[batch_size, seq_len]` 。 + 数据类型为 float32、float64。默认：None，表示无此掩码运算。 + - **attn_mask** (DenseTensor, 可选) - Attention 模块中的 attention mask，是一个 2D 的 DenseTensor，shape 为 `[seq_len, seq_len]` 。 + 数据类型为 float32、float64。默认：None，表示无此掩码运算。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + + +返回 +::::::::: +DenseTensor: 维度为 4，shape 为 `[batch_size, num_heads, seq_len, head_dim]` ，dtype 与输入相同。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.functional.attention diff --git a/docs/api/paddle/sparse/nn/functional/conv3d_cn.rst b/docs/api/paddle/sparse/nn/functional/conv3d_cn.rst new file mode 100644 index 00000000000..2f5f5c1aec4 --- /dev/null +++ b/docs/api/paddle/sparse/nn/functional/conv3d_cn.rst @@ -0,0 +1,69 @@ +.. _cn_api_paddle_sparse_nn_functional_conv3d: + +conv3d +------------------------------- + +.. py:function:: paddle.sparse.nn.functional.conv3d(x, weight, bias=None, stride=1, padding=0, dilation=1, groups=1, data_format="NDHWC", name=None) + +稀疏三维卷积层（convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出是 NCDHW 或 NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征层高度，W 是特征层宽度。如果 bias_attr 不为 False，卷积计算会添加偏置项。 + +对每个输入 X ，有等式： + +.. math:: + + Out = W * X + b + +其中： + + - :math:`X` ：输入值，NCDHW 或 NDHWC 格式的 5-D Tensor + - :math:`W` ：卷积核值，MCDHW 格式的 5-D Tensor + - :math:`*` ：卷积操作 + - :math:`b` ：偏置值，1-D Tensor，形为 ``[M]`` + - :math:`Out` ：输出值，NCDHW 或 NDHWC 格式的 5-D Tensor，和 ``X`` 的形状可能不同 + +**示例** + +- 输入： + + 输入形状：:math:`(N, D_{in}, H_{in}, W_{in}, C_{in})` + + 卷积核形状：:math:`(D_f, H_f, W_f, C_{in}, C_{out})` + +- 输出： + + 输出形状：:math:`(N, D_{out}, H_{out}, W_{out}, C_{out})` + +参数 +:::::::::::: + + - **x** (Tensor) - 输入是形状为 :math:`[N, D, H, W, C]` 的 5-D SparseCooTensor，N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征高度，W 是特征宽度，数据类型为 float16, float32 或 float64 。 + - **weight** (Tensor) - 形状为 :math:`[kD, kH, kW, C/g, M]` 的卷积核（卷积核）。 M 是输出通道数，g 是分组的个数，kH 是卷积核的高度，kW 是卷积核的宽度。 + - **bias** (Tensor，可选) - 偏置项，形状为：:math:`[M]` 。 + - **stride** (int|list|tuple，可选) - 步长大小。卷积核和输入进行卷积计算时滑动的步长。 + + - 如果它是一个列表或元组，则必须包含三个整型数：（stride_depth, stride_height,stride_width）。 + - 若为一个整数，stride_depth = stride_height = stride_width = stride。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有 3 种格式： + + - (1)包含 5 个二元组：当 ``data_format`` 为"NCDHW"时为 [[0,0], [0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为"NDHWC"时为[[0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]； + - (2)包含 6 个整数值：[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]； + - (3)包含 3 个整数值：[padding_depth, padding_height, padding_width]，此时 padding_depth_front = padding_depth_back = padding_depth, padding_height_top = padding_height_bottom = padding_height, padding_width_left = padding_width_right = padding_width。若为一个整数，padding_depth = padding_height = padding_width = padding。默认值：0。 + - **dilation** (int|list|tuple，可选) - 空洞大小。空洞卷积时会使用该参数，卷积核对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果空洞大小为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 + - **groups** (int，可选) - 二维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的成组卷积：当 group=n，输入和卷积核分别根据通道数量平均分为 n 组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第 n 组卷积核和第 n 组输入进行卷积计算。默认值：1。 + - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **bias_attr** （ParamAttr|bool，可选）- 指定偏置参数属性的对象。若 ``bias_attr`` 为 bool 类型，只支持为 False，表示没有偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCDHW"和"NDHWC"。N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征高度，W 是特征宽度。默认值："NCDHW"。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。 + +返回 +:::::::::::: +5-D Tensor ，数据类型与 ``input`` 一致。返回卷积计算的结果。 + +返回类型 +:::::::::::: +Tensor。 + +代码示例 +:::::::::::: + +COPY-FROM: paddle.sparse.nn.functional.conv3d diff --git a/docs/api/paddle/sparse/nn/functional/leaky_relu_cn.rst b/docs/api/paddle/sparse/nn/functional/leaky_relu_cn.rst new file mode 100644 index 00000000000..331ef21ed0c --- /dev/null +++ b/docs/api/paddle/sparse/nn/functional/leaky_relu_cn.rst @@ -0,0 +1,33 @@ +.. _cn_api_paddle_sparse_nn_functional_leaky_relu: + +leaky_relu +------------------------------- +.. py:function:: paddle.sparse.nn.functional.leaky_relu(x, negative_slope=0.01, name=None) + +稀疏 leaky_relu 激活函数，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +.. math:: + leaky_relu(x)= + \left\{ + \begin{array}{rcl} + x, & & if \ x >= 0 \\ + negative\_slope * x, & & otherwise \\ + \end{array} + \right. + +其中，:math:`x` 为输入的 Tensor。 + +参数 +:::::::::: + - **x** (Tensor) - 输入的稀疏 Tensor，可以是 SparseCooTensor 或 SparseCsrTensor，数据类型为 float32、float64。 + - **negative_slope** (float，可选) - :math:`x < 0` 时的斜率。默认值为 0.01。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同。 + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.functional.leaky_relu diff --git a/docs/api/paddle/sparse/nn/functional/max_pool3d_cn.rst b/docs/api/paddle/sparse/nn/functional/max_pool3d_cn.rst new file mode 100644 index 00000000000..b780e6ef0f9 --- /dev/null +++ b/docs/api/paddle/sparse/nn/functional/max_pool3d_cn.rst @@ -0,0 +1,35 @@ +.. _cn_api_paddle_sparse_nn_functional_max_pool3d: + + +max_pool3d +------------------------------- + +.. py:function:: paddle.sparse.nn.functional.max_pool3d(x, kernel_size, stride=None, padding=0, ceil_mode=False, data_format="NDHWC", name=None) + +该函数是一个三维最大池化函数，根据输入参数 `kernel_size` , `stride` , `padding` 等参数对输入 `x` 做最大池化操作。 + +参数 +::::::::: + - **x** (Tensor) - 形状为 [N,D,H,W, C] 的 5-D SparseCooTensor，N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度，数据类型为 float32 或 float64。 + - **kernel_size** (int|list|tuple) - 池化核大小。如果它是一个元组或列表，它必须包含三个整数值，(pool_size_Depth，pool_size_Height, pool_size_Width)。若为一个整数，则表示 D，H 和 W 维度上均为该值，比如若 kernel_size=2，则池化核大小为[2,2,2]。 + - **stride** (int|list|tuple，可选) - 池化层的步长。如果它是一个元组或列表，它将包含三个整数，(pool_stride_Depth，pool_stride_Height, pool_stride_Width)。若为一个整数，则表示 D, H 和 W 维度上 stride 均为该值。默认值为 kernel_size。 + - **padding** (string|int|list|tuple，可选) - 池化填充。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法。如果它是一个元组或列表，它可以有 3 种格式： + + - (1)包含 3 个整数值：[pad_depth, pad_height, pad_width]； + - (2)包含 6 个整数值：[pad_depth_front, pad_depth_back, pad_height_top, pad_height_bottom, pad_width_left, pad_width_right]； + - (3)包含 5 个二元组：当 data_format 为"NCDHW"时为[[0,0], [0,0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right]]，当 data_format 为"NDHWC"时为[[0,0], [pad_depth_front, pad_depth_back], [pad_height_top, pad_height_bottom], [pad_width_left, pad_width_right], [0,0]]。若为一个整数，则表示 D、H 和 W 维度上均为该值。默认值：0 + - **ceil_mode** (bool，可选) - 是否用 ceil 函数计算输出高度和宽度。如果是 True，则使用 `ceil` 计算输出形状的大小。默认为 False + - **data_format** (str，可选) - 输入和输出的数据格式，可以是"NCDHW"和"NDHWC"。N 是批尺寸，C 是通道数，D 是特征深度，H 是特征高度，W 是特征宽度。当前只支持："NDHWC"。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None。 + + + +返回 +::::::::: +5-D Tensor，数据类型与输入 x 一致。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.functional.max_pool3d diff --git a/docs/api/paddle/sparse/nn/functional/relu6_cn.rst b/docs/api/paddle/sparse/nn/functional/relu6_cn.rst new file mode 100644 index 00000000000..e612638612c --- /dev/null +++ b/docs/api/paddle/sparse/nn/functional/relu6_cn.rst @@ -0,0 +1,26 @@ +.. _cn_api_paddle_sparse_nn_functional_relu6: + +relu6 +------------------------------- +.. py:function:: paddle.sparse.nn.functional.relu6(x, name=None) + +稀疏 relu6 激活函数，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +.. math:: + relu6(x) = min(max(0, x), 6) + +其中，:math:`x` 为输入的 Tensor。 + +参数 +:::::::::: + - **x** (Tensor) - 输入的稀疏 Tensor，可以是 SparseCooTensor 或 SparseCsrTensor，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同。 + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.functional.relu6 diff --git a/docs/api/paddle/sparse/nn/functional/relu_cn.rst b/docs/api/paddle/sparse/nn/functional/relu_cn.rst new file mode 100644 index 00000000000..99393c62514 --- /dev/null +++ b/docs/api/paddle/sparse/nn/functional/relu_cn.rst @@ -0,0 +1,26 @@ +.. _cn_api_paddle_sparse_nn_functional_relu: + +relu +------------------------------- +.. py:function:: paddle.sparse.nn.functional.relu(x, name=None) + +稀疏 relu 激活函数，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +.. math:: + relu(x) = max(x, 0) + +其中，:math:`x` 为输入的 Tensor。 + +参数 +:::::::::: + - **x** (Tensor) - 输入的稀疏 Tensor，可以是 SparseCooTensor 或 SparseCsrTensor，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同。 + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.functional.relu diff --git a/docs/api/paddle/sparse/nn/functional/softmax_cn.rst b/docs/api/paddle/sparse/nn/functional/softmax_cn.rst new file mode 100644 index 00000000000..b2958e1aeee --- /dev/null +++ b/docs/api/paddle/sparse/nn/functional/softmax_cn.rst @@ -0,0 +1,31 @@ +.. _cn_api_paddle_sparse_nn_functional_softmax: + +softmax +------------------------------- +.. py:function:: paddle.sparse.nn.functional.softmax(x, axis=-1, name=None) + +稀疏 softmax 激活函数，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +当输入 `x` 为 `SparseCsrTensor` 时，仅支持 axis=-1，是由于 Csr 稀疏存储格式，更适合按行读取数据。 + +如果将 `x` 从稀疏矩阵转换为稠密矩阵， :math:`i` 代表行数， :math:`j` 代表列数，且 axis=-1 时有如下公式： + +.. math:: + softmax_ij = \frac{\exp(x_ij - max_j(x_ij))}{\sum_j(exp(x_ij - max_j(x_ij))} + +其中，:math:`x` 为输入的 Tensor。 + +参数 +:::::::::: + - **x** (Tensor) - 输入的稀疏 Tensor，可以是 SparseCooTensor 或 SparseCsrTensor，数据类型为 float32、float64。 + - **axis** (int, 可选) - 指定对输入 SparseTensor 计算 softmax 的轴。对于 SparseCsrTensor，仅支持 axis=-1。默认值：-1。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同。 + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.nn.functional.softmax diff --git a/docs/api/paddle/sparse/nn/functional/subm_conv3d_cn.rst b/docs/api/paddle/sparse/nn/functional/subm_conv3d_cn.rst new file mode 100644 index 00000000000..49a23d7d53e --- /dev/null +++ b/docs/api/paddle/sparse/nn/functional/subm_conv3d_cn.rst @@ -0,0 +1,63 @@ +.. _cn_api_paddle_sparse_nn_functional_subm_conv3d: + +subm_conv3d +------------------------------- + +.. py:function:: paddle.sparse.nn.functional.subm_conv3d(x, weight, bias=None, stride=1, padding=0, dilation=1, groups=1, data_format="NDHWC", key=None, name=None) + +子流形稀疏三维卷积层（convolution3D layer），根据输入、卷积核、步长（stride）、填充（padding）、空洞大小（dilations）一组参数计算得到输出特征层大小。输入和输出是 NCDHW 或 NDHWC 格式，其中 N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征层高度，W 是特征层宽度。如果 bias_attr 不为 False，卷积计算会添加偏置项。 + +对每个输入 X，有等式： + +.. math:: + + Out = W * X + b + +其中： + + - :math:`X` ：输入值，NCDHW 或 NDHWC 格式的 5-D Tensor + - :math:`W` ：卷积核值，MCDHW 格式的 5-D Tensor + - :math:`*` ：卷积操作 + - :math:`b` ：偏置值，1-D Tensor，形为 ``[M]`` + - :math:`Out` ：输出值，NCDHW 或 NDHWC 格式的 5-D Tensor，和 ``X`` 的形状可能不同 + +**示例** + +- 输入： + + 输入形状：:math:`(N, D_{in}, H_{in}, W_{in}, C_{in})` + + 卷积核形状：:math:`(D_f, H_f, W_f, C_{in}, C_{out})` + +- 输出： + + 输出形状：:math:`(N, D_{out}, H_{out}, W_{out}, C_{out})` + +参数 +:::::::::::: + + - **x** (Tensor) - 输入是形状为 :math:`[N, D, H, W, C]` 的 5-D SparseCooTensor，N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征高度，W 是特征宽度，数据类型为 float16, float32 或 float64。 + - **weight** (Tensor) - 形状为 :math:`[kD, kH, kW, C/g, M]` 的卷积核（卷积核）。 M 是输出通道数，g 是分组的个数，kH 是卷积核的高度，kW 是卷积核的宽度。 + - **bias** (Tensor，可选) - 偏置项，形状为：:math:`[M]` 。 + - **stride** (int|list|tuple，可选) - 步长大小。卷积核和输入进行卷积计算时滑动的步长。如果它是一个列表或元组，则必须包含三个整型数：（stride_depth, stride_height,stride_width）。若为一个整数，stride_depth = stride_height = stride_width = stride。默认值：1。 + - **padding** (int|list|tuple|str，可选) - 填充大小。如果它是一个字符串，可以是"VALID"或者"SAME"，表示填充算法，计算细节可参考上述 ``padding`` = "SAME"或 ``padding`` = "VALID" 时的计算公式。如果它是一个元组或列表，它可以有 3 种格式：(1)包含 5 个二元组：当 ``data_format`` 为"NCDHW"时为 [[0,0], [0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right]]，当 ``data_format`` 为"NDHWC"时为[[0,0], [padding_depth_front, padding_depth_back], [padding_height_top, padding_height_bottom], [padding_width_left, padding_width_right], [0,0]]；(2)包含 6 个整数值：[padding_depth_front, padding_depth_back, padding_height_top, padding_height_bottom, padding_width_left, padding_width_right]；(3)包含 3 个整数值：[padding_depth, padding_height, padding_width]，此时 padding_depth_front = padding_depth_back = padding_depth, padding_height_top = padding_height_bottom = padding_height, padding_width_left = padding_width_right = padding_width。若为一个整数，padding_depth = padding_height = padding_width = padding。默认值：0。 + - **dilation** (int|list|tuple，可选) - 空洞大小。空洞卷积时会使用该参数，卷积核对输入进行卷积时，感受野里每相邻两个特征点之间的空洞信息。如果空洞大小为列表或元组，则必须包含两个整型数：（dilation_height,dilation_width）。若为一个整数，dilation_height = dilation_width = dilation。默认值：1。 + - **groups** (int，可选) - 二维卷积层的组数。根据 Alex Krizhevsky 的深度卷积神经网络（CNN）论文中的成组卷积：当 group=n，输入和卷积核分别根据通道数量平均分为 n 组，第一组卷积核和第一组输入进行卷积计算，第二组卷积核和第二组输入进行卷积计算，……，第 n 组卷积核和第 n 组输入进行卷积计算。默认值：1。 + - **weight_attr** (ParamAttr，可选) - 指定权重参数属性的对象。默认值为 None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr`。 + - **bias_attr** (ParamAttr|bool，可选) - 指定偏置参数属性的对象。若 ``bias_attr`` 为 bool 类型，只支持为 False，表示没有偏置参数。默认值为 None，表示使用默认的偏置参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr`。 + - **data_format** (str，可选) - 指定输入的数据格式，输出的数据格式将与输入保持一致，可以是"NCDHW"和"NDHWC"。N 是批尺寸，C 是通道数，D 是特征层深度，H 是特征高度，W 是特征宽度。默认值："NCDHW"。 + - **key** (str，可选) - 用来保存和使用相同 rulebook 。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为 None 。 + +返回 +:::::::::::: +5-D Tensor，数据类型与 ``input`` 一致。返回卷积计算的结果。 + +返回类型 +:::::::::::: +Tensor。 + +代码示例 +:::::::::::: + +COPY-FROM: paddle.sparse.nn.functional.subm_conv3d diff --git a/docs/api/paddle/sparse/pow_cn.rst b/docs/api/paddle/sparse/pow_cn.rst new file mode 100644 index 00000000000..2c1cc91a97d --- /dev/null +++ b/docs/api/paddle/sparse/pow_cn.rst @@ -0,0 +1,31 @@ +.. _cn_api_paddle_sparse_pow: + +pow +------------------------------- + +.. py:function:: paddle.sparse.pow(x, factor, name=None) + + +逐元素计算 :attr:`x` 的幂函数，幂的系数为 `factor`，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + + +数学公式： + +.. math:: + out = x^{factor} + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **factor** (float|int) - 幂函数的系数，可以为 float 或 int。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.pow diff --git a/docs/api/paddle/sparse/rad2deg_cn.rst b/docs/api/paddle/sparse/rad2deg_cn.rst new file mode 100644 index 00000000000..64eee2721f1 --- /dev/null +++ b/docs/api/paddle/sparse/rad2deg_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_rad2deg: + +rad2deg +------------------------------- + +.. py:function:: paddle.sparse.rad2deg(x, name=None) + + +逐元素将输入 :attr:`x` 从弧度转换为度，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + rad2deg(x) = 180/ \pi * x + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.rad2deg diff --git a/docs/api/paddle/sparse/reshape_cn.rst b/docs/api/paddle/sparse/reshape_cn.rst new file mode 100644 index 00000000000..4b9c35dfbd1 --- /dev/null +++ b/docs/api/paddle/sparse/reshape_cn.rst @@ -0,0 +1,42 @@ +.. _cn_api_paddle_sparse_reshape: + +reshape +------------------------------- + +.. py:function:: paddle.sparse.reshape(x, shape, name=None) + + +在保持输入 ``x`` 数据不变的情况下，改变 ``x`` 的形状。 ``x`` 必须是一个 ``SparseCooTensor`` 或者 ``SparseCsrTensor`` 。 + +目前只能针对输入 ``x`` 的 ``sparse dims`` 部分改变形状，但是 ``shape`` 仍必须指定为变形后的 ``Tensor`` 的完整的形状。 + +注意如果 ``x`` 是一个 ``SparseCsrTensor`` ， 则 ``len(shape)`` 必须为 2 或者 3。 + +在指定目标 ``shape`` 时存在一些技巧： + + - 1. -1 表示这个维度的值是从 ``x`` 的元素总数和剩余维度推断出来的。因此，有且只有一个维度可以被设置为-1。 + - 2. 0 表示实际的维数是从 ``x`` 的对应维数中复制出来的，因此 ``shape`` 中 0 的索引值不能超过 ``x`` 的维度。 + +这里有一些例子来解释它们： + + - 1. 给定一个形状为[2,4,6]的三维 Tensor x ，目标形状为[6,8]，则将 x 变换为形状为[6,8]的 2-D Tensor，且 x 的数据保持不变。 + - 2. 给定一个形状为[2,4,6]的三维 Tensor x ，目标形状为[2,3,-1,2]，则将 x 变换为形状为[2,3,4,2]的 4-D Tensor，且 x 的数据保持不变。在这种情况下，目标形状的一个维度被设置为 -1 ，这个维度的值是从 x 的元素总数和剩余维度推断出来的。 + - 3. 给定一个形状为[2,4,6]的三维 Tensor x ，目标形状为[-1,0,3,2]，则将 x 变换为形状为[2,4,3,2]的 4-D Tensor，且 x 的数据保持不变。在这种情况下， 0 对应位置的维度值将从 x 的对应维数中复制，-1 对应位置的维度值由 x 的元素总数和剩余维度推断出来。 + +参数 +::::::::: + + - **x** (Tensor) - ``sparse tensor``，数据类型为 ``float32``、 ``float64``、 ``int32``、 ``int64`` 或者 ``bool``。 + - **shape** (list|tuple) - 数据类型是 ``int32``。定义目标形状。目标形状最多只能有一个维度为 -1 。 + - **name** (str ，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None 。 + +返回 +::::::::: + +``Tensor`` ： 改变形状后的 ``Tensor``，数据类型与 ``x`` 相同。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.reshape diff --git a/docs/api/paddle/sparse/sin_cn.rst b/docs/api/paddle/sparse/sin_cn.rst new file mode 100644 index 00000000000..6cf81831c7b --- /dev/null +++ b/docs/api/paddle/sparse/sin_cn.rst @@ -0,0 +1,28 @@ +.. _cn_api_paddle_sparse_sin: + +sin +------------------------------- + +.. py:function:: paddle.sparse.sin(x, name=None) + +逐元素计算 :attr:`x` 的正弦，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = sin(x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.sin diff --git a/docs/api/paddle/sparse/sinh_cn.rst b/docs/api/paddle/sparse/sinh_cn.rst new file mode 100644 index 00000000000..e02064db36c --- /dev/null +++ b/docs/api/paddle/sparse/sinh_cn.rst @@ -0,0 +1,28 @@ +.. _cn_api_paddle_sparse_sinh: + +sinh +------------------------------- + +.. py:function:: paddle.sparse.sinh(x, name=None) + +逐元素计算 :attr:`x` 的双曲正弦，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = sinh(x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.sinh diff --git a/docs/api/paddle/incubate/sparse/sparse_coo_tensor_cn.rst b/docs/api/paddle/sparse/sparse_coo_tensor_cn.rst similarity index 90% rename from docs/api/paddle/incubate/sparse/sparse_coo_tensor_cn.rst rename to docs/api/paddle/sparse/sparse_coo_tensor_cn.rst index dadc33bd8f0..dfca401f11e 100644 --- a/docs/api/paddle/incubate/sparse/sparse_coo_tensor_cn.rst +++ b/docs/api/paddle/sparse/sparse_coo_tensor_cn.rst @@ -1,10 +1,9 @@ -.. _cn_api_paddle_incubate_sparse_coo_tensor: +.. _cn_api_paddle_sparse_coo_tensor: sparse_coo_tensor ------------------------------- - -.. py:function:: paddle.incubate.sparse.sparse_coo_tensor(indices, values, shape=None, dtype=None, place=None, stop_gradient=True) +.. py:function:: paddle.sparse.sparse_coo_tensor(indices, values, shape=None, dtype=None, place=None, stop_gradient=True) 该 API 通过已知的非零元素的 ``indices`` 和 ``values`` 来创建一个 coordinate 格式的稀疏 tensor，tensor 类型为 ``paddle.Tensor`` 。 @@ -40,4 +39,4 @@ sparse_coo_tensor 代码示例 ::::::::: -COPY-FROM: paddle.incubate.sparse.sparse_coo_tensor +COPY-FROM: paddle.sparse.sparse_coo_tensor diff --git a/docs/api/paddle/incubate/sparse/sparse_csr_tensor_cn.rst b/docs/api/paddle/sparse/sparse_csr_tensor_cn.rst similarity index 91% rename from docs/api/paddle/incubate/sparse/sparse_csr_tensor_cn.rst rename to docs/api/paddle/sparse/sparse_csr_tensor_cn.rst index 0240ec06dcf..4a032e366fb 100644 --- a/docs/api/paddle/incubate/sparse/sparse_csr_tensor_cn.rst +++ b/docs/api/paddle/sparse/sparse_csr_tensor_cn.rst @@ -1,10 +1,9 @@ -.. _cn_api_paddle_incubate_sparse_csr_tensor: +.. _cn_api_paddle_sparse_csr_tensor: sparse_csr_tensor ------------------------------- - -.. py:function:: paddle.incubate.sparse.sparse_csr_tensor(crows, cols, values, shape, dtype=None, place=None, stop_gradient=True) +.. py:function:: paddle.sparse.sparse_csr_tensor(crows, cols, values, shape, dtype=None, place=None, stop_gradient=True) 该 API 通过已知的非零元素的 ``crows`` , ``cols`` 和 ``values`` 来创建一个 CSR(Compressed Sparse Row) 格式的稀疏 tensor，tensor 类型为 ``paddle.Tensor`` 。 @@ -43,4 +42,4 @@ sparse_csr_tensor **代码示例** -COPY-FROM: paddle.incubate.sparse.sparse_csr_tensor +COPY-FROM: paddle.sparse.sparse_csr_tensor diff --git a/docs/api/paddle/sparse/sqrt_cn.rst b/docs/api/paddle/sparse/sqrt_cn.rst new file mode 100644 index 00000000000..1cbf40a44be --- /dev/null +++ b/docs/api/paddle/sparse/sqrt_cn.rst @@ -0,0 +1,28 @@ +.. _cn_api_paddle_sparse_sqrt: + +sqrt +------------------------------- + +.. py:function:: paddle.sparse.sqrt(x, name=None) + +逐元素计算 :attr:`x` 的算术平方根，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = sqrt(x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.sqrt diff --git a/docs/api/paddle/sparse/square_cn.rst b/docs/api/paddle/sparse/square_cn.rst new file mode 100644 index 00000000000..4cc0c8b742c --- /dev/null +++ b/docs/api/paddle/sparse/square_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_square: + +square +------------------------------- + +.. py:function:: paddle.sparse.square(x, name=None) + + +逐元素计算 :attr:`x` 的平方，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = square(x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.square diff --git a/docs/api/paddle/incubate/sparse/subtract_cn.rst b/docs/api/paddle/sparse/subtract_cn.rst similarity index 77% rename from docs/api/paddle/incubate/sparse/subtract_cn.rst rename to docs/api/paddle/sparse/subtract_cn.rst index 21d433ff220..e1596043bb0 100644 --- a/docs/api/paddle/incubate/sparse/subtract_cn.rst +++ b/docs/api/paddle/sparse/subtract_cn.rst @@ -1,10 +1,9 @@ -.. _cn_api_paddle_incubate_sparse_subtract: +.. _cn_api_paddle_sparse_subtract: subtract ------------------------------- -.. py:function:: paddle.incubate.sparse.subtract(x, y, name=None) - +.. py:function:: paddle.sparse.subtract(x, y, name=None) 输入 :attr:`x` 与输入 :attr:`y` 逐元素相减，并将各个位置的输出元素保存到返回结果中。 @@ -14,10 +13,10 @@ subtract 等式为： .. math:: - Out = X - Y + out = x - y -- :math:`X`：多维稀疏 Tensor。 -- :math:`Y`：多维稀疏 Tensor。 +- :math:`x`：多维稀疏 Tensor。 +- :math:`y`：多维稀疏 Tensor。 参数 ::::::::: @@ -33,4 +32,4 @@ subtract 代码示例 ::::::::: -COPY-FROM: paddle.incubate.sparse.subtract +COPY-FROM: paddle.sparse.subtract diff --git a/docs/api/paddle/sparse/tan_cn.rst b/docs/api/paddle/sparse/tan_cn.rst new file mode 100644 index 00000000000..1aed63f201d --- /dev/null +++ b/docs/api/paddle/sparse/tan_cn.rst @@ -0,0 +1,28 @@ +.. _cn_api_paddle_sparse_tan: + +tan +------------------------------- + +.. py:function:: paddle.sparse.tan(x, name=None) + +逐元素计算 :attr:`x` 的正切，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = tan(x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.tan diff --git a/docs/api/paddle/sparse/tanh_cn.rst b/docs/api/paddle/sparse/tanh_cn.rst new file mode 100644 index 00000000000..5ad81c7df01 --- /dev/null +++ b/docs/api/paddle/sparse/tanh_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_tanh: + +tanh +------------------------------- + +.. py:function:: paddle.sparse.tanh(x, name=None) + + +逐元素计算 :attr:`x` 的双曲正切，要求 输入 :attr:`x` 为 `SparseCooTensor` 或 `SparseCsrTensor` 。 + +数学公式： + +.. math:: + out = tanh(x) + +参数 +::::::::: + - **x** (SparseTensor) - 输入的稀疏 Tensor，可以为 Coo 或 Csr 格式，数据类型为 float32、float64。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +多维稀疏 Tensor, 数据类型和稀疏格式与 :attr:`x` 相同 。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.tanh diff --git a/docs/api/paddle/sparse/transpose_cn.rst b/docs/api/paddle/sparse/transpose_cn.rst new file mode 100644 index 00000000000..b66bcab7d12 --- /dev/null +++ b/docs/api/paddle/sparse/transpose_cn.rst @@ -0,0 +1,29 @@ +.. _cn_api_paddle_sparse_transpose: + +transpose +------------------------------- + +.. py:function:: paddle.sparse.transpose(x, perm, name=None) + + +根据 :attr:`perm` 对输入的 :attr:`x` 维度进行重排，但不改变数据， +:attr:`x` 必须是多维 SparseTensor 或 COO 格式的 2 维或 3 维 SparseTensor。 + +.. math:: + out = transpose(x, perm) + +参数 +::::::::: + - **x** (Tensor) - 输入的 Tensor，数据类型为 float32、float64、int32 或 int64。 + - **perm** (list|tuple) - :attr:`perm` 长度必须和 :attr:`x` 的维度相同，并依照 :attr:`perm` 中数据进行重排。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。 + +返回 +::::::::: +转置后的稀疏 Tensor, 数据类型和压缩格式与 :attr:`x` 相同。 + + +代码示例 +::::::::: + +COPY-FROM: paddle.sparse.transpose