Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

DOC: merge wiki edits for linalg module.

  • Loading branch information...
commit b904ccc42b0e6a18949397f8ce9a43fb3037e30c 1 parent f292cd6
@rgommers rgommers authored
Showing with 128 additions and 102 deletions.
  1. +66 −58 scipy/linalg/decomp.py
  2. +62 −44 scipy/linalg/decomp_svd.py
View
124 scipy/linalg/decomp.py
@@ -79,53 +79,55 @@ def _geneig(a1, b1, left, right, overwrite_a, overwrite_b):
return w, vr
def eig(a, b=None, left=False, right=True, overwrite_a=False, overwrite_b=False):
- """Solve an ordinary or generalized eigenvalue problem of a square matrix.
+ """
+ Solve an ordinary or generalized eigenvalue problem of a square matrix.
Find eigenvalues w and right or left eigenvectors of a general matrix::
a vr[:,i] = w[i] b vr[:,i]
a.H vl[:,i] = w[i].conj() b.H vl[:,i]
- where .H is the Hermitean conjugation.
+ where ``.H`` is the Hermitian conjugation.
Parameters
----------
- a : array, shape (M, M)
+ a : ndarray
A complex or real matrix whose eigenvalues and eigenvectors
- will be computed.
- b : array, shape (M, M)
+ will be computed. Of shape ``(M, M)``.
+ b : ndarray, optional
Right-hand side matrix in a generalized eigenvalue problem.
- If omitted, identity matrix is assumed.
- left : boolean
- Whether to calculate and return left eigenvectors
- right : boolean
- Whether to calculate and return right eigenvectors
-
- overwrite_a : boolean
- Whether to overwrite data in a (may improve performance)
- overwrite_b : boolean
- Whether to overwrite data in b (may improve performance)
+ Default is None, identity matrix is assumed. Of shape ``(M, M)``.
+ left : bool, optional
+ Whether to calculate and return left eigenvectors. Default is False.
+ right : bool, optional
+ Whether to calculate and return right eigenvectors. Default is True.
+ overwrite_a : bool, optional
+ Whether to overwrite `a`; may improve performance. Default is False.
+ overwrite_b : bool, optional
+ Whether to overwrite `b`; may improve performance. Default is False.
Returns
-------
- w : double or complex array, shape (M,)
+ w : double or complex ndarray
The eigenvalues, each repeated according to its multiplicity.
-
- (if left == True)
- vl : double or complex array, shape (M, M)
- The normalized left eigenvector corresponding to the eigenvalue w[i]
- is the column v[:,i].
-
- (if right == True)
- vr : double or complex array, shape (M, M)
- The normalized right eigenvector corresponding to the eigenvalue w[i]
- is the column vr[:,i].
-
- Raises LinAlgError if eigenvalue computation does not converge
+ Of shape (M,).
+ vl : double or complex ndarray
+ The normalized left eigenvector corresponding to the eigenvalue
+ ``w[i]`` is the column v[:,i]. Only returned if ``left=True``.
+ Of shape ``(M, M)``.
+ vr : double or complex array
+ The normalized right eigenvector corresponding to the eigenvalue
+ ``w[i]`` is the column ``vr[:,i]``. Only returned if ``right=True``.
+ Of shape ``(M, M)``.
+
+ Raises
+ ------
+ LinAlgError
+ If eigenvalue computation does not converge.
See Also
--------
- eigh : eigenvalues and right eigenvectors for symmetric/Hermitian arrays
+ eigh : Eigenvalues and right eigenvectors for symmetric/Hermitian arrays.
"""
a1 = asarray_chkfinite(a)
@@ -534,7 +536,8 @@ def eig_banded(a_band, lower=False, eigvals_only=False, overwrite_a_band=False,
return w, v
def eigvals(a, b=None, overwrite_a=False):
- """Compute eigenvalues from an ordinary or generalized eigenvalue problem.
+ """
+ Compute eigenvalues from an ordinary or generalized eigenvalue problem.
Find eigenvalues of a general matrix::
@@ -542,28 +545,32 @@ def eigvals(a, b=None, overwrite_a=False):
Parameters
----------
- a : array, shape (M, M)
+ a : ndarray
A complex or real matrix whose eigenvalues and eigenvectors
- will be computed.
- b : array, shape (M, M)
+ will be computed. Of shape ``(M, M)``.
+ b : ndarray, optional
Right-hand side matrix in a generalized eigenvalue problem.
- If omitted, identity matrix is assumed.
- overwrite_a : boolean
- Whether to overwrite data in a (may improve performance)
+ Default is None, which means that the identity matrix is assumed.
+ Of shape ``(M, M)``.
+ overwrite_a : bool, optional
+ Whether to overwrite `a`; may improve performance. Default is False.
Returns
-------
- w : double or complex array, shape (M,)
+ w : double or complex ndarray
The eigenvalues, each repeated according to its multiplicity,
- but not in any specific order.
+ but not in any specific order. Of shape (M,).
- Raises LinAlgError if eigenvalue computation does not converge
+ Raises
+ ------
+ LinAlgError
+ If eigenvalue computation does not converge
See Also
--------
- eigvalsh : eigenvalues of symmetric or Hemitiean arrays
- eig : eigenvalues and right eigenvectors of general arrays
- eigh : eigenvalues and eigenvectors of symmetric/Hermitean arrays.
+ eigvalsh : eigenvalues of symmetric or Hermitian arrays,
+ eig : eigenvalues and right eigenvectors of general arrays.
+ eigh : eigenvalues and eigenvectors of symmetric/Hermitian arrays.
"""
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,
def hessenberg(a, calc_q=False, overwrite_a=False):
- """Compute Hessenberg form of a matrix.
+ """
+ Compute Hessenberg form of a matrix.
- The Hessenberg decomposition is
+ The Hessenberg decomposition is::
A = Q H Q^H
- where Q is unitary/orthogonal and H has only zero elements below the first
- subdiagonal.
+ where `Q` is unitary/orthogonal and `H` has only zero elements below
+ the first sub-diagonal.
Parameters
----------
- a : array, shape (M,M)
- Matrix to bring into Hessenberg form
- calc_q : boolean
- Whether to compute the transformation matrix
- overwrite_a : boolean
- Whether to ovewrite data in a (may improve performance)
+ a : ndarray
+ Matrix to bring into Hessenberg form, of shape ``(M,M)``.
+ calc_q : bool, optional
+ Whether to compute the transformation matrix. Default is False.
+ overwrite_a : bool, optional
+ Whether to overwrite `a`; may improve performance.
+ Default is False.
Returns
-------
- H : array, shape (M,M)
- Hessenberg form of A
-
- (If calc_q == True)
- Q : array, shape (M,M)
- Unitary/orthogonal similarity transformation matrix s.t. A = Q H Q^H
+ H : ndarray
+ Hessenberg form of `a`, of shape (M,M).
+ Q : ndarray
+ Unitary/orthogonal similarity transformation matrix ``A = Q H Q^H``.
+ Only returned if ``calc_q=True``. Of shape (M,M).
"""
a1 = asarray(a)
View
106 scipy/linalg/decomp_svd.py
@@ -12,40 +12,57 @@
def svd(a, full_matrices=True, compute_uv=True, overwrite_a=False):
- """Singular Value Decomposition.
+ """
+ Singular Value Decomposition.
- Factorizes the matrix a into two unitary matrices U and Vh and
- an 1d-array s of singular values (real, non-negative) such that
- a == U S Vh if S is an suitably shaped matrix of zeros whose
- main diagonal is s.
+ Factorizes the matrix a into two unitary matrices U and Vh, and
+ a 1-D array s of singular values (real, non-negative) such that
+ ``a == U*S*Vh``, where S is a suitably shaped matrix of zeros with
+ main diagonal s.
Parameters
----------
- a : array, shape (M, N)
- Matrix to decompose
- full_matrices : boolean
- If true, U, Vh are shaped (M,M), (N,N)
- If false, the shapes are (M,K), (K,N) where K = min(M,N)
- compute_uv : boolean
- Whether to compute also U, Vh in addition to s (Default: true)
- overwrite_a : boolean
- Whether data in a is overwritten (may improve performance)
+ a : ndarray
+ Matrix to decompose, of shape ``(M,N)``.
+ full_matrices : bool, optional
+ If True, `U` and `Vh` are of shape ``(M,M)``, ``(N,N)``.
+ If False, the shapes are ``(M,K)`` and ``(K,N)``, where
+ ``K = min(M,N)``.
+ compute_uv : bool, optional
+ Whether to compute also `U` and `Vh` in addition to `s`.
+ Default is True.
+ overwrite_a : bool, optional
+ Whether to overwrite `a`; may improve performance.
+ Default is False.
Returns
-------
- U: array, shape (M,M) or (M,K) depending on full_matrices
- s: array, shape (K,)
- The singular values, sorted so that s[i] >= s[i+1]. K = min(M, N)
- Vh: array, shape (N,N) or (K,N) depending on full_matrices
-
- For compute_uv = False, only s is returned.
+ U : ndarray
+ Unitary matrix having left singular vectors as columns.
+ Of shape ``(M,M)`` or ``(M,K)``, depending on `full_matrices`.
+ s : ndarray
+ The singular values, sorted in non-increasing order.
+ Of shape (K,), with ``K = min(M, N)``.
+ Vh : ndarray
+ Unitary matrix having right singular vectors as rows.
+ Of shape ``(N,N)`` or ``(K,N)`` depending on `full_matrices`.
+
+ For ``compute_uv = False``, only `s` is returned.
+
+ Raises
+ ------
+ LinAlgError
+ If SVD computation does not converge.
- Raises LinAlgError if SVD computation does not converge
+ See also
+ --------
+ svdvals : Compute singular values of a matrix.
+ diagsvd : Construct the Sigma matrix, given the vector s.
Examples
--------
- >>> from scipy import random, linalg, allclose, dot
- >>> a = random.randn(9, 6) + 1j*random.randn(9, 6)
+ >>> from scipy import linalg
+ >>> a = np.random.randn(9, 6) + 1.j*np.random.randn(9, 6)
>>> U, s, Vh = linalg.svd(a)
>>> U.shape, Vh.shape, s.shape
((9, 9), (6, 6), (6,))
@@ -54,18 +71,13 @@ def svd(a, full_matrices=True, compute_uv=True, overwrite_a=False):
>>> U.shape, Vh.shape, s.shape
((9, 6), (6, 6), (6,))
>>> S = linalg.diagsvd(s, 6, 6)
- >>> allclose(a, dot(U, dot(S, Vh)))
+ >>> np.allclose(a, np.dot(U, np.dot(S, Vh)))
True
>>> s2 = linalg.svd(a, compute_uv=False)
- >>> allclose(s, s2)
+ >>> np.allclose(s, s2)
True
- See also
- --------
- svdvals : return singular values of a matrix
- diagsvd : return the Sigma matrix, given the vector s
-
"""
a1 = asarray_chkfinite(a)
if len(a1.shape) != 2:
@@ -90,40 +102,46 @@ def svd(a, full_matrices=True, compute_uv=True, overwrite_a=False):
return s
def svdvals(a, overwrite_a=False):
- """Compute singular values of a matrix.
+ """
+ Compute singular values of a matrix.
Parameters
----------
- a : array, shape (M, N)
- Matrix to decompose
- overwrite_a : boolean
- Whether data in a is overwritten (may improve performance)
+ a : ndarray
+ Matrix to decompose, of shape ``(M, N)``.
+ overwrite_a : bool, optional
+ Whether to overwrite `a`; may improve performance.
+ Default is False.
Returns
-------
- s: array, shape (K,)
- The singular values, sorted so that s[i] >= s[i+1]. K = min(M, N)
+ s : ndarray
+ The singular values, sorted in decreasing order.
+ Of shape ``(K,)``, with``K = min(M, N)``.
- Raises LinAlgError if SVD computation does not converge
+ Raises
+ ------
+ LinAlgError
+ If SVD computation does not converge.
See also
--------
- svd : return the full singular value decomposition of a matrix
- diagsvd : return the Sigma matrix, given the vector s
+ svd : Compute the full singular value decomposition of a matrix.
+ diagsvd : Construct the Sigma matrix, given the vector s.
"""
return svd(a, compute_uv=0, overwrite_a=overwrite_a)
def diagsvd(s, M, N):
- """Construct the sigma matrix in SVD from singular values and size M,N.
+ """
+ Construct the sigma matrix in SVD from singular values and size M, N.
Parameters
----------
s : array, shape (M,) or (N,)
Singular values
- M : integer
- N : integer
- Size of the matrix whose singular values are s
+ M, N : int
+ Number of rows and columns in the matrix whose singular values are s
Returns
-------
Please sign in to comment.
Something went wrong with that request. Please try again.