# public scipy /scipy

### Subversion checkout URL

You can clone with HTTPS or Subversion.

DOC: merge wiki edits for linalg module.

commit b904ccc42b0e6a18949397f8ce9a43fb3037e30c 1 parent f292cd6
authored

Showing 2 changed files with 128 additions and 102 deletions.

1. scipy/linalg/decomp.py
2. scipy/linalg/decomp_svd.py
124  scipy/linalg/decomp.py
 `@@ -79,53 +79,55 @@ def _geneig(a1, b1, left, right, overwrite_a, overwrite_b):` 79 79 ` return w, vr` 80 80 ` ` 81 81 ` def eig(a, b=None, left=False, right=True, overwrite_a=False, overwrite_b=False):` 82 `- """Solve an ordinary or generalized eigenvalue problem of a square matrix.` 82 `+ """` 83 `+ Solve an ordinary or generalized eigenvalue problem of a square matrix.` 83 84 ` ` 84 85 ` Find eigenvalues w and right or left eigenvectors of a general matrix::` 85 86 ` ` 86 87 ` a vr[:,i] = w[i] b vr[:,i]` 87 88 ` a.H vl[:,i] = w[i].conj() b.H vl[:,i]` 88 89 ` ` 89 `- where .H is the Hermitean conjugation.` 90 `+ where ``.H`` is the Hermitian conjugation.` 90 91 ` ` 91 92 ` Parameters` 92 93 ` ----------` 93 `- a : array, shape (M, M)` 94 `+ a : ndarray` 94 95 ` A complex or real matrix whose eigenvalues and eigenvectors` 95 `- will be computed.` 96 `- b : array, shape (M, M)` 96 `+ will be computed. Of shape ``(M, M)``.` 97 `+ b : ndarray, optional` 97 98 ` Right-hand side matrix in a generalized eigenvalue problem.` 98 `- If omitted, identity matrix is assumed.` 99 `- left : boolean` 100 `- Whether to calculate and return left eigenvectors` 101 `- right : boolean` 102 `- Whether to calculate and return right eigenvectors` 103 `-` 104 `- overwrite_a : boolean` 105 `- Whether to overwrite data in a (may improve performance)` 106 `- overwrite_b : boolean` 107 `- Whether to overwrite data in b (may improve performance)` 99 `+ Default is None, identity matrix is assumed. Of shape ``(M, M)``.` 100 `+ left : bool, optional` 101 `+ Whether to calculate and return left eigenvectors. Default is False.` 102 `+ right : bool, optional` 103 `+ Whether to calculate and return right eigenvectors. Default is True.` 104 `+ overwrite_a : bool, optional` 105 `+ Whether to overwrite `a`; may improve performance. Default is False.` 106 `+ overwrite_b : bool, optional` 107 `+ Whether to overwrite `b`; may improve performance. Default is False.` 108 108 ` ` 109 109 ` Returns` 110 110 ` -------` 111 `- w : double or complex array, shape (M,)` 111 `+ w : double or complex ndarray` 112 112 ` The eigenvalues, each repeated according to its multiplicity.` 113 `-` 114 `- (if left == True)` 115 `- vl : double or complex array, shape (M, M)` 116 `- The normalized left eigenvector corresponding to the eigenvalue w[i]` 117 `- is the column v[:,i].` 118 `-` 119 `- (if right == True)` 120 `- vr : double or complex array, shape (M, M)` 121 `- The normalized right eigenvector corresponding to the eigenvalue w[i]` 122 `- is the column vr[:,i].` 123 `-` 124 `- Raises LinAlgError if eigenvalue computation does not converge` 113 `+ Of shape (M,).` 114 `+ vl : double or complex ndarray` 115 `+ The normalized left eigenvector corresponding to the eigenvalue` 116 `+ ``w[i]`` is the column v[:,i]. Only returned if ``left=True``.` 117 `+ Of shape ``(M, M)``.` 118 `+ vr : double or complex array` 119 `+ The normalized right eigenvector corresponding to the eigenvalue` 120 `+ ``w[i]`` is the column ``vr[:,i]``. Only returned if ``right=True``.` 121 `+ Of shape ``(M, M)``.` 122 `+` 123 `+ Raises` 124 `+ ------` 125 `+ LinAlgError` 126 `+ If eigenvalue computation does not converge.` 125 127 ` ` 126 128 ` See Also` 127 129 ` --------` 128 `- eigh : eigenvalues and right eigenvectors for symmetric/Hermitian arrays` 130 `+ eigh : Eigenvalues and right eigenvectors for symmetric/Hermitian arrays.` 129 131 ` ` 130 132 ` """` 131 133 ` a1 = asarray_chkfinite(a)` `@@ -534,7 +536,8 @@ def eig_banded(a_band, lower=False, eigvals_only=False, overwrite_a_band=False,` 534 536 ` return w, v` 535 537 ` ` 536 538 ` def eigvals(a, b=None, overwrite_a=False):` 537 `- """Compute eigenvalues from an ordinary or generalized eigenvalue problem.` 539 `+ """` 540 `+ Compute eigenvalues from an ordinary or generalized eigenvalue problem.` 538 541 ` ` 539 542 ` Find eigenvalues of a general matrix::` 540 543 ` ` `@@ -542,28 +545,32 @@ def eigvals(a, b=None, overwrite_a=False):` 542 545 ` ` 543 546 ` Parameters` 544 547 ` ----------` 545 `- a : array, shape (M, M)` 548 `+ a : ndarray` 546 549 ` A complex or real matrix whose eigenvalues and eigenvectors` 547 `- will be computed.` 548 `- b : array, shape (M, M)` 550 `+ will be computed. Of shape ``(M, M)``.` 551 `+ b : ndarray, optional` 549 552 ` Right-hand side matrix in a generalized eigenvalue problem.` 550 `- If omitted, identity matrix is assumed.` 551 `- overwrite_a : boolean` 552 `- Whether to overwrite data in a (may improve performance)` 553 `+ Default is None, which means that the identity matrix is assumed.` 554 `+ Of shape ``(M, M)``.` 555 `+ overwrite_a : bool, optional` 556 `+ Whether to overwrite `a`; may improve performance. Default is False.` 553 557 ` ` 554 558 ` Returns` 555 559 ` -------` 556 `- w : double or complex array, shape (M,)` 560 `+ w : double or complex ndarray` 557 561 ` The eigenvalues, each repeated according to its multiplicity,` 558 `- but not in any specific order.` 562 `+ but not in any specific order. Of shape (M,).` 559 563 ` ` 560 `- Raises LinAlgError if eigenvalue computation does not converge` 564 `+ Raises` 565 `+ ------` 566 `+ LinAlgError` 567 `+ If eigenvalue computation does not converge` 561 568 ` ` 562 569 ` See Also` 563 570 ` --------` 564 `- eigvalsh : eigenvalues of symmetric or Hemitiean arrays` 565 `- eig : eigenvalues and right eigenvectors of general arrays` 566 `- eigh : eigenvalues and eigenvectors of symmetric/Hermitean arrays.` 571 `+ eigvalsh : eigenvalues of symmetric or Hermitian arrays,` 572 `+ eig : eigenvalues and right eigenvectors of general arrays.` 573 `+ eigh : eigenvalues and eigenvectors of symmetric/Hermitian arrays.` 567 574 ` ` 568 575 ` """` 569 576 ` return eig(a, b=b, left=0, right=0, overwrite_a=overwrite_a)` `@@ -706,32 +713,33 @@ def eigvals_banded(a_band, lower=False, overwrite_a_band=False,` 706 713 ` ` 707 714 ` ` 708 715 ` def hessenberg(a, calc_q=False, overwrite_a=False):` 709 `- """Compute Hessenberg form of a matrix.` 716 `+ """` 717 `+ Compute Hessenberg form of a matrix.` 710 718 ` ` 711 `- The Hessenberg decomposition is` 719 `+ The Hessenberg decomposition is::` 712 720 ` ` 713 721 ` A = Q H Q^H` 714 722 ` ` 715 `- where Q is unitary/orthogonal and H has only zero elements below the first` 716 `- subdiagonal.` 723 `+ where `Q` is unitary/orthogonal and `H` has only zero elements below` 724 `+ the first sub-diagonal.` 717 725 ` ` 718 726 ` Parameters` 719 727 ` ----------` 720 `- a : array, shape (M,M)` 721 `- Matrix to bring into Hessenberg form` 722 `- calc_q : boolean` 723 `- Whether to compute the transformation matrix` 724 `- overwrite_a : boolean` 725 `- Whether to ovewrite data in a (may improve performance)` 728 `+ a : ndarray` 729 `+ Matrix to bring into Hessenberg form, of shape ``(M,M)``.` 730 `+ calc_q : bool, optional` 731 `+ Whether to compute the transformation matrix. Default is False.` 732 `+ overwrite_a : bool, optional` 733 `+ Whether to overwrite `a`; may improve performance.` 734 `+ Default is False.` 726 735 ` ` 727 736 ` Returns` 728 737 ` -------` 729 `- H : array, shape (M,M)` 730 `- Hessenberg form of A` 731 `-` 732 `- (If calc_q == True)` 733 `- Q : array, shape (M,M)` 734 `- Unitary/orthogonal similarity transformation matrix s.t. A = Q H Q^H` 738 `+ H : ndarray` 739 `+ Hessenberg form of `a`, of shape (M,M).` 740 `+ Q : ndarray` 741 `+ Unitary/orthogonal similarity transformation matrix ``A = Q H Q^H``.` 742 `+ Only returned if ``calc_q=True``. Of shape (M,M).` 735 743 ` ` 736 744 ` """` 737 745 ` a1 = asarray(a)`
106  scipy/linalg/decomp_svd.py
 `@@ -12,40 +12,57 @@` 12 12 ` ` 13 13 ` ` 14 14 ` def svd(a, full_matrices=True, compute_uv=True, overwrite_a=False):` 15 `- """Singular Value Decomposition.` 15 `+ """` 16 `+ Singular Value Decomposition.` 16 17 ` ` 17 `- Factorizes the matrix a into two unitary matrices U and Vh and` 18 `- an 1d-array s of singular values (real, non-negative) such that` 19 `- a == U S Vh if S is an suitably shaped matrix of zeros whose` 20 `- main diagonal is s.` 18 `+ Factorizes the matrix a into two unitary matrices U and Vh, and` 19 `+ a 1-D array s of singular values (real, non-negative) such that` 20 `+ ``a == U*S*Vh``, where S is a suitably shaped matrix of zeros with` 21 `+ main diagonal s.` 21 22 ` ` 22 23 ` Parameters` 23 24 ` ----------` 24 `- a : array, shape (M, N)` 25 `- Matrix to decompose` 26 `- full_matrices : boolean` 27 `- If true, U, Vh are shaped (M,M), (N,N)` 28 `- If false, the shapes are (M,K), (K,N) where K = min(M,N)` 29 `- compute_uv : boolean` 30 `- Whether to compute also U, Vh in addition to s (Default: true)` 31 `- overwrite_a : boolean` 32 `- Whether data in a is overwritten (may improve performance)` 25 `+ a : ndarray` 26 `+ Matrix to decompose, of shape ``(M,N)``.` 27 `+ full_matrices : bool, optional` 28 `+ If True, `U` and `Vh` are of shape ``(M,M)``, ``(N,N)``.` 29 `+ If False, the shapes are ``(M,K)`` and ``(K,N)``, where` 30 `+ ``K = min(M,N)``.` 31 `+ compute_uv : bool, optional` 32 `+ Whether to compute also `U` and `Vh` in addition to `s`.` 33 `+ Default is True.` 34 `+ overwrite_a : bool, optional` 35 `+ Whether to overwrite `a`; may improve performance.` 36 `+ Default is False.` 33 37 ` ` 34 38 ` Returns` 35 39 ` -------` 36 `- U: array, shape (M,M) or (M,K) depending on full_matrices` 37 `- s: array, shape (K,)` 38 `- The singular values, sorted so that s[i] >= s[i+1]. K = min(M, N)` 39 `- Vh: array, shape (N,N) or (K,N) depending on full_matrices` 40 `-` 41 `- For compute_uv = False, only s is returned.` 40 `+ U : ndarray` 41 `+ Unitary matrix having left singular vectors as columns.` 42 `+ Of shape ``(M,M)`` or ``(M,K)``, depending on `full_matrices`.` 43 `+ s : ndarray` 44 `+ The singular values, sorted in non-increasing order.` 45 `+ Of shape (K,), with ``K = min(M, N)``.` 46 `+ Vh : ndarray` 47 `+ Unitary matrix having right singular vectors as rows.` 48 `+ Of shape ``(N,N)`` or ``(K,N)`` depending on `full_matrices`.` 49 `+` 50 `+ For ``compute_uv = False``, only `s` is returned.` 51 `+` 52 `+ Raises` 53 `+ ------` 54 `+ LinAlgError` 55 `+ If SVD computation does not converge.` 42 56 ` ` 43 `- Raises LinAlgError if SVD computation does not converge` 57 `+ See also` 58 `+ --------` 59 `+ svdvals : Compute singular values of a matrix.` 60 `+ diagsvd : Construct the Sigma matrix, given the vector s.` 44 61 ` ` 45 62 ` Examples` 46 63 ` --------` 47 `- >>> from scipy import random, linalg, allclose, dot` 48 `- >>> a = random.randn(9, 6) + 1j*random.randn(9, 6)` 64 `+ >>> from scipy import linalg` 65 `+ >>> a = np.random.randn(9, 6) + 1.j*np.random.randn(9, 6)` 49 66 ` >>> U, s, Vh = linalg.svd(a)` 50 67 ` >>> U.shape, Vh.shape, s.shape` 51 68 ` ((9, 9), (6, 6), (6,))` `@@ -54,18 +71,13 @@ def svd(a, full_matrices=True, compute_uv=True, overwrite_a=False):` 54 71 ` >>> U.shape, Vh.shape, s.shape` 55 72 ` ((9, 6), (6, 6), (6,))` 56 73 ` >>> S = linalg.diagsvd(s, 6, 6)` 57 `- >>> allclose(a, dot(U, dot(S, Vh)))` 74 `+ >>> np.allclose(a, np.dot(U, np.dot(S, Vh)))` 58 75 ` True` 59 76 ` ` 60 77 ` >>> s2 = linalg.svd(a, compute_uv=False)` 61 `- >>> allclose(s, s2)` 78 `+ >>> np.allclose(s, s2)` 62 79 ` True` 63 80 ` ` 64 `- See also` 65 `- --------` 66 `- svdvals : return singular values of a matrix` 67 `- diagsvd : return the Sigma matrix, given the vector s` 68 `-` 69 81 ` """` 70 82 ` a1 = asarray_chkfinite(a)` 71 83 ` if len(a1.shape) != 2:` `@@ -90,40 +102,46 @@ def svd(a, full_matrices=True, compute_uv=True, overwrite_a=False):` 90 102 ` return s` 91 103 ` ` 92 104 ` def svdvals(a, overwrite_a=False):` 93 `- """Compute singular values of a matrix.` 105 `+ """` 106 `+ Compute singular values of a matrix.` 94 107 ` ` 95 108 ` Parameters` 96 109 ` ----------` 97 `- a : array, shape (M, N)` 98 `- Matrix to decompose` 99 `- overwrite_a : boolean` 100 `- Whether data in a is overwritten (may improve performance)` 110 `+ a : ndarray` 111 `+ Matrix to decompose, of shape ``(M, N)``.` 112 `+ overwrite_a : bool, optional` 113 `+ Whether to overwrite `a`; may improve performance.` 114 `+ Default is False.` 101 115 ` ` 102 116 ` Returns` 103 117 ` -------` 104 `- s: array, shape (K,)` 105 `- The singular values, sorted so that s[i] >= s[i+1]. K = min(M, N)` 118 `+ s : ndarray` 119 `+ The singular values, sorted in decreasing order.` 120 `+ Of shape ``(K,)``, with``K = min(M, N)``.` 106 121 ` ` 107 `- Raises LinAlgError if SVD computation does not converge` 122 `+ Raises` 123 `+ ------` 124 `+ LinAlgError` 125 `+ If SVD computation does not converge.` 108 126 ` ` 109 127 ` See also` 110 128 ` --------` 111 `- svd : return the full singular value decomposition of a matrix` 112 `- diagsvd : return the Sigma matrix, given the vector s` 129 `+ svd : Compute the full singular value decomposition of a matrix.` 130 `+ diagsvd : Construct the Sigma matrix, given the vector s.` 113 131 ` ` 114 132 ` """` 115 133 ` return svd(a, compute_uv=0, overwrite_a=overwrite_a)` 116 134 ` ` 117 135 ` def diagsvd(s, M, N):` 118 `- """Construct the sigma matrix in SVD from singular values and size M,N.` 136 `+ """` 137 `+ Construct the sigma matrix in SVD from singular values and size M, N.` 119 138 ` ` 120 139 ` Parameters` 121 140 ` ----------` 122 141 ` s : array, shape (M,) or (N,)` 123 142 ` Singular values` 124 `- M : integer` 125 `- N : integer` 126 `- Size of the matrix whose singular values are s` 143 `+ M, N : int` 144 `+ Number of rows and columns in the matrix whose singular values are s` 127 145 ` ` 128 146 ` Returns` 129 147 ` -------`