【Hackathon 8th No.1】add lu_solve api for paddle (#7052)

* 【Hackathon 8th No.1】add `lu_solve` api for paddle

* pre-commit

* add example

* fix review

Author: decade-afk

docs/api/paddle/Tensor/Overview_en.rst

@@ -195,6 +195,7 @@ Methods
     outer
     cov
     lu
+    lu_solve
     lu_unpack
     cholesky_solve
     mod

docs/api/paddle/linalg/Overview_cn.rst

@@ -80,6 +80,7 @@ paddle.linalg 目录下包含飞桨框架支持的线性代数相关 API。具
     :widths: 10, 30
 
     " :ref:`paddle.linalg.lstsq <cn_api_paddle_linalg_lstsq>` ", "求解线性方程组的最小二乘问题"
+    " :ref:`paddle.linalg.lu_solve <cn_api_paddle_linalg_lu_solve>` ", "计算具有唯一解的线性方程组，方程左边为 LU 分解矩阵，右边为矩阵"
     " :ref:`paddle.linalg.solve <cn_api_paddle_linalg_solve>` ", "计算具有唯一解的线性方程组，方程左边为方阵，右边为矩阵"
     " :ref:`paddle.linalg.triangular_solve <cn_api_paddle_linalg_triangular_solve>` ", "计算具有唯一解的线性方程组，方程左边为上(下)三角方阵，右边为矩阵"
     " :ref:`paddle.linalg.cholesky_solve <cn_api_paddle_linalg_cholesky_solve>` ", "通过 Cholesky 分解矩阵，计算具有唯一解的线性方程组"

docs/api/paddle/linalg/lu_solve_cn.rst

@@ -0,0 +1,46 @@
+.. _cn_api_paddle_linalg_lu_solve:
+
+lu_solve
+-------------------------------
+
+.. py:function:: paddle.linalg.lu_solve(b, lu, pivots, trans="N", name=None)
+
+给定 `A` 的 LU 分解结果 和列向量 `b` ，求解线性方程组的解 `x`。
+
+记 :math:`A` 为一个或一批方阵，:math:`b` 一个或一批矩阵，当 `trans` 为 `N` 时，公式为：
+
+.. math::
+    b = A * X
+
+当 `trans` 为 `T` 时，公式为：
+
+.. math::
+    b = A ^ {T} * X
+
+当 `trans` 为 `C` 时，公式为：
+
+.. math::
+    b = A ^ {H} * X
+
+.. note::
+
+    `lu` 和 `pivots` 由 ``paddle.linalg.lu`` 得到。
+
+参数
+::::::::::::
+
+    - **b** (Tensor) - 输入的欲进行线性方程组求解的右值，类型为 Tensor。 ``b`` 的形状应为 ``[*, M, K]``，其中 ``*`` 为零或更大的批次维度，数据类型为 float32， float64。
+    - **lu** (Tensor) - LU 分解结果矩阵，由 L、U 拼接组成，类型为 Tensor。 ``lu`` 的形状应为 ``[*, M, M]``，其中 ``*`` 为零或更大的批次维度。数据类型和 ``b`` 相同。
+    - **pivots** (Tensor) - LU 分解结果的主元信息，类型为 Tensor。 ``pivots`` 的形状应为 ``[*, M]``，其中 ``*`` 为零或更大的批次维度。数据类型为 int32。
+    - **trans** (str，可选) - 是否对 A 进行转置，该参数的合法值为 'N'，'T'，'C'，默认值为 N。
+    - **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
+
+返回
+::::::::::::
+
+    - Tensor，这个（或这批）矩阵 ``lu`` 、 ``pivots`` 和 ``b`` 经过运算后的结果，数据类型及维度和输入 ``b`` 的一致。
+
+代码示例
+::::::::::
+
+COPY-FROM: paddle.linalg.lu_solve

docs/guides/model_convert/convert_from_pytorch/api_difference/linalg/torch.linalg.lu_solve.md

@@ -0,0 +1,83 @@
+## [ 输入参数类型不一致 ]torch.linalg.lu_solve
+
+### [torch.linalg.lu_solve](https://pytorch.org/docs/stable/generated/torch.linalg.lu_solve.html#torch.linalg.lu_solve)
+
+```python
+torch.linalg.lu_solve(LU, pivots, B, *, left=True, adjoint=False, out=None)
+```
+
+### [paddle.linalg.lu_solve](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/api/paddle/linalg/lu_solve_cn.html)
+
+```python
+paddle.linalg.lu_solve(b, lu, pivots, trans="N", name=None)
+```
+
+PyTorch 相比 Paddle 支持更多其他参数，具体如下：
+
+### 参数映射
+
+| PyTorch | PaddlePaddle | 备注                                                  |
+| ------- | ------------ | ----------------------------------------------------- |
+| LU      | lu           | 表示 LU 分解结果矩阵，由 L、U 拼接组成，仅参数名不一致。  |
+| pivots  | pivots       | 表示 LU 分解结果的主元信息 Tensor 。                    |
+| B       | b            | 表示欲进行线性方程组求解的右值 Tensor ，仅参数名不一致。  |
+| left    | -            | 表示系数矩阵 A 是否在左侧， Paddle 无此参数，需要转写。|
+| adjoint | trans        | 表示是否使用转置 LU 分解结果， PyTorch 为 bool 类型，Paddle 为 str 类型，需要转写。|
+| out     | -            | 表示输出的 Tensor 元组 ， Paddle 无此参数，需要转写。    |
+
+### 转写示例
+
+#### out：指定输出
+
+```python
+# PyTorch 写法
+torch.linalg.lu_solve(LU, pivots, B, out=A)
+
+# Paddle 写法
+y = paddle.linalg.lu_solve(B, LU, pivots)
+paddle.assign(y, A)
+```
+
+#### left=True, adjoint=True
+```python
+# PyTorch 写法
+LU, pivots = torch.linalg.lu(A)
+torch.linalg.lu_solve(LU, pivots, B, left=True, adjoint=True)
+
+# Paddle 写法
+LU, pivots = paddle.linalg.lu(A)
+paddle.linalg.lu_solve(B, LU, pivots, trans="C")
+```
+
+#### left=True, adjoint=False
+```python
+# PyTorch 写法
+LU, pivots = torch.linalg.lu(A)
+torch.linalg.lu_solve(LU, pivots, B, left=True, adjoint=False)
+
+# Paddle 写法
+LU, pivots = paddle.linalg.lu(A)
+paddle.linalg.lu_solve(B, LU, pivots, trans="N")
+```
+
+#### left=False, adjoint=True
+```python
+# PyTorch 写法
+LU, pivots = torch.linalg.lu(A)
+torch.linalg.lu_solve(LU, pivots, B, left=False, adjoint=True)
+
+# Paddle 写法
+LU, pivots = paddle.linalg.lu(A.T)
+paddle.linalg.lu_solve(B.T, LU, pivots, trans="C").T
+```
+
+#### left=False, adjoint=False
+```python
+# PyTorch 写法
+LU, pivots = torch.linalg.lu(A)
+torch.linalg.lu_solve(LU, pivots, B, left=False, adjoint=False)
+
+# Paddle 写法
+LU, pivots = paddle.linalg.lu(A.T)
+paddle.linalg.lu_solve(B.T, LU, pivots, trans="N").T
+```