# [Scipy-svn] r6881 - trunk/scipy/linalg

scipy-svn@scip... scipy-svn@scip...
Sun Nov 14 03:57:33 CST 2010

```Author: rgommers
Date: 2010-11-14 03:57:33 -0600 (Sun, 14 Nov 2010)
New Revision: 6881

Modified:
trunk/scipy/linalg/__init__.py
trunk/scipy/linalg/basic.py
trunk/scipy/linalg/special_matrices.py
Log:
DOC: merge wiki edits for linalg module.

Modified: trunk/scipy/linalg/__init__.py
===================================================================
--- trunk/scipy/linalg/__init__.py	2010-11-14 07:08:13 UTC (rev 6880)
+++ trunk/scipy/linalg/__init__.py	2010-11-14 09:57:33 UTC (rev 6881)
@@ -1,3 +1,98 @@
+"""
+Linear Algebra
+==============
+
+Basics
+------
+
+.. autosummary::
+   :toctree: generated/
+
+   inv - Find the inverse of a square matrix
+   solve - Solve a linear system of equations
+   solve_banded - Solve a banded linear system
+   solveh_banded - Solve a Hermitian or symmetric banded system
+   det - Find the determinant of a square matrix
+   norm - Matrix and vector norm
+   lstsq - Solve a linear least-squares problem
+   pinv - Pseudo-inverse (Moore-Penrose) using lstsq
+   pinv2 - Pseudo-inverse using svd
+
+Eigenvalue Problems
+-------------------
+
+.. autosummary::
+   :toctree: generated/
+
+   eig - Find the eigenvalues and eigenvectors of a square matrix
+   eigvals - Find just the eigenvalues of a square matrix
+   eigh - Find the e-vals and e-vectors of a Hermitian or symmetric matrix
+   eigvalsh - Find just the eigenvalues of a Hermitian or symmetric matrix
+   eig_banded - Find the eigenvalues and eigenvectors of a banded matrix
+   eigvals_banded - Find just the eigenvalues of a banded matrix
+
+Decompositions
+--------------
+
+.. autosummary::
+   :toctree: generated/
+
+   lu - LU decomposition of a matrix
+   lu_factor - LU decomposition returning unordered matrix and pivots
+   lu_solve - Solve Ax=b using back substitution with output of lu_factor
+   svd - Singular value decomposition of a matrix
+   svdvals - Singular values of a matrix
+   diagsvd - Construct matrix of singular values from output of svd
+   orth - Construct orthonormal basis for the range of A using svd
+   cholesky - Cholesky decomposition of a matrix
+   cholesky_banded - Cholesky decomp. of a sym. or Hermitian banded matrix
+   cho_factor - Cholesky decomposition for use in solving a linear system
+   cho_solve - Solve previously factored linear system
+   cho_solve_banded - Solve previously factored banded linear system
+   qr - QR decomposition of a matrix
+   schur - Schur decomposition of a matrix
+   rsf2csf - Real to complex Schur form
+   hessenberg - Hessenberg form of a matrix
+
+Matrix Functions
+----------------
+
+.. autosummary::
+   :toctree: generated/
+
+   expm - Matrix exponential using Pade approximation
+   expm2 - Matrix exponential using eigenvalue decomposition
+   expm3 - Matrix exponential using Taylor-series expansion
+   logm - Matrix logarithm
+   cosm - Matrix cosine
+   sinm - Matrix sine
+   tanm - Matrix tangent
+   coshm - Matrix hyperbolic cosine
+   sinhm - Matrix hyperbolic sine
+   tanhm - Matrix hyperbolic tangent
+   signm - Matrix sign
+   sqrtm - Matrix square root
+   funm - Evaluating an arbitrary matrix function
+
+Special Matrices
+----------------
+
+.. autosummary::
+   :toctree: generated/
+
+   block_diag - Construct a block diagonal matrix from submatrices
+   circulant - Circulant matrix
+   companion - Companion matrix
+   hankel - Hankel matrix
+   kron - Kronecker product of two arrays
+   leslie - Leslie matrix
+   toeplitz - Toeplitz matrix
+   tri - Construct a matrix filled with ones at and below a given diagonal
+   tril - Construct a lower-triangular matrix from a given matrix
+   triu - Construct an upper-triangular matrix from a given matrix
+
+"""
#
# linalg - Dense Linear Algebra routines
#

Modified: trunk/scipy/linalg/basic.py
===================================================================
--- trunk/scipy/linalg/basic.py	2010-11-14 07:08:13 UTC (rev 6880)
+++ trunk/scipy/linalg/basic.py	2010-11-14 09:57:33 UTC (rev 6881)
@@ -260,29 +260,35 @@

# matrix inversion
def inv(a, overwrite_a=False):
-    """Compute the inverse of a matrix.
+    """
+    Compute the inverse of a matrix.

Parameters
----------
-    a : array-like, shape (M, M)
-        Matrix to be inverted
+    a : array_like
+        Square matrix to be inverted.
overwrite_a : bool, optional
-        Discard data in ``a`` (may improve performance)
+        Discard data in `a` (may improve performance). Default is False.

Returns
-------
-    ainv : array-like, shape (M, M)
-        Inverse of the matrix a
+    ainv : ndarray
+        Inverse of the matrix `a`.

-    Raises LinAlgError if a is singular
+    Raises
+    ------
+    LinAlgError :
+        If `a` is singular.
+    ValueError :
+        If `a` is not square, or not 2-dimensional.

Examples
--------
-    >>> a = array([[1., 2.], [3., 4.]])
-    >>> inv(a)
+    >>> a = np.array([[1., 2.], [3., 4.]])
+    >>> sp.linalg.inv(a)
array([[-2. ,  1. ],
[ 1.5, -0.5]])
-    >>> dot(a, inv(a))
+    >>> np.dot(a, sp.linalg.inv(a))
array([[ 1.,  0.],
[ 0.,  1.]])

Modified: trunk/scipy/linalg/special_matrices.py
===================================================================
--- trunk/scipy/linalg/special_matrices.py	2010-11-14 07:08:13 UTC (rev 6880)
+++ trunk/scipy/linalg/special_matrices.py	2010-11-14 09:57:33 UTC (rev 6881)
@@ -118,27 +118,26 @@
"""
Construct a Toeplitz matrix.

-    The Toepliz matrix has constant diagonals, with c as its first column
-    and r as its first row.  If r is not given, r == conjugate(c) is
+    The Toeplitz matrix has constant diagonals, with c as its first column
+    and r as its first row.  If r is not given, ``r == conjugate(c)`` is
assumed.

Parameters
----------
-    c : array-like, 1D
+    c : array_like
First column of the matrix.  Whatever the actual shape of `c`, it
-        will be converted to a 1D array.
-    r : array-like, 1D
-        First row of the matrix. If None, `r = conjugate(c)` is assumed; in
-        this case, if `c[0]` is real, the result is a Hermitian matrix.
-        `r[0]` is ignored; the first row of the returned matrix is
-        `[c[0], r[1:]]`.  Whatever the actual shape of `r`, it will be
-        converted to a 1D array.
+        will be converted to a 1-D array.
+    r : array_like
+        First row of the matrix. If None, ``r = conjugate(c)`` is assumed;
+        in this case, if c[0] is real, the result is a Hermitian matrix.
+        r[0] is ignored; the first row of the returned matrix is
+        ``[c[0], r[1:]]``.  Whatever the actual shape of `r`, it will be
+        converted to a 1-D array.

Returns
-------
A : array, shape (len(c), len(r))
-        The Toeplitz matrix.
-        dtype is the same as `(c[0] + r[0]).dtype`.
+        The Toeplitz matrix. Dtype is the same as ``(c[0] + r[0]).dtype``.

--------
@@ -184,8 +183,8 @@

Parameters
----------
-    c : array-like, 1D
-        First column of the matrix.
+    c : array_like
+        1-D array, the first column of the matrix.

Returns
-------
@@ -227,20 +226,19 @@

Parameters
----------
-    c : array-like, 1D
+    c : array_like
First column of the matrix.  Whatever the actual shape of `c`, it
-        will be converted to a 1D array.
-    r : array-like, 1D
-        Last row of the matrix. If None, `r = zeros_like(c)` is assumed.
-        `r[0]` is ignored; the last row of the returned matrix is
-        `[c[-1], r[1:]]`.  Whatever the actual shape of `r`, it will be
-        converted to a 1D array.
+        will be converted to a 1-D array.
+    r : array_like, 1D
+        Last row of the matrix. If None, ``r = zeros_like(c)`` is assumed.
+        r[0] is ignored; the last row of the returned matrix is
+        ``[c[-1], r[1:]]``.  Whatever the actual shape of `r`, it will be
+        converted to a 1-D array.

Returns
-------
A : array, shape (len(c), len(r))
-        The Hankel matrix.
-        dtype is the same as `(c[0] + r[0]).dtype`.
+        The Hankel matrix. Dtype is the same as ``(c[0] + r[0]).dtype``.

--------
@@ -331,28 +329,47 @@

def leslie(f, s):
-    """Create a Leslie matrix.
-
+    """
+    Create a Leslie matrix.
+
+    Given the length n array of fecundity coefficients `f` and the length
+    n-1 array of survival coefficents `s`, return the associated Leslie matrix.
+
Parameters
----------
-    f : array-like, 1D
-        The "fecundity" coefficients.
-    s : array-like, 1D
-        The "survival" coefficients.  The length of `s` must be one less
-        than the length of `f`, and it must be at least 1.
+    f : array_like
+        The "fecundity" coefficients, has to be 1-D.
+    s : array_like
+        The "survival" coefficients, has to be 1-D.  The length of `s`
+        must be one less than the length of `f`, and it must be at least 1.

Returns
-------
-    L : ndarray, 2D
-        Returns a 2D numpy ndarray with shape `(n,n)`, where `n` is the
+    L : ndarray
+        Returns a 2-D ndarray of shape ``(n, n)``, where `n` is the
length of `f`.  The array is zero except for the first row,
-        which is `f`, and the first subdiagonal, which is `s`.
-        The data type of the array will be the data type of `f[0]+s[0]`.
+        which is `f`, and the first sub-diagonal, which is `s`.
+        The data-type of the array will be the data-type of ``f[0]+s[0]``.

Notes
-----

+    The Leslie matrix is used to model discrete-time, age-structured
+    population growth [1]_ [2]_. In a population with `n` age classes, two sets
+    of parameters define a Leslie matrix: the `n` "fecundity coefficients",
+    which give the number of offspring per-capita produced by each age
+    class, and the `n` - 1 "survival coefficients", which give the
+    per-capita survival rate of each age class.
+
+    References
+    ----------
+    .. [1] P. H. Leslie, On the use of matrices in certain population
+           mathematics, Biometrika, Vol. 33, No. 3, 183--212 (Nov. 1945)
+    .. [2] P. H. Leslie, Some further notes on the use of matrices in
+           population mathematics, Biometrika, Vol. 35, No. 3/4, 213--245
+           (Dec. 1948)
+
Examples
--------
>>> leslie([0.1, 2.0, 1.0, 0.1], [0.2, 0.8, 0.7])
@@ -360,6 +377,7 @@
[ 0.2,  0. ,  0. ,  0. ],
[ 0. ,  0.8,  0. ,  0. ],
[ 0. ,  0. ,  0.7,  0. ]])
+
"""
f = np.atleast_1d(f)
s = np.atleast_1d(s)
@@ -421,7 +439,8 @@
return np.concatenate(np.concatenate(o, axis=1), axis=1)

def block_diag(*arrs):
-    """Create a block diagonal matrix from the provided arrays.
+    """
+    Create a block diagonal matrix from provided arrays.

Given the inputs `A`, `B` and `C`, the output will have these
arrays arranged on the diagonal::
@@ -430,14 +449,11 @@
[0, B, 0],
[0, 0, C]]

-    If all the input arrays are square, the output is known as a
-    block diagonal matrix.
-
Parameters
----------
-    A, B, C, ... : array-like, up to 2D
-        Input arrays.  A 1D array or array-like sequence with length n is
-        treated as a 2D array with shape (1,n).
+    A, B, C, ... : array_like, up to 2-D
+        Input arrays.  A 1-D array or array_like sequence of length `n`is
+        treated as a 2-D array with shape ``(1,n)``.

Returns
-------
@@ -445,10 +461,10 @@
Array with `A`, `B`, `C`, ... on the diagonal.  `D` has the
same dtype as `A`.

-    References
-    ----------
-    .. [1] Wikipedia, "Block matrix",
-           http://en.wikipedia.org/wiki/Block_diagonal_matrix
+    Notes
+    -----
+    If all the input arrays are square, the output is known as a
+    block diagonal matrix.

Examples
--------
@@ -457,7 +473,7 @@
>>> B = [[3, 4, 5],
...      [6, 7, 8]]
>>> C = [[7]]
-    >>> print(block_diag(A, B, C))
+    >>> block_diag(A, B, C)
[[1 0 0 0 0 0]
[0 1 0 0 0 0]
[0 0 3 4 5 0]
@@ -490,35 +506,49 @@
return out

def companion(a):
-    """Create a companion matrix.
+    """
+    Create a companion matrix.

-    Create the companion matrix associated with the polynomial whose
+    Create the companion matrix [1]_ associated with the polynomial whose
coefficients are given in `a`.

Parameters
----------
-    a : array-like, 1D
-        Polynomial coefficients.  The length of `a` must be at least two,
-        and `a[0]` must not be zero.
+    a : array_like
+        1-D array of polynomial coefficients.  The length of `a` must be
+        at least two, and ``a[0]`` must not be zero.

Returns
-------
c : ndarray
-        A square ndarray with shape `(n-1, n-1)`, where `n` is the length
-        of `a`. The first row of `c` is `-a[1:]/a[0]`, and the first
-        subdiagonal is all ones.  The data type of the array is the same
-        as the data type of `1.0*a[0]`.
+        A square array of shape ``(n-1, n-1)``, where `n` is the length
+        of `a`.  The first row of `c` is ``-a[1:]/a[0]``, and the first
+        sub-diagonal is all ones.  The data-type of the array is the same
+        as the data-type of ``1.0*a[0]``.

+    Raises
+    ------
+    ValueError
+        If any of the following are true: a) ``a.ndim != 1``;
+        b) ``a.size < 2``; c) ``a[0] == 0``.
+
Notes
-----
-
+
+    References
+    ----------
+    .. [1] R. A. Horn & C. R. Johnson, *Matrix Analysis*.  Cambridge, UK:
+        Cambridge University Press, 1999, pp. 146-7.
+
Examples
--------
-    >>> companion([1, -10, 31, -30])
+    >>> from scipy.linalg import companion
+    >>> companion([1, -10, 31, -30])
array([[ 10., -31.,  30.],
[  1.,   0.,   0.],
[  0.,   1.,   0.]])
+
"""
a = np.atleast_1d(a)

```