polish linalg doc and add triangular_solve doc (#4073)

Author: zhwesky2010

docs/api/paddle/Overview_cn.rst

@@ -61,7 +61,6 @@ tensor数学操作
     " :ref:`paddle.greater_equal <cn_api_tensor_cn_greater_equal>` ", "逐元素地返回 x>=y 的逻辑值"
     " :ref:`paddle.greater_than <cn_api_tensor_cn_greater_than>` ", "逐元素地返回 x>y 的逻辑值"
     " :ref:`paddle.increment <cn_api_tensor_increment>` ", "在控制流程中用来让 x 的数值增加 value"
-    " :ref:`paddle.inverse <cn_api_tensor_inverse>` ", "计算方阵的逆"
     " :ref:`paddle.kron <cn_api_paddle_tensor_kron>` ", "计算两个张量的克罗内克积"
     " :ref:`paddle.less_equal <cn_api_tensor_cn_less_equal>` ", "逐元素地返回 x<=y 的逻辑值"
     " :ref:`paddle.less_than <cn_api_tensor_cn_less_than>` ", "逐元素地返回 x<y 的逻辑值"
@@ -236,20 +235,16 @@ tensor线性代数相关
 
     " :ref:`paddle.bincount <cn_api_tensor_bincount>` ", "统计输入张量中元素的出现次数"
     " :ref:`paddle.bmm <cn_api_paddle_tensor_bmm>` ", "对输入x及输入y进行矩阵相乘"
-    " :ref:`paddle.cholesky <cn_api_tensor_cholesky>` ", "计算一个对称正定矩阵或一批对称正定矩阵的Cholesky分解"
     " :ref:`paddle.cross <cn_api_tensor_linalg_cross>` ", "计算张量 x 和 y 在 axis 维度上的向量积（叉积）"
     " :ref:`paddle.dist <cn_api_tensor_linalg_dist>` ", "计算 (x-y) 的 p 范数（p-norm）"
     " :ref:`paddle.dot <cn_api_paddle_tensor_linalg_dot>` ", "计算向量的内积"
     " :ref:`paddle.histogram <cn_api_tensor_histogram>` ", "计算输入张量的直方图"
     " :ref:`paddle.matmul <cn_api_tensor_matmul>` ", "计算两个Tensor的乘积，遵循完整的广播规则"
-    " :ref:`paddle.matrix_power <cn_api_tensor_matrix_power>` ", "计算一个（或一批）方阵的 n 次幂"
     " :ref:`paddle.mv <cn_api_tensor_mv>` ", "计算矩阵 x 和向量 vec 的乘积"
-    " :ref:`paddle.norm <cn_api_tensor_norm>` ", "计算给定Tensor的矩阵范数（Frobenius 范数）和向量范数（向量1范数、2范数、或者通常的p范数）"
     " :ref:`paddle.rank <cn_api_fluid_layers_rank>` ", "计算输入Tensor的维度（秩）"
     " :ref:`paddle.t <cn_api_paddle_tensor_t>` ", "对小于等于2维的Tensor进行数据转置"
     " :ref:`paddle.tril <cn_api_tensor_tril>` ", "返回输入矩阵 input 的下三角部分，其余部分被设为0"
     " :ref:`paddle.triu <cn_api_tensor_triu>` ", "返回输入矩阵 input 的上三角部分，其余部分被设为0"
-    " :ref:`paddle.multi_dot<cn_api_tensor_multi_dot>` ", "计算多个矩阵相乘"
 
 .. _tensor_manipulation:
 

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)
 :::::::::

docs/api/paddle/linalg/Overview_cn.rst

@@ -21,9 +21,9 @@ paddle.linalg 目录下包含飞桨框架支持的线性代数相关API。具体
     :widths: 10, 30
 
     " :ref:`paddle.linalg.det <cn_api_linalg_det>` ", "计算方阵的行列式"
-    " :ref:`paddle.linalg.slogdet <cn_api_tensor_norm>` ", "计算方阵行列式的符号、绝对值的自然对数"
+    " :ref:`paddle.linalg.slogdet <cn_api_linalg_slogdet>` ", "计算方阵行列式的符号、绝对值的自然对数"
     " :ref:`paddle.linalg.cond <cn_api_linalg_cond>` ", "根据矩阵的范数，来计算矩阵的条件数"
-    " :ref:`paddle.linalg.norm <cn_api_tensor_norm>` ", "计算矩阵范数或向量范数"
+    " :ref:`paddle.linalg.norm <cn_api_linalg_norm>` ", "计算矩阵范数或向量范数"
     " :ref:`paddle.linalg.matrix_rank <cn_api_linalg_matrix_rank>` ", "计算矩阵的秩"
 
 
@@ -36,9 +36,9 @@ paddle.linalg 目录下包含飞桨框架支持的线性代数相关API。具体
     :header: "API名称", "API功能"
     :widths: 10, 30
 
-    " :ref:`paddle.linalg.multi_dot <cn_api_tensor_multi_dot>` ", "2个或更多矩阵的乘法，会自动选择计算量最少的乘法顺序"
-    " :ref:`paddle.linalg.matrix_power <cn_api_tensor_matrix_power>` ", "计算方阵的n次幂"
-    " :ref:`paddle.linalg.inv <cn_api_tensor_inverse>` ", "计算方阵的逆矩阵"
+    " :ref:`paddle.linalg.multi_dot <cn_api_linalg_multi_dot>` ", "2个或更多矩阵的乘法，会自动选择计算量最少的乘法顺序"
+    " :ref:`paddle.linalg.matrix_power <cn_api_linalg_matrix_power>` ", "计算方阵的n次幂"
+    " :ref:`paddle.linalg.inv <cn_api_linalg_inv>` ", "计算方阵的逆矩阵"
     " :ref:`paddle.linalg.pinv <cn_api_linalg_pinv>` ", "计算矩阵的广义逆"
 
 
@@ -52,10 +52,10 @@ paddle.linalg 目录下包含飞桨框架支持的线性代数相关API。具体
     :widths: 10, 30
 
     " :ref:`paddle.linalg.eig <cn_api_linalg_eig>` ", "计算一般方阵的特征值与特征向量"
-    " :ref:`paddle.linalg.eigvals <cn_api_paddle_linalg_eigvals>` ", "计算一般方阵的特征值"
+    " :ref:`paddle.linalg.eigvals <cn_api_linalg_eigvals>` ", "计算一般方阵的特征值"
     " :ref:`paddle.linalg.eigh <cn_api_linalg_eigh>` ", "计算厄米特矩阵或者实数对称矩阵的特征值和特征向量"
     " :ref:`paddle.linalg.eigvalsh <cn_api_linalg_eigvalsh>` ", "计算厄米特矩阵或者实数对称矩阵的特征值"
-    " :ref:`paddle.linalg.cholesky <cn_api_tensor_cholesky>` ", "计算一个实数对称正定矩阵的Cholesky分解"
+    " :ref:`paddle.linalg.cholesky <cn_api_linalg_cholesky>` ", "计算一个实数对称正定矩阵的Cholesky分解"
     " :ref:`paddle.linalg.svd <cn_api_linalg_svd>` ", "计算矩阵的奇异值分解"
     " :ref:`paddle.linalg.qr <cn_api_linalg_qr>` ", "计算矩阵的正交三角分解（也称QR分解）"
 
@@ -70,3 +70,4 @@ paddle.linalg 目录下包含飞桨框架支持的线性代数相关API。具体
     :widths: 10, 30
 
     " :ref:`paddle.linalg.solve <cn_api_linalg_solve>` ", "计算具有唯一解的线性方程组"
+    " :ref:`paddle.linalg.triangular_solve <cn_api_linalg_solve>` ", "计算具有唯一解的线性方程组"

docs/api/paddle/cholesky_cn.rst renamed to 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.        ]

docs/api/paddle/linalg/eigvals_cn.rst

@@ -1,4 +1,4 @@
-.. _cn_api_paddle_linalg_eigvals:
+.. _cn_api_linalg_eigvals:
 
 eigvals
 -------------------------------

docs/api/paddle/inverse_cn.rst renamed to 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]]

docs/api/paddle/linalg/matrix_power_cn.rst

@@ -1,4 +1,4 @@
-.. _cn_api_tensor_matrix_power:
+.. _cn_api_linalg_matrix_power:
 
 matrix_power
 -------------------------------

docs/api/paddle/linalg/multi_dot_cn.rst

@@ -1,4 +1,4 @@
-.. _cn_api_tensor_multi_dot:
+.. _cn_api_linalg_multi_dot:
 
 multi_dot
 -------------------------------

docs/api/paddle/norm_cn.rst renamed to 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.]]
  

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]
+