From 04032fd894382208364e42ea715f2133bc329a9a Mon Sep 17 00:00:00 2001 From: zhouwei25 Date: Thu, 11 Nov 2021 08:08:19 +0000 Subject: [PATCH] polish linalg doc and add triangular_solve doc --- docs/api/paddle/Overview_cn.rst | 5 -- docs/api/paddle/Tensor_cn.rst | 23 ++++--- docs/api/paddle/linalg/Overview_cn.rst | 15 ++--- docs/api/paddle/{ => linalg}/cholesky_cn.rst | 6 +- docs/api/paddle/linalg/eigvals_cn.rst | 2 +- .../{inverse_cn.rst => linalg/inv_cn.rst} | 8 +-- docs/api/paddle/linalg/matrix_power_cn.rst | 2 +- docs/api/paddle/linalg/multi_dot_cn.rst | 2 +- docs/api/paddle/{ => linalg}/norm_cn.rst | 20 +++--- .../api/paddle/linalg/triangular_solve_cn.rst | 61 +++++++++++++++++++ 10 files changed, 105 insertions(+), 39 deletions(-) rename docs/api/paddle/{ => linalg}/cholesky_cn.rst (90%) rename docs/api/paddle/{inverse_cn.rst => linalg/inv_cn.rst} (87%) rename docs/api/paddle/{ => linalg}/norm_cn.rst (73%) create mode 100644 docs/api/paddle/linalg/triangular_solve_cn.rst diff --git a/docs/api/paddle/Overview_cn.rst b/docs/api/paddle/Overview_cn.rst index 1d94b2583bb..2c2f89d9df1 100755 --- a/docs/api/paddle/Overview_cn.rst +++ b/docs/api/paddle/Overview_cn.rst @@ -61,7 +61,6 @@ tensor数学操作 " :ref:`paddle.greater_equal ` ", "逐元素地返回 x>=y 的逻辑值" " :ref:`paddle.greater_than ` ", "逐元素地返回 x>y 的逻辑值" " :ref:`paddle.increment ` ", "在控制流程中用来让 x 的数值增加 value" - " :ref:`paddle.inverse ` ", "计算方阵的逆" " :ref:`paddle.kron ` ", "计算两个张量的克罗内克积" " :ref:`paddle.less_equal ` ", "逐元素地返回 x<=y 的逻辑值" " :ref:`paddle.less_than ` ", "逐元素地返回 x` ", "统计输入张量中元素的出现次数" " :ref:`paddle.bmm ` ", "对输入x及输入y进行矩阵相乘" - " :ref:`paddle.cholesky ` ", "计算一个对称正定矩阵或一批对称正定矩阵的Cholesky分解" " :ref:`paddle.cross ` ", "计算张量 x 和 y 在 axis 维度上的向量积（叉积）" " :ref:`paddle.dist ` ", "计算 (x-y) 的 p 范数（p-norm）" " :ref:`paddle.dot ` ", "计算向量的内积" " :ref:`paddle.histogram ` ", "计算输入张量的直方图" " :ref:`paddle.matmul ` ", "计算两个Tensor的乘积，遵循完整的广播规则" - " :ref:`paddle.matrix_power ` ", "计算一个（或一批）方阵的 n 次幂" " :ref:`paddle.mv ` ", "计算矩阵 x 和向量 vec 的乘积" - " :ref:`paddle.norm ` ", "计算给定Tensor的矩阵范数（Frobenius 范数）和向量范数（向量1范数、2范数、或者通常的p范数）" " :ref:`paddle.rank ` ", "计算输入Tensor的维度（秩）" " :ref:`paddle.t ` ", "对小于等于2维的Tensor进行数据转置" " :ref:`paddle.tril ` ", "返回输入矩阵 input 的下三角部分，其余部分被设为0" " :ref:`paddle.triu ` ", "返回输入矩阵 input 的上三角部分，其余部分被设为0" - " :ref:`paddle.multi_dot` ", "计算多个矩阵相乘" .. _tensor_manipulation: diff --git a/docs/api/paddle/Tensor_cn.rst b/docs/api/paddle/Tensor_cn.rst index 032a0fade8a..53ae7d96efe 100755 --- a/docs/api/paddle/Tensor_cn.rst +++ b/docs/api/paddle/Tensor_cn.rst @@ -480,7 +480,7 @@ cholesky(upper=False, name=None) 返回类型：Tensor -请参考 :ref:`cn_api_tensor_cholesky` +请参考 :ref:`cn_api_linalg_cholesky` chunk(chunks, axis=0, name=None) ::::::::: @@ -814,7 +814,7 @@ eigvals(y, name=None) 返回类型：Tensor -请参考 :ref:`cn_api_paddle_linalg_eigvals` +请参考 :ref:`cn_api_linalg_eigvals` fill_(x, value, name=None) ::::::::: @@ -1076,14 +1076,14 @@ index_select(index, axis=0, name=None) 请参考 :ref:`cn_api_tensor_search_index_select` -inverse(name=None) +inv(name=None) ::::::::: 返回：计算后的Tensor 返回类型：Tensor -请参考 :ref:`cn_api_tensor_inverse` +请参考 :ref:`cn_api_linalg_inv` is_empty(cond=None) ::::::::: @@ -1263,7 +1263,7 @@ matrix_power(x, n, name=None) 返回类型：Tensor -请参考 :ref:`cn_api_tensor_matrix_power` +请参考 :ref:`cn_api_linalg_matrix_power` max(axis=None, keepdim=False, name=None) ::::::::: @@ -1402,7 +1402,7 @@ norm(p=fro, axis=None, keepdim=False, name=None) 返回类型：Tensor -请参考 :ref:`cn_api_tensor_norm` +请参考 :ref:`cn_api_linalg_norm` not_equal(y, name=None) ::::::::: @@ -1950,6 +1950,15 @@ transpose(perm, name=None) 请参考 :ref:`cn_api_fluid_layers_transpose` +triangular_solve(b, upper=True, transpose=False, unitriangular=False, name=None) +::::::::: + +返回：计算后的Tensor + +返回类型：Tensor + +请参考 :ref:`cn_api_linalg_triangular_solve` + trunc(name=None) ::::::::: @@ -2064,7 +2073,7 @@ multi_dot(x, name=None) 返回类型：Tensor -请参考 :ref:`cn_api_tensor_multi_dot` +请参考 :ref:`cn_api_linalg_multi_dot` solve(x, y name=None) ::::::::: diff --git a/docs/api/paddle/linalg/Overview_cn.rst b/docs/api/paddle/linalg/Overview_cn.rst index 689b32da750..9e66691e3c9 100644 --- a/docs/api/paddle/linalg/Overview_cn.rst +++ b/docs/api/paddle/linalg/Overview_cn.rst @@ -21,9 +21,9 @@ paddle.linalg 目录下包含飞桨框架支持的线性代数相关API。具体 :widths: 10, 30 " :ref:`paddle.linalg.det ` ", "计算方阵的行列式" - " :ref:`paddle.linalg.slogdet ` ", "计算方阵行列式的符号、绝对值的自然对数" + " :ref:`paddle.linalg.slogdet ` ", "计算方阵行列式的符号、绝对值的自然对数" " :ref:`paddle.linalg.cond ` ", "根据矩阵的范数，来计算矩阵的条件数" - " :ref:`paddle.linalg.norm ` ", "计算矩阵范数或向量范数" + " :ref:`paddle.linalg.norm ` ", "计算矩阵范数或向量范数" " :ref:`paddle.linalg.matrix_rank ` ", "计算矩阵的秩" @@ -36,9 +36,9 @@ paddle.linalg 目录下包含飞桨框架支持的线性代数相关API。具体 :header: "API名称", "API功能" :widths: 10, 30 - " :ref:`paddle.linalg.multi_dot ` ", "2个或更多矩阵的乘法，会自动选择计算量最少的乘法顺序" - " :ref:`paddle.linalg.matrix_power ` ", "计算方阵的n次幂" - " :ref:`paddle.linalg.inv ` ", "计算方阵的逆矩阵" + " :ref:`paddle.linalg.multi_dot ` ", "2个或更多矩阵的乘法，会自动选择计算量最少的乘法顺序" + " :ref:`paddle.linalg.matrix_power ` ", "计算方阵的n次幂" + " :ref:`paddle.linalg.inv ` ", "计算方阵的逆矩阵" " :ref:`paddle.linalg.pinv ` ", "计算矩阵的广义逆" @@ -52,10 +52,10 @@ paddle.linalg 目录下包含飞桨框架支持的线性代数相关API。具体 :widths: 10, 30 " :ref:`paddle.linalg.eig ` ", "计算一般方阵的特征值与特征向量" - " :ref:`paddle.linalg.eigvals ` ", "计算一般方阵的特征值" + " :ref:`paddle.linalg.eigvals ` ", "计算一般方阵的特征值" " :ref:`paddle.linalg.eigh ` ", "计算厄米特矩阵或者实数对称矩阵的特征值和特征向量" " :ref:`paddle.linalg.eigvalsh ` ", "计算厄米特矩阵或者实数对称矩阵的特征值" - " :ref:`paddle.linalg.cholesky ` ", "计算一个实数对称正定矩阵的Cholesky分解" + " :ref:`paddle.linalg.cholesky ` ", "计算一个实数对称正定矩阵的Cholesky分解" " :ref:`paddle.linalg.svd ` ", "计算矩阵的奇异值分解" " :ref:`paddle.linalg.qr ` ", "计算矩阵的正交三角分解（也称QR分解）" @@ -70,3 +70,4 @@ paddle.linalg 目录下包含飞桨框架支持的线性代数相关API。具体 :widths: 10, 30 " :ref:`paddle.linalg.solve ` ", "计算具有唯一解的线性方程组" + " :ref:`paddle.linalg.triangular_solve ` ", "计算具有唯一解的线性方程组" diff --git a/docs/api/paddle/cholesky_cn.rst b/docs/api/paddle/linalg/cholesky_cn.rst similarity index 90% rename from docs/api/paddle/cholesky_cn.rst rename to docs/api/paddle/linalg/cholesky_cn.rst index 4393a33d2f5..0aa081fd454 100644 --- a/docs/api/paddle/cholesky_cn.rst +++ b/docs/api/paddle/linalg/cholesky_cn.rst @@ -1,9 +1,9 @@ -.. _cn_api_tensor_cholesky: +.. _cn_api_linalg_cholesky: cholesky ------------------------------- -.. py:function:: paddle.cholesky(x, upper=False, name=None) +.. py:function:: paddle.linalg.cholesky(x, upper=False, name=None) @@ -32,7 +32,7 @@ cholesky a_t = np.transpose(a, [1, 0]) x_data = np.matmul(a, a_t) + 1e-03 x = paddle.to_tensor(x_data) - out = paddle.cholesky(x, upper=False) + out = paddle.linalg.cholesky(x, upper=False) print(out) # [[1.190523 0. 0. ] # [0.9906703 0.27676893 0. ] diff --git a/docs/api/paddle/linalg/eigvals_cn.rst b/docs/api/paddle/linalg/eigvals_cn.rst index 30b239f9d86..2ae5627b49a 100644 --- a/docs/api/paddle/linalg/eigvals_cn.rst +++ b/docs/api/paddle/linalg/eigvals_cn.rst @@ -1,4 +1,4 @@ -.. _cn_api_paddle_linalg_eigvals: +.. _cn_api_linalg_eigvals: eigvals ------------------------------- diff --git a/docs/api/paddle/inverse_cn.rst b/docs/api/paddle/linalg/inv_cn.rst similarity index 87% rename from docs/api/paddle/inverse_cn.rst rename to docs/api/paddle/linalg/inv_cn.rst index 7b75e82e958..4c79875f8df 100644 --- a/docs/api/paddle/inverse_cn.rst +++ b/docs/api/paddle/linalg/inv_cn.rst @@ -1,9 +1,9 @@ -.. _cn_api_tensor_inverse: +.. _cn_api_linalg_inv: -inverse +inv ------------------------------- -.. py:function:: paddle.inverse(x, name=None) +.. py:function:: paddle.linalg.inv(x, name=None) 计算方阵的逆。方阵是行数和列数相等的矩阵。输入可以是一个方阵（2-D张量），或者是批次方阵（维数大于2时）。 @@ -26,5 +26,5 @@ Tensor, 输入方阵的逆。 import paddle mat = paddle.to_tensor([[2, 0], [0, 2]], dtype='float32') - inv = paddle.inverse(mat) + inv = paddle.linalg.inv(mat) print(inv) # [[0.5, 0], [0, 0.5]] diff --git a/docs/api/paddle/linalg/matrix_power_cn.rst b/docs/api/paddle/linalg/matrix_power_cn.rst index c1f771a92f0..17d306d83c5 100644 --- a/docs/api/paddle/linalg/matrix_power_cn.rst +++ b/docs/api/paddle/linalg/matrix_power_cn.rst @@ -1,4 +1,4 @@ -.. _cn_api_tensor_matrix_power: +.. _cn_api_linalg_matrix_power: matrix_power ------------------------------- diff --git a/docs/api/paddle/linalg/multi_dot_cn.rst b/docs/api/paddle/linalg/multi_dot_cn.rst index e6200eecbdd..294d630c84f 100755 --- a/docs/api/paddle/linalg/multi_dot_cn.rst +++ b/docs/api/paddle/linalg/multi_dot_cn.rst @@ -1,4 +1,4 @@ -.. _cn_api_tensor_multi_dot: +.. _cn_api_linalg_multi_dot: multi_dot ------------------------------- diff --git a/docs/api/paddle/norm_cn.rst b/docs/api/paddle/linalg/norm_cn.rst similarity index 73% rename from docs/api/paddle/norm_cn.rst rename to docs/api/paddle/linalg/norm_cn.rst index f932883654c..941375509f8 100644 --- a/docs/api/paddle/norm_cn.rst +++ b/docs/api/paddle/linalg/norm_cn.rst @@ -1,9 +1,9 @@ -.. _cn_api_tensor_norm: +.. _cn_api_linalg_norm: norm ------------------------------- -.. py:function:: paddle.norm(x, p='fro', axis=None, keepdim=False, name=None): +.. py:function:: paddle.linalg.norm(x, p='fro', axis=None, keepdim=False, name=None): @@ -12,7 +12,7 @@ norm .. note:: - 此API与`numpy.linalg.norm`存在差异。此API支持高阶张量（rank>=3）作为输入，输入`axis`对应的轴就可以计算出norm的值。但是`numpy.linalg.norm`仅支持一维向量和二维矩阵作为输入。特别需要注意的是，此API的P阶矩阵范数，实际上将矩阵摊平成向量计算。实际计算的是向量范数，而不是真正的矩阵范数。 + 此API与 ``numpy.linalg.norm`` 存在差异。此API支持高阶张量（rank>=3）作为输入，输入 ``axis`` 对应的轴就可以计算出norm的值。但是 ``numpy.linalg.norm`` 仅支持一维向量和二维矩阵作为输入。特别需要注意的是，此API的P阶矩阵范数，实际上将矩阵摊平成向量计算。实际计算的是向量范数，而不是真正的矩阵范数。 参数 ::::::::: @@ -43,27 +43,27 @@ norm # [[ 0. 1. 2. 3.] [ 4. 5. 6. 7.] [ 8. 9. 10. 11.]]] # compute frobenius norm along last two dimensions. - out_fro = paddle.norm(x, p='fro', axis=[0,1]) + out_fro = paddle.linalg.norm(x, p='fro', axis=[0,1]) # out_fro.numpy() [17.435596 16.911535 16.7332 16.911535] # compute 2-order vector norm along last dimension. - out_pnorm = paddle.norm(x, p=2, axis=-1) + out_pnorm = paddle.linalg.norm(x, p=2, axis=-1) #out_pnorm.numpy(): [[21.118711 13.190906 5.477226] # [ 3.7416575 11.224972 19.131126]] # compute 2-order norm along [0,1] dimension. - out_pnorm = paddle.norm(x, p=2, axis=[0,1]) + out_pnorm = paddle.linalg.norm(x, p=2, axis=[0,1]) #out_pnorm.numpy(): [17.435596 16.911535 16.7332 16.911535] # compute inf-order norm - out_pnorm = paddle.norm(x, p=np.inf) + out_pnorm = paddle.linalg.norm(x, p=np.inf) #out_pnorm.numpy() = [12.] - out_pnorm = paddle.norm(x, p=np.inf, axis=0) + out_pnorm = paddle.linalg.norm(x, p=np.inf, axis=0) #out_pnorm.numpy(): [[12. 11. 10. 9.] [8. 7. 6. 7.] [8. 9. 10. 11.]] # compute -inf-order norm - out_pnorm = paddle.norm(x, p=-np.inf) + out_pnorm = paddle.linalg.norm(x, p=-np.inf) #out_pnorm.numpy(): [0.] - out_pnorm = paddle.norm(x, p=-np.inf, axis=0) + out_pnorm = paddle.linalg.norm(x, p=-np.inf, axis=0) #out_pnorm.numpy(): [[0. 1. 2. 3.] [4. 5. 6. 5.] [4. 3. 2. 1.]] diff --git a/docs/api/paddle/linalg/triangular_solve_cn.rst b/docs/api/paddle/linalg/triangular_solve_cn.rst new file mode 100644 index 00000000000..4330a30eeb3 --- /dev/null +++ b/docs/api/paddle/linalg/triangular_solve_cn.rst @@ -0,0 +1,61 @@ +.. _cn_api_linalg_triangular_solve: + +triangular_solve +------------------------------- + +.. py:function:: paddle.linalg.triangular_solve(x, y, upper=True, transpose=False, unitriangular=False, name=None) + + +计算具有唯一解的线性方程组解，其中系数矩阵 `x` 是上(下)三角系数矩阵， `y` 是方程右边。 + +记 :math:`X` 为一个或一批方阵，:math:`Y` 一个或一批矩阵。 + +则方程组为： + +.. math:: + X * Out = Y + +方程组的解为： + +.. math:: + Out = X ^ {-1} * Y + +特别地， + +- 如果 ``x`` 不可逆 ， 则线性方程组不可解。 + +参数 +::::::::: + - **x** (Tensor) : 线性方程组左边的系数方阵，其为一个或一批方阵。``x`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度，数据类型为float32， float64。 + - **y** (Tensor) : 线性方程组右边的矩阵，其为一个或一批矩阵。``y`` 的形状应为 ``[*, M, K]``， 其中 ``*`` 为零或更大的批次维度，数据类型为float32， float64。 + - **upper** (bool, 可选) - 对系数矩阵 ``x`` 取上三角还是下三角。默认为True，表示取上三角。 + - **transpose** (bool, 可选) - 是否对系数矩阵 ``x`` 进行转置。默认为False，不进行转置。 + - **unitriangular** (bool, 可选) - 如果为True，则将系数矩阵 ``x`` 对角线元素假设为1来求解方程。默认为False。 + - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + +返回： +::::::::: + - Tensor， 线程方程组的解， 数据类型和 ``x`` 一致。 + +代码示例 +:::::::::: + +.. code-block:: python + + # a square system of linear equations: + # x1 + x2 + x3 = 0 + # 2*x2 + x3 = -9 + # -x3 = 5 + + import paddle + import numpy as np + + x = paddle.to_tensor([[1, 1, 1], + [0, 2, 1], + [0, 0,-1]], dtype="float64") + y = paddle.to_tensor([[0], [-9], [5]], dtype="float64") + out = paddle.linalg.triangular_solve(x, y, upper=True) + + print(out) + # [7, -2, -5] +