Merge pull request #400 from jieli-matrix:docstring-svd

GitOrigin-RevId: 3bcbea3440

.github/workflows/ci.yml

@@ -29,7 +29,6 @@ jobs:
         uses: actions/checkout@v2
       - name: Checkout submodules
         run: |
-          apt update&&apt install ninja-build
           ./third_party/prepare.sh
           ./third_party/install-mkl.sh
       - name: Build MegEngine
@@ -58,7 +57,6 @@ jobs:
         uses: actions/checkout@v2
       - name: Checkout submodules
         run: |
-          apt update&&apt install ninja-build
           ./third_party/prepare.sh
           ./third_party/install-mkl.sh
       - name: Build MegEngine

README.md

@@ -12,7 +12,7 @@ MegEngine is a fast, scalable and easy-to-use deep learning framework, with auto
 
 ## Installation
 
-**NOTE:** MegEngine now supports Python installation on Linux-64bit/Windows-64bit/MacOS(CPU-Only)-10.14+/Android 7+(CPU-Only) platforms with Python from 3.5 to 3.8. On Windows 10 you can either install the Linux distribution through [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl) or install the Windows distribution directly. Many other platforms are supported for inference.
+**NOTE:** MegEngine now supports Python installation on Linux-64bit/Windows-64bit/MacOS(CPU-Only)-10.14+ platforms with Python from 3.5 to 3.8. On Windows 10 you can either install the Linux distribution through [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl) or install the Windows distribution directly. Many other platforms are supported for inference.
 
 ### Binaries
 

README_CN.md

@@ -13,7 +13,7 @@ MegEngine 是一个快速、可拓展、易于使用且支持自动求导的深
 
 ## 安装说明
 
-**注意:** MegEngine 现在支持在 Linux-64bit/Windows-64bit/macos-10.14/Android 7+ 及其以上 (MacOS/Android只支持cpu) 等平台上安装 Python 包，支持Python3.5 到 Python3.8。对于 Windows 10 用户，可以通过安装 [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl) 进行体验，同时我们也原生支持Windows。MegEngine 也支持在很多其它平台上进行推理运算。
+**注意:** MegEngine 现在支持在 Linux-64bit/Windows-64bit/macos-10.14及其以上 (MacOS只支持cpu) 等平台上安装 Python 包，支持Python3.5 到 Python3.8。对于 Windows 10 用户，可以通过安装 [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl) 进行体验，同时我们也原生支持Windows。MegEngine 也支持在很多其它平台上进行推理运算。
 
 ### 通过包管理器安装
 
@@ -26,8 +26,8 @@ python3 -m pip install megengine -f https://megengine.org.cn/whl/mge.html
 
 ## 通过源码编译安装
 
-* CMake 编译细节请参考 [BUILD_README.md](scripts/cmake-build/BUILD_README.md)
-* Python 绑定编译细节请参考 [BUILD_PYTHON_WHL_README.md](scripts/whl/BUILD_PYTHON_WHL_README.md)
+* CMake编译细节请参考 [BUILD_README.md](scripts/cmake-build/BUILD_README.md)
+* Python绑定编译细节请参考 [BUILD_PYTHON_WHL_README.md](scripts/whl/BUILD_PYTHON_WHL_README.md)
 
 ## 如何参与贡献
 

ci/cmake.sh

@@ -27,8 +27,7 @@ function build() {
             -DMGE_WITH_DISTRIBUTED=${DMGE_WITH_DISTRIBUTED} \
             -DMGE_WITH_CUDA=${DMGE_WITH_CUDA} \
             -DMGE_WITH_TEST=ON \
-            -DCMAKE_BUILD_TYPE=RelWithDebInfo \
-	    -DMGE_WITH_CUSTOM_OP=ON
+            -DCMAKE_BUILD_TYPE=RelWithDebInfo
         make -j$(($(nproc) * 2)) -I ${build_dir}
         make develop
     popd >/dev/null

imperative/python/megengine/functional/math.py

@@ -1153,35 +1153,39 @@ def dot(inp1: Tensor, inp2: Tensor) -> Tensor:
 
 
 def svd(inp: Tensor, full_matrices=False, compute_uv=True) -> Tensor:
-    r"""Computes the singular value decompositions of input matrix.
+    r"""Returns a singular value decomposition ``A = USVh`` of a matrix (or a stack of matrices) ``x`` , where ``U`` is a matrix (or a stack of matrices) with orthonormal columns, ``S`` is a vector of non-negative numbers (or stack of vectors), and ``Vh`` is a matrix (or a stack of matrices) with orthonormal rows.
 
     Args:
-        inp: input matrix, must has shape `[..., M, N]`.
+        x (Tensor): A input real tensor having the shape ``(..., M, N)`` with ``x.ndim >= 2`` .
+        full_matrices (bool, optional): If ``False`` , ``U`` and ``Vh`` have the shapes  ``(..., M, K)`` and ``(..., K, N)`` , respectively, where ``K = min(M, N)`` . If ``True`` , the shapes  are ``(..., M, M)`` and ``(..., N, N)`` , respectively. Default: ``False`` . 
+        compute_uv (bool, optional): Whether or not to compute ``U`` and ``Vh`` in addition to ``S`` . Default: ``True`` .
+
+    Note:
+        * naive does not support ``full_matrices`` and ``compute_uv`` as ``True`` .
 
     Returns:
-        output matrices, `(U, sigma, V)`.
+        Returns a tuple ( ``U`` , ``S`` , ``Vh`` ), which are  SVD factors ``U`` , ``S``, ``Vh`` of  input matrix ``x``. ( ``U`` , ``Vh`` only returned when ``compute_uv`` is True). 
+            ``U`` contains matrices orthonormal columns (i.e., the columns are left singular vectors). If ``full_matrices`` is ``True`` , the array must have shape ``(..., M, M)`` . If ``full_matrices`` is ``False`` , the array must have shape ``(..., M, K)`` , where ``K = min(M, N)`` .
 
     Examples:
 
-        .. testcode::
-
-            import numpy as np
-            from megengine import tensor
-            import megengine.functional as F
-
-            x = tensor(np.arange(0, 6, dtype=np.float32).reshape(2,3))
-            _, y, _ = F.svd(x)
-            print(y.numpy().round(decimals=3))
+        >>> import numpy as np
+        >>> x = Tensor(np.random.randn(9, 6))
+        >>> y = Tensor(np.random.randn(2, 7, 8, 3))
 
-        Outputs:
-
-        .. testoutput::
+        Reconstruction based on reduced SVD, 2D case:
+        >>> U, S, Vh = F.svd(x, full_matrices=False)
+        >>> print(U._tuple_shape, S._tuple_shape, Vh._tuple_shape)
+        (9, 6) (6,) (6, 6)
 
-            [7.348 1.   ]
+        Reconsturction based on reduced SVD, 4D case:
+        >>> u, s, vh = F.svd(y, full_matrices=False)
+        >>> print(u._tuple_shape, s._tuple_shape, vh._tuple_shape)
+        (2, 7, 8, 3) (2, 7, 3) (2, 7, 3, 3)
     """
     op = builtin.SVD(full_matrices=full_matrices, compute_uv=compute_uv)
-    U, sigma, V = apply(op, inp)
-    return U, sigma, V
+    U, S, Vh = apply(op, inp)
+    return U, S, Vh
 
 
 def _check_non_finite(inps: Iterable[Tensor], scale=1.0) -> Tensor: