[Scipy-svn] r5060 - trunk/scipy/sparse/linalg/isolve
scipy-svn at scipy.org
scipy-svn at scipy.org
Tue Nov 11 21:17:33 EST 2008
Author: wnbell
Date: 2008-11-11 20:17:26 -0600 (Tue, 11 Nov 2008)
New Revision: 5060
Modified:
trunk/scipy/sparse/linalg/isolve/iterative.py
trunk/scipy/sparse/linalg/isolve/minres.py
Log:
updated iterative solver docstrings
resolves ticket #652
Modified: trunk/scipy/sparse/linalg/isolve/iterative.py
===================================================================
--- trunk/scipy/sparse/linalg/isolve/iterative.py 2008-11-11 09:03:27 UTC (rev 5059)
+++ trunk/scipy/sparse/linalg/isolve/iterative.py 2008-11-12 02:17:26 UTC (rev 5060)
@@ -10,41 +10,67 @@
_type_conv = {'f':'s', 'd':'d', 'F':'c', 'D':'z'}
-def bicg(A, b, x0=None, tol=1e-5, maxiter=None, xtype=None, M=None, callback=None):
- """Use BIConjugate Gradient iteration to solve A x = b
- Inputs:
+# Part of the docstring common to all iterative solvers
+common_doc = \
+"""
+Parameters
+----------
+A : {sparse matrix, dense matrix, LinearOperator}
+ The N-by-N matrix of the linear system.
+b : {array, matrix}
+ Right hand side of the linear system. Has shape (N,) or (N,1).
- A -- An array or an object with matvec(x) and rmatvec(x) methods
- to represent A * x and A^H * x respectively. May also have
- psolve(b) and rpsolve(b) methods for representing solutions
- to the preconditioning equations M * x = b and
- M^H * x = b respectively.
- b -- An n-length vector
+Optional Parameters
+-------------------
+x0 : {array, matrix}
+ Starting guess for the solution.
+tol : float
+ Relative tolerance to achieve before terminating.
+maxiter : integer
+ Maximum number of iterations. Iteration will stop after maxiter
+ steps even if the specified tolerance has not been achieved.
+M : {sparse matrix, dense matrix, LinearOperator}
+ Preconditioner for A. The preconditioner should approximate the
+ inverse of A. Effective preconditioning dramatically improves the
+ rate of convergence, which implies that fewer iterations are needed
+ to reach a given error tolerance.
+callback : function
+ User-supplied function to call after each iteration. It is called
+ as callback(xk), where xk is the current solution vector.
- Outputs:
+Outputs
+-------
+x : {array, matrix}
+ The converged solution.
+info : integer
+ Provides convergence information:
+ 0 : successful exit
+ >0 : convergence to tolerance not achieved, number of iterations
+ <0 : illegal input or breakdown
- x -- The converged solution
- info -- output result
- 0 : successful exit
- >0 : convergence to tolerance not achieved, number of iterations
- <0 : illegal input or breakdown
+Deprecated Parameters
+----------------------
+xtype : {'f','d','F','D'}
+ The type of the result. If None, then it will be determined from
+ A.dtype.char and b. If A does not have a typecode method then it
+ will compute A.matvec(x0) to get a typecode. To save the extra
+ computation when A does not have a typecode attribute use xtype=0
+ for the same type as b or use xtype='f','d','F',or 'D'.
+ This parameter has been superceeded by LinearOperator.
+"""
- Optional Inputs:
- x0 -- (0) default starting guess.
- tol -- (1e-5) relative tolerance to achieve
- maxiter -- (10*n) maximum number of iterations
- xtype -- The type of the result. If None, then it will be
- determined from A.dtype.char and b. If A does not have a
- typecode method then it will compute A.matvec(x0) to get a
- typecode. To save the extra computation when A does not
- have a typecode attribute use xtype=0 for the same type as
- b or use xtype='f','d','F',or 'D'
- callback -- an optional user-supplied function to call after each
- iteration. It is called as callback(xk), where xk is the
- current parameter vector.
- """
+def set_docstring(header, footer):
+ def combine(fn):
+ fn.__doc__ = header + '\n' + common_doc + '\n' + footer
+ return fn
+ return combine
+
+
+
+ at set_docstring('Use BIConjugate Gradient iteration to solve A x = b','')
+def bicg(A, b, x0=None, tol=1e-5, maxiter=None, xtype=None, M=None, callback=None):
A,M,x,b,postprocess = make_system(A,M,x0,b,xtype)
n = len(b)
@@ -104,41 +130,8 @@
return postprocess(x), info
-
+ at set_docstring('Use BIConjugate Gradient STABilized iteration to solve A x = b','')
def bicgstab(A, b, x0=None, tol=1e-5, maxiter=None, xtype=None, M=None, callback=None):
- """Use BIConjugate Gradient STABilized iteration to solve A x = b
-
- Inputs:
-
- A -- An array or an object with a matvec(x) method
- to represent A * x. May also have a psolve(b) methods for
- representing solution to the preconditioning equation
- M * x = b.
- b -- An n-length vector
-
- Outputs:
-
- x -- The converged solution
- info -- output result
- 0 : successful exit
- >0 : convergence to tolerance not achieved, number of iterations
- <0 : illegal input or breakdown
-
- Optional Inputs:
-
- x0 -- (0) default starting guess.
- tol -- (1e-5) relative tolerance to achieve
- maxiter -- (10*n) maximum number of iterations
- xtype -- The type of the result. If None, then it will be
- determined from A.dtype.char and b. If A does not have a
- typecode method then it will compute A.matvec(x0) to get a
- typecode. To save the extra computation when A does not
- have a typecode attribute use xtype=0 for the same type as
- b or use xtype='f','d','F',or 'D'
- callback -- an optional user-supplied function to call after each
- iteration. It is called as callback(xk), where xk is the
- current parameter vector.
- """
A,M,x,b,postprocess = make_system(A,M,x0,b,xtype)
n = len(b)
@@ -199,42 +192,8 @@
return postprocess(x), info
-
+ at set_docstring('Use Conjugate Gradient iteration to solve A x = b','')
def cg(A, b, x0=None, tol=1e-5, maxiter=None, xtype=None, M=None, callback=None):
- """Use Conjugate Gradient iteration to solve A x = b (A^H = A)
-
- Inputs:
-
- A -- An array or an object with a matvec(x) method
- to represent A * x. May also have a psolve(b) methods for
- representing solution to the preconditioning equation
- M * x = b.
- b -- An n-length vector
-
-
- Outputs:
-
- x -- The converged solution
- info -- output result
- 0 : successful exit
- >0 : convergence to tolerance not achieved, number of iterations
- <0 : illegal input or breakdown
-
- Optional Inputs:
-
- x0 -- (0) default starting guess.
- tol -- (1e-5) relative tolerance to achieve
- maxiter -- (10*n) maximum number of iterations
- xtype -- The type of the result. If None, then it will be
- determined from A.dtype.char and b. If A does not have a
- typecode method then it will compute A.matvec(x0) to get a
- typecode. To save the extra computation when A does not
- have a typecode attribute use xtype=0 for the same type as
- b or use xtype='f','d','F',or 'D'
- callback -- an optional user-supplied function to call after each
- iteration. It is called as callback(xk), where xk is the
- current parameter vector.
- """
A,M,x,b,postprocess = make_system(A,M,x0,b,xtype)
n = len(b)
@@ -291,41 +250,8 @@
return postprocess(x), info
+ at set_docstring('Use Conjugate Gradient Squared iteration to solve A x = b','')
def cgs(A, b, x0=None, tol=1e-5, maxiter=None, xtype=None, M=None, callback=None):
- """Use Conjugate Gradient Squared iteration to solve A x = b
-
- Inputs:
-
- A -- An array or an object with a matvec(x) method
- to represent A * x. May also have a psolve(b) methods for
- representing solution to the preconditioning equation
- M * x = b.
- b -- An n-length vector
-
-
- Outputs:
-
- x -- The converged solution
- info -- output result
- 0 : successful exit
- >0 : convergence to tolerance not achieved, number of iterations
- <0 : illegal input or breakdown
-
- Optional Inputs:
-
- x0 -- (0) default starting guess.
- tol -- (1e-5) relative tolerance to achieve
- maxiter -- (10*n) maximum number of iterations
- xtype -- The type of the result. If None, then it will be
- determined from A.dtype.char and b. If A does not have a
- typecode method then it will compute A.matvec(x0) to get a
- typecode. To save the extra computation when A does not
- have a typecode attribute use xtype=0 for the same type as
- b or use xtype='f','d','F',or 'D'
- callback -- an optional user-supplied function to call after each
- iteration. It is called as callback(xk), where xk is the
- current parameter vector.
- """
A,M,x,b,postprocess = make_system(A,M,x0,b,xtype)
n = len(b)
@@ -379,44 +305,63 @@
info = iter_
return postprocess(x), info
+
-
def gmres(A, b, x0=None, tol=1e-5, restrt=20, maxiter=None, xtype=None, M=None, callback=None):
"""Use Generalized Minimal RESidual iteration to solve A x = b
-
- Inputs:
-
- A -- An array or an object with a matvec(x) method
- to represent A * x. May also have a psolve(b) methods for
- representing solution to the preconditioning equation
- M * x = b.
- b -- An n-length vector
-
-
- Outputs:
-
- x -- The converged solution
- info -- output result
+
+ Parameters
+ ----------
+ A : {sparse matrix, dense matrix, LinearOperator}
+ The N-by-N matrix of the linear system.
+ b : {array, matrix}
+ Right hand side of the linear system. Has shape (N,) or (N,1).
+
+ Optional Parameters
+ -------------------
+ x0 : {array, matrix}
+ Starting guess for the solution.
+ tol : float
+ Relative tolerance to achieve before terminating.
+ restrt : integer
+ Number of iterations between restarts. Larger values increase
+ iteration cost, but may be necessary for convergence.
+ maxiter : integer
+ Maximum number of iterations. Iteration will stop after maxiter
+ steps even if the specified tolerance has not been achieved.
+ M : {sparse matrix, dense matrix, LinearOperator}
+ Preconditioner for A. The preconditioner should approximate the
+ inverse of A. Effective preconditioning dramatically improves the
+ rate of convergence, which implies that fewer iterations are needed
+ to reach a given error tolerance.
+ callback : function
+ User-supplied function to call after each iteration. It is called
+ as callback(rk), where rk is the current residual vector.
+
+ Outputs
+ -------
+ x : {array, matrix}
+ The converged solution.
+ info : integer
+ Provides convergence information:
0 : successful exit
>0 : convergence to tolerance not achieved, number of iterations
<0 : illegal input or breakdown
-
- Optional Inputs:
-
- x0 -- (0) default starting guess.
- tol -- (1e-5) relative tolerance to achieve
- restrt -- (10) When to restart (change this to get faster performance -- but
- may not converge).
- maxiter -- (10*n) maximum number of iterations
- xtype -- The type of the result. If None, then it will be
- determined from A.dtype.char and b. If A does not have a
- typecode method then it will compute A.matvec(x0) to get a
- typecode. To save the extra computation when A does not
- have a typecode attribute use xtype=0 for the same type as
- b or use xtype='f','d','F',or 'D'
- callback -- an optional user-supplied function to call after each
- iteration. It is called as callback(rk), where rk is the
- the current relative residual
+
+ See Also
+ --------
+ LinearOperator
+
+ Deprecated Parameters
+ ---------------------
+ xtype : {'f','d','F','D'}
+ The type of the result. If None, then it will be determined from
+ A.dtype.char and b. If A does not have a typecode method then it
+ will compute A.matvec(x0) to get a typecode. To save the extra
+ computation when A does not have a typecode attribute use xtype=0
+ for the same type as b or use xtype='f','d','F',or 'D'.
+ This parameter has been superceeded by LinearOperator.
+
"""
A,M,x,b,postprocess = make_system(A,M,x0,b,xtype)
@@ -499,38 +444,56 @@
def qmr(A, b, x0=None, tol=1e-5, maxiter=None, xtype=None, M1=None, M2=None, callback=None):
"""Use Quasi-Minimal Residual iteration to solve A x = b
- Inputs:
-
- A -- An array or an object with matvec(x) and rmatvec(x) methods
- to represent A * x and A^H * x respectively. May also have
- psolve(b,<which>) and rpsolve(b,<which>) methods for
- representing solutions to the preconditioning equations
- M * x = b and M^H * x = b respectively. The <which> argument
- may be given to specify 'left' or 'right' preconditioning.
- b -- An n-length vector
-
- Outputs:
-
- x -- The converged solution
- info -- output result
+ Parameters
+ ----------
+ A : {sparse matrix, dense matrix, LinearOperator}
+ The N-by-N matrix of the linear system.
+ b : {array, matrix}
+ Right hand side of the linear system. Has shape (N,) or (N,1).
+
+ Optional Parameters
+ -------------------
+ x0 : {array, matrix}
+ Starting guess for the solution.
+ tol : float
+ Relative tolerance to achieve before terminating.
+ maxiter : integer
+ Maximum number of iterations. Iteration will stop after maxiter
+ steps even if the specified tolerance has not been achieved.
+ M1 : {sparse matrix, dense matrix, LinearOperator}
+ Left preconditioner for A.
+ M2 : {sparse matrix, dense matrix, LinearOperator}
+ Right preconditioner for A. Used together with the left
+ preconditioner M1. The matrix M1*A*M2 should have better
+ conditioned than A alone.
+ callback : function
+ User-supplied function to call after each iteration. It is called
+ as callback(xk), where xk is the current solution vector.
+
+ Outputs
+ -------
+ x : {array, matrix}
+ The converged solution.
+ info : integer
+ Provides convergence information:
0 : successful exit
>0 : convergence to tolerance not achieved, number of iterations
<0 : illegal input or breakdown
-
- Optional Inputs:
-
- x0 -- (0) default starting guess.
- tol -- (1e-5) relative tolerance to achieve
- maxiter -- (10*n) maximum number of iterations
- xtype -- The type of the result. If None, then it will be
- determined from A.dtype.char and b. If A does not have a
- typecode method then it will compute A.matvec(x0) to get a
- typecode. To save the extra computation when A does not
- have a typecode attribute use xtype=0 for the same type as
- b or use xtype='f','d','F',or 'D'
- callback -- an optional user-supplied function to call after each
- iteration. It is called as callback(xk), where xk is the
- current parameter vector.
+
+ See Also
+ --------
+ LinearOperator
+
+ Deprecated Parameters
+ ---------------------
+ xtype : {'f','d','F','D'}
+ The type of the result. If None, then it will be determined from
+ A.dtype.char and b. If A does not have a typecode method then it
+ will compute A.matvec(x0) to get a typecode. To save the extra
+ computation when A does not have a typecode attribute use xtype=0
+ for the same type as b or use xtype='f','d','F',or 'D'.
+ This parameter has been superceeded by LinearOperator.
+
"""
A_ = A
A,M,x,b,postprocess = make_system(A,None,x0,b,xtype)
Modified: trunk/scipy/sparse/linalg/isolve/minres.py
===================================================================
--- trunk/scipy/sparse/linalg/isolve/minres.py 2008-11-11 09:03:27 UTC (rev 5059)
+++ trunk/scipy/sparse/linalg/isolve/minres.py 2008-11-12 02:17:26 UTC (rev 5060)
@@ -2,35 +2,40 @@
from numpy.linalg import norm
from utils import make_system
+from iterative import set_docstring
__all__ = ['minres']
-def minres(A, b, x0=None, shift=0.0, tol=1e-5, maxiter=None, xtype=None,
- M=None, callback=None, show=False, check=False):
- """Use the Minimum Residual Method (MINRES) to solve Ax=b
+
+header = \
+"""Use MINimum RESidual iteration to solve Ax=b
- MINRES minimizes norm(A*x - b) for the symmetric matrix A. Unlike
- the Conjugate Gradient method, A can be indefinite or singular.
+MINRES minimizes norm(A*x - b) for the symmetric matrix A. Unlike
+the Conjugate Gradient method, A can be indefinite or singular.
- If shift != 0 then the method solves (A - shift*I)x = b
+If shift != 0 then the method solves (A - shift*I)x = b
+"""
+footer = \
+"""
+Notes
+-----
+THIS FUNCTION IS EXPERIMENTAL AND SUBJECT TO CHANGE!
- Parameters
- ==========
- TODO
+References
+----------
+Solution of sparse indefinite systems of linear equations,
+ C. C. Paige and M. A. Saunders (1975),
+ SIAM J. Numer. Anal. 12(4), pp. 617-629.
+ http://www.stanford.edu/group/SOL/software/minres.html
- References
- ==========
+This file is a translation of the following MATLAB implementation:
+ http://www.stanford.edu/group/SOL/software/minres/matlab/
+"""
- Solution of sparse indefinite systems of linear equations,
- C. C. Paige and M. A. Saunders (1975),
- SIAM J. Numer. Anal. 12(4), pp. 617-629.
- http://www.stanford.edu/group/SOL/software/minres.html
-
- This file is a translation of the following MATLAB implementation:
- http://www.stanford.edu/group/SOL/software/minres/matlab/
-
- """
+ at set_docstring(header,footer)
+def minres(A, b, x0=None, shift=0.0, tol=1e-5, maxiter=None, xtype=None,
+ M=None, callback=None, show=False, check=False):
A,M,x,b,postprocess = make_system(A,M,x0,b,xtype)
matvec = A.matvec
More information about the Scipy-svn
mailing list