From 95657d54cf1e08893d0769d4e6d662c75e74cadd Mon Sep 17 00:00:00 2001 From: jieli-matrix Date: Mon, 6 Dec 2021 23:15:28 +0800 Subject: [PATCH] docs(mge/functional): update functional.math.svd docstring --- imperative/python/megengine/functional/math.py | 58 ++++++++++++++++---------- 1 file changed, 37 insertions(+), 21 deletions(-) diff --git a/imperative/python/megengine/functional/math.py b/imperative/python/megengine/functional/math.py index facd8206..87343847 100644 --- a/imperative/python/megengine/functional/math.py +++ b/imperative/python/megengine/functional/math.py @@ -1151,36 +1151,52 @@ def dot(inp1: Tensor, inp2: Tensor) -> Tensor: return result -def svd(inp: Tensor, full_matrices=False, compute_uv=True) -> Tensor: - r"""Computes the singular value decompositions of input matrix. +def svd(x: Tensor, full_matrices=False, compute_uv=True) -> Tensor: + 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`` . 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)) - - Outputs: + ``S`` contains the vector(s) of singular values of length ``K`` , where ``K = min(M, N)`` . For each vector, the singular values must be sorted in descending order by magnitude, such that ``s[..., 0]`` is the largest value, ``s[..., 1]`` is the second largest value, etc. The first ``x.ndim-2`` dimensions must have the same shape as those of the input ``x`` . - .. testoutput:: + ``Vh`` contains orthonormal rows (i.e., the rows are the right singular vectors and the array is the adjoint). If ``full_matrices`` is ``True`` , the array must have shape ``(..., N, N)`` . If ``full_matrices`` is ``False`` , the array must have shape ``(..., K, N)`` where ``K = min(M, N)`` . The first ``x.ndim-2`` dimensions must have the same shape as those of the input ``x`` . + Each returned array must have the same floating-point data type as ``x`` . - [7.348 1. ] + Examples: + >>> import numpy as np + >>> x = Tensor(np.random.randn(9, 6)) + >>> y = Tensor(np.random.randn(2, 7, 8, 3)) + + Reconstruction based on full SVD, 2D case: + >>> U, S, Vh = F.svd(x, full_matrices=True) + >>> U.shape, S.shape, Vh.shape + ((9, 9), (6,), (6, 6)) + + Reconstruction based on reduced SVD, 2D case: + >>> U, S, Vh = F.svd(x, full_matrices=False) + >>> U.shape, S.shape, Vh.shape + ((9, 6), (6,), (6, 6)) + + Reconsturction based on full SVD, 4D case: + >>> u, s, vh = F.svd(y, full_matrices=True) + >>> u.shape, s.shape, vh.shape + ((2, 7, 8, 8), (2, 7, 3), (2, 7, 3, 3)) + + Reconsturction based on reduced SVD, 4D case: + >>> u, s, vh = F.svd(y, full_matrices=False) + >>> u.shape, s.shape, vh.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, x) + return U, S, Vh def _check_non_finite(inps: Iterable[Tensor], scale=1.0) -> Tensor: