!48022 pinv文档补充详细说明

Merge pull request !48022 from wujueying/master

docs/api/api_python/ops/mindspore.ops.func_pinv.rst

@@ -5,22 +5,35 @@ mindspore.ops.pinv
 
     计算矩阵的（Moore-Penrose）伪逆。
 
+    本函数通过SVD计算。如果 math:`x=U*S*V^{T}` ，则x的伪逆为 :math:`x^{T}=V*S^{+}*U^{T}` ，:math:`S^{+}` 为对S的对角线上的每个非零元素取倒数，零保留在原位。
+
+    支持批量矩阵，若x是批量矩阵，当atol或rtol为float时，则输出具有相同的批量维度。
+    若atol或rtol为Tensor，则其shape必须可广播到 `x.svd() <https://www.mindspore.cn/docs/zh-CN/master/api_python/ops/mindspore.ops.svd.html>`_ 返回的奇异值的shape。
+    若x.shape为 :math:`(B, M, N)` ，atol或rtol的shape为 :math:`(K, B)` ，则输出shape为 :math:`(K, B, N, M)` 。
+
+    当hermitian为True时，暂时仅支持实数域，默认输入x为实对称矩阵，因此不会在内部检查x，并且在计算中仅使用下三角部分。
+    当x的奇异值（或特征值范数，hermitian=True）小于阈值（ :math:`max(atol, \sigma \cdot rtol)` ， :math:`\sigma` 为最大奇异值或特征值）时，将其置为零，且在计算中不使用。
+
+    若rtol和atol均未指定并且x的shape(M, N)，则rtol设置为 :math:`rtol=max(M, N)\varepsilon` ， :math:`\varepsilon` 为x.dtype的 `eps值 <https://www.mindspore.cn/docs/zh-CN/master/api_python/ops/mindspore.ops.Eps.html>`_ 。
+    若rtol未指定且atol指定值大于零，则rtol设置为零。
+
+    .. note::
+        该函数在内部使用 `svd <https://www.mindspore.cn/docs/zh-CN/master/api_python/ops/mindspore.ops.svd.html>`_
+        （或 `eigh <https://www.mindspore.cn/docs/zh-CN/master/api_python/scipy/mindspore.scipy.linalg.eigh.html>`_ ,hermitian=True），
+        因此与这些函数具有相同问题，详细信息请参阅svd()和eigh()中的警告。
+
     参数：
-        - **x** (Tensor) - 要计算的矩阵。矩阵必须至少有两个维度。支持数据类型为float32或float64。
-          
-          - hermitian为false时，支持2维和更高维度，shape为 :math:`(*, M, N)`。
-          - hermitian为true时，仅支持2维，shape为 :math:`(M, N)`。
+        - **x** (Tensor) - 要计算的矩阵。支持数据类型为float32或float64。shape为 :math:`(*, M, N)` ，其中*为零或多个批量维度。
+
+          - hermitian为True时，暂不支持多个批量维度。
 
     关键字参数：
         - **atol** (float, Tensor) - 绝对公差值。默认值：None。
         - **rtol** (float, Tensor) - 相对公差值。默认值：None。
-        - **hermitian** (bool) - 为True时假设x为实对称矩阵。默认值：False。
+        - **hermitian** (bool) - 为True时求解x为实对称的矩阵。默认值：False。
 
     输出：
-        - **output** (Tensor): 类型与输入相同。
-          
-          - hermitian为false时，输出shape为 :math:`(*, N, M)`。
-          - hermitian为true时，输出shape为 :math:`(N, M)`。
+        - **output** (Tensor): 类型与输入相同。shape为 :math:`(*, N, M)` ，其中*为零或多个批量维度。
 
     异常：
         - **TypeError** - `hermitian` 不是bool。

mindspore/python/mindspore/ops/function/linalg_func.py

@@ -92,15 +92,39 @@ def svd(a, full_matrices=False, compute_uv=True):
 
 
 def pinv(x, *, atol=None, rtol=None, hermitian=False):
-    """
+    r"""
     Computes the (Moore-Penrose) pseudo-inverse of a matrix.
+    This function is computed using SVD. If :math:`x=U*S*V^{T}` ,Than the pseudo-inverse of x is:
+    :math:`x^{T}=V*S^{+}*U^{T}` , :math:`S^{+}` is the reciprocal of each non-zero element on
+    the diagonal of S, and zero remains in place.
+    Batch matrices are supported. If x is a batch matrix, the output has the same batch dimension when
+    atol or rtol is float.
+    If atol or rtol is a Tensor, its shape must be broadcast to the singular value returned by
+    `x.svd <https://www.mindspore.cn/docs/en/master/api_python/ops/mindspore.ops.svd.html>`_ .
+    If x.shape is :math:`(B, M, N)`, and the shape of atol or rtol is :math: `(K, B)`, the output
+    shape is :math:`(K, B, N, M)`.
+    When the Hermitian is True, temporary support only real domain, x is treated as a real symmetric, so x is
+    not checked internally, and only use the lower triangular part in the computations.
+    When the singular value of x (or the norm of the eigenvalues when hermitian = True) that are below
+    threshold (:math:`Max(atol, \sigma \cdot rtol)`, :math:`\sigma` as the largest singular value or
+    characteristic value), it is set to zero, and is not used in the computations.
+    If rtol is not specified and x is a matrix of dimensions (M, N), then rtol is set to
+    be :math:`rtol=max(M, N)\varepsilon`, :math:`\varepsilon` is the
+    `eps <https://www.mindspore.cn/docs/en/master/api_python/ops/mindspore.ops.Eps.html>`_ value of x.dtype.
+    If rtol is not specified and atol specifies a value larger than zero, rtol is set to zero.
+
+    .. note::
+        This function uses
+        `svd <https://www.mindspore.cn/docs/en/master/api_python/ops/mindspore.ops.svd.html>`_ internally,
+        (or `eigh <https://www.mindspore.cn/docs/en/master/api_python/scipy/mindspore.scipy.linalg.eigh.html>`_ ,
+        when hermitian = True). So it has the same problem as these functions. For details,
+        see the warnings in svd() and eigh().
 
     Args:
-        x (Tensor): A matrix to be calculated. The matrix must be at least two dimensions.
-            Only `float32`, `float64` are supported Tensor dtypes.
+        x (Tensor): A matrix to be calculated. Only `float32`, `float64` are supported Tensor dtypes.
+            shape is :math:`(*, M, N)`, * is zero or more batch dimensions.
 
-            - When hermitian is false, 2 and higher dimensions are supported, and the shape is :math:`(*, M, N)`.
-            - When hermitian is true, only 2 dimensions are supported, and the shape is :math:`(M, N)`.
+            - When hermitian is true, batch dimensions are not supported temporarily.
 
     Keyword args:
         atol (float, Tensor): absolute tolerance value. Default: None.
@@ -108,10 +132,7 @@ def pinv(x, *, atol=None, rtol=None, hermitian=False):
         hermitian (bool): An optional bool. x is assumed to be symmetric if real. Default: False.
 
     Outputs:
-        - **output** (Tensor) - same type as input.
-
-          - When hermitian is false, the output shape is :math:`(*, N, M)`.
-          - When hermitian is true, the output shape is :math:`(N, M)`.
+        - **output** (Tensor) - same type as input. Shape is :math:`(*, N, M)`, * is zero or more batch dimensions.
 
     Raises:
         TypeError: If `hermitian` is not a bool.