[Scipy-svn] r5265 - trunk/scipy/optimize
scipy-svn at scipy.org
scipy-svn at scipy.org
Mon Dec 15 13:58:18 EST 2008
Author: charris
Date: 2008-12-15 12:58:14 -0600 (Mon, 15 Dec 2008)
New Revision: 5265
Modified:
trunk/scipy/optimize/zeros.py
Log:
Make disp=True the default.
Reformat and clean up documentation. See Also still needs work.
Modified: trunk/scipy/optimize/zeros.py
===================================================================
--- trunk/scipy/optimize/zeros.py 2008-12-15 05:44:37 UTC (rev 5264)
+++ trunk/scipy/optimize/zeros.py 2008-12-15 18:58:14 UTC (rev 5265)
@@ -39,57 +39,53 @@
def bisect(f, a, b, args=(),
xtol=_xtol, rtol=_rtol, maxiter=_iter,
- full_output=False, disp=False):
- """Find root of f in [a,b]
+ full_output=False, disp=True):
+ """Find root of f in [a,b].
- Basic bisection routine to find a zero of the function
- f between the arguments a and b. f(a) and f(b) can not
- have the same signs. Slow but sure.
+ Basic bisection routine to find a zero of the function f between the
+ arguments a and b. f(a) and f(b) can not have the same signs. Slow but
+ sure.
- f : Python function returning a number.
+ Parameters
+ ----------
+ f : function
+ Python function returning a number. f must be continuous, and f(a) and
+ f(b) must have opposite signs.
+ a : number
+ One end of the bracketing interval [a,b].
+ b : number
+ The other end of the bracketing interval [a,b].
+ xtol : number, optional
+ The routine converges when a root is known to lie within xtol of the
+ value return. Should be >= 0. The routine modifies this to take into
+ account the relative precision of doubles.
+ maxiter : number, optional
+ if convergence is not achieved in maxiter iterations, and error is
+ raised. Must be >= 0.
+ args : tuple, optional
+ containing extra arguments for the function `f`.
+ `f` is called by ``apply(f, (x)+args)``.
+ full_output : bool, optional
+ If `full_output` is False, the root is returned. If `full_output` is
+ True, the return value is ``(x, r)``, where `x` is the root, and `r` is
+ a RootResults object.
+ disp : {True, bool} optional
+ If True, raise RuntimeError if the algorithm didn't converge.
- a : Number, one end of the bracketing interval.
+ Returns
+ -------
+ x0 : float
+ Zero of `f` between `a` and `b`.
+ r : RootResults (present if ``full_output = True``)
+ Object containing information about the convergence. In particular,
+ ``r.converged`` is True if the routine converged.
- b : Number, the other end of the bracketing interval.
+ See Also
+ --------
+ brentq, brenth, bisect, newton : one-dimensional root-finding
+ fixed_point : scalar fixed-point finder
+ fsolve -- n-dimenstional root-finding
- xtol : Number, the routine converges when a root is known
- to lie within xtol of the value return. Should be >= 0.
- The routine modifies this to take into account the relative
- precision of doubles.
-
- maxiter : Number, if convergence is not achieved in
- maxiter iterations, and error is raised. Must be
- >= 0.
-
- args : tuple containing extra arguments for the function f.
- f is called by apply(f,(x)+args).
-
- If full_output is False, the root is returned.
-
- If full_output is True, the return value is (x, r), where x
- is the root, and r is a RootResults object containing information
- about the convergence. In particular, r.converged is True if the
- the routine converged.
-
- See also:
-
- fmin, fmin_powell, fmin_cg,
- fmin_bfgs, fmin_ncg -- multivariate local optimizers
- leastsq -- nonlinear least squares minimizer
-
- fmin_l_bfgs_b, fmin_tnc,
- fmin_cobyla -- constrained multivariate optimizers
-
- anneal, brute -- global optimizers
-
- fminbound, brent, golden, bracket -- local scalar minimizers
-
- fsolve -- n-dimenstional root-finding
-
- brentq, brenth, ridder, bisect, newton -- one-dimensional root-finding
-
- fixed_point -- scalar fixed-point finder
-
"""
if type(args) != type(()) :
args = (args,)
@@ -98,38 +94,35 @@
def ridder(f, a, b, args=(),
xtol=_xtol, rtol=_rtol, maxiter=_iter,
- full_output=False, disp=False):
+ full_output=False, disp=True):
"""
Find a root of a function in an interval.
Parameters
----------
f : function
- Python function returning a number.
- `f` must be continuous, and `f(a)` and `f(b)` must have opposite signs.
+ Python function returning a number. f must be continuous, and f(a) and
+ f(b) must have opposite signs.
a : number
- one end of the bracketing interval `[a,b]`
+ One end of the bracketing interval [a,b].
b : number
- the other end of the bracketing interval `[a,b]`
+ The other end of the bracketing interval [a,b].
xtol : number, optional
- the routine converges when a root is known
- to lie within xtol of the value return. Should be >= 0.
- The routine modifies this to take into account the relative
- precision of doubles.
+ The routine converges when a root is known to lie within xtol of the
+ value return. Should be >= 0. The routine modifies this to take into
+ account the relative precision of doubles.
maxiter : number, optional
- if convergence is not achieved in
- maxiter iterations, and error is raised.
- Must be >= 0.
+ if convergence is not achieved in maxiter iterations, and error is
+ raised. Must be >= 0.
args : tuple, optional
containing extra arguments for the function `f`.
`f` is called by ``apply(f, (x)+args)``.
full_output : bool, optional
- If `full_output` is False, the root is returned.
- If `full_output` is True, the return value is ``(x, r)``, where `x`
- is the root, and `r` is a RootResults object.
- disp : bool, optional
- If True, print a message to ``stderr`` if the algorithm didn't
- converge.
+ If `full_output` is False, the root is returned. If `full_output` is
+ True, the return value is ``(x, r)``, where `x` is the root, and `r` is
+ a RootResults object.
+ disp : {True, bool} optional
+ If True, raise RuntimeError if the algorithm didn't converge.
Returns
-------
@@ -146,14 +139,14 @@
Notes
-----
- Uses [Ridders1979]_ method to find a zero of the function `f` between
- the arguments `a` and `b`. Ridders' method is faster than bisection,
- but not generaly as fast as the brent rountines. [Ridders1979]_ provides
- the classic description and source of the algorithm. A description can
- also be found in may be found in any recent edition of Numerical Recipes.
+ Uses [Ridders1979]_ method to find a zero of the function `f` between the
+ arguments `a` and `b`. Ridders' method is faster than bisection, but not
+ generaly as fast as the brent rountines. [Ridders1979]_ provides the
+ classic description and source of the algorithm. A description can also be
+ found in may be found in any recent edition of Numerical Recipes.
- The routine used here diverges slightly from standard presentations
- in order to be a bit more careful of tolerance.
+ The routine used here diverges slightly from standard presentations in
+ order to be a bit more careful of tolerance.
References
----------
@@ -170,73 +163,66 @@
def brentq(f, a, b, args=(),
xtol=_xtol, rtol=_rtol, maxiter=_iter,
- full_output=False, disp=False):
+ full_output=False, disp=True):
"""
Find a root of a function in given interval.
- Return float, a zero of `f` between `a` and `b`.
- `f` must be a continuous function, and
- [a,b] must be a sign changing interval.
+ Return float, a zero of `f` between `a` and `b`. `f` must be a continuous
+ function, and [a,b] must be a sign changing interval.
Description:
- Uses the classic Brent (1973) method to find a zero
- of the function `f` on the sign changing interval [a , b].
- Generally considered the best of the rootfinding routines here.
- It is a safe version of the secant method that uses inverse
- quadratic extrapolation.
- Brent's method combines root bracketing, interval bisection,
- and inverse quadratic interpolation.
- It is sometimes known as the van Wijngaarden-Deker-Brent method.
- Brent (1973) claims convergence is guaranteed for functions
- computable within [a,b].
+ Uses the classic Brent (1973) method to find a zero of the function `f` on
+ the sign changing interval [a , b]. Generally considered the best of the
+ rootfinding routines here. It is a safe version of the secant method that
+ uses inverse quadratic extrapolation. Brent's method combines root
+ bracketing, interval bisection, and inverse quadratic interpolation. It is
+ sometimes known as the van Wijngaarden-Deker-Brent method. Brent (1973)
+ claims convergence is guaranteed for functions computable within [a,b].
- [Brent1973]_ provides the classic description of the algorithm.
- Another description is in any recent edition of Numerical Recipes,
- including [PressEtal1992]_.
- Another description is at http://mathworld.wolfram.com/BrentsMethod.html.
- It should be easy to understand the algorithm just by reading our code.
- Our code diverges a bit from standard presentations:
- we choose a different formula for the extrapolation step.
+ [Brent1973]_ provides the classic description of the algorithm. Another
+ description is in any recent edition of Numerical Recipes, including
+ [PressEtal1992]_. Another description is at
+ http://mathworld.wolfram.com/BrentsMethod.html. It should be easy to
+ understand the algorithm just by reading our code. Our code diverges a bit
+ from standard presentations: we choose a different formula for the
+ extrapolation step.
-
Parameters
----------
+ f : function
+ Python function returning a number. f must be continuous, and f(a) and
+ f(b) must have opposite signs.
+ a : number
+ One end of the bracketing interval [a,b].
+ b : number
+ The other end of the bracketing interval [a,b].
+ xtol : number, optional
+ The routine converges when a root is known to lie within xtol of the
+ value return. Should be >= 0. The routine modifies this to take into
+ account the relative precision of doubles.
+ maxiter : number, optional
+ if convergence is not achieved in maxiter iterations, and error is
+ raised. Must be >= 0.
+ args : tuple, optional
+ containing extra arguments for the function `f`.
+ `f` is called by ``apply(f, (x)+args)``.
+ full_output : bool, optional
+ If `full_output` is False, the root is returned. If `full_output` is
+ True, the return value is ``(x, r)``, where `x` is the root, and `r` is
+ a RootResults object.
+ disp : {True, bool} optional
+ If True, raise RuntimeError if the algorithm didn't converge.
- `f` : function
- Python function returning a number.
+ Returns
+ -------
+ x0 : float
+ Zero of `f` between `a` and `b`.
+ r : RootResults (present if ``full_output = True``)
+ Object containing information about the convergence. In particular,
+ ``r.converged`` is True if the routine converged.
- `a` : number
- one end of the bracketing interval [a,b]
-
- `b` : number
- the other end of the bracketing interval [a,b]
-
- `xtol` : number
- the routine converges when a root is known
- to lie within xtol of the value return. Should be >= 0.
- The routine modifies this to take into account the relative
- precision of doubles.
-
- `maxiter` : number
- if convergence is not achieved in
- maxiter iterations, and error is raised.
- Must be >= 0.
-
- `args` : tuple
- containing extra arguments for the function `f`.
- `f` is called by apply(f,(x)+args).
-
- `full_output` : bool
- If `full_output` is False, the root is returned.
- If `full_output` is True, the return value is (x, r), where x
- is the root, and r is a RootResults object containing information
- about the convergence. In particular, r.converged is True if the
- the routine converged.
-
-
See Also
--------
-
multivariate local optimizers
`fmin`, `fmin_powell`, `fmin_cg`, `fmin_bfgs`, `fmin_ncg`
nonlinear least squares minimizer
@@ -257,8 +243,7 @@
Notes
-----
- `f` must be continuous.
- f(a) and f(b) must have opposite signs.
+ f must be continuous. f(a) and f(b) must have opposite signs.
.. [Brent1973]
@@ -280,45 +265,53 @@
def brenth(f, a, b, args=(),
xtol=_xtol, rtol=_rtol, maxiter=_iter,
- full_output=False, disp=False):
- """Find root of f in [a,b]
+ full_output=False, disp=True):
+ """Find root of f in [a,b].
- A variation on the classic Brent routine to find a zero
- of the function f between the arguments a and b that uses
- hyperbolic extrapolation instead of inverse quadratic
- extrapolation. There was a paper back in the 1980's ...
- f(a) and f(b) can not have the same signs. Generally on a
- par with the brent routine, but not as heavily tested.
- It is a safe version of the secant method that uses hyperbolic
- extrapolation. The version here is by Chuck Harris.
+ A variation on the classic Brent routine to find a zero of the function f
+ between the arguments a and b that uses hyperbolic extrapolation instead of
+ inverse quadratic extrapolation. There was a paper back in the 1980's ...
+ f(a) and f(b) can not have the same signs. Generally on a par with the
+ brent routine, but not as heavily tested. It is a safe version of the
+ secant method that uses hyperbolic extrapolation. The version here is by
+ Chuck Harris.
- f : Python function returning a number.
+ Parameters
+ ----------
+ f : function
+ Python function returning a number. f must be continuous, and f(a) and
+ f(b) must have opposite signs.
+ a : number
+ One end of the bracketing interval [a,b].
+ b : number
+ The other end of the bracketing interval [a,b].
+ xtol : number, optional
+ The routine converges when a root is known to lie within xtol of the
+ value return. Should be >= 0. The routine modifies this to take into
+ account the relative precision of doubles.
+ maxiter : number, optional
+ if convergence is not achieved in maxiter iterations, and error is
+ raised. Must be >= 0.
+ args : tuple, optional
+ containing extra arguments for the function `f`.
+ `f` is called by ``apply(f, (x)+args)``.
+ full_output : bool, optional
+ If `full_output` is False, the root is returned. If `full_output` is
+ True, the return value is ``(x, r)``, where `x` is the root, and `r` is
+ a RootResults object.
+ disp : {True, bool} optional
+ If True, raise RuntimeError if the algorithm didn't converge.
- a : Number, one end of the bracketing interval.
+ Returns
+ -------
+ x0 : float
+ Zero of `f` between `a` and `b`.
+ r : RootResults (present if ``full_output = True``)
+ Object containing information about the convergence. In particular,
+ ``r.converged`` is True if the routine converged.
- b : Number, the other end of the bracketing interval.
-
- xtol : Number, the routine converges when a root is known
- to lie within xtol of the value return. Should be >= 0.
- The routine modifies this to take into account the relative
- precision of doubles.
-
- maxiter : Number, if convergence is not achieved in
- maxiter iterations, and error is raised. Must be
- >= 0.
-
- args : tuple containing extra arguments for the function f.
- f is called by apply(f,(x)+args).
-
- If full_output is False, the root is returned.
-
- If full_output is True, the return value is (x, r), where x
- is the root, and r is a RootResults object containing information
- about the convergence. In particular, r.converged is True if the
- the routine converged.
-
- See also:
-
+ See Also
+ --------
fmin, fmin_powell, fmin_cg,
fmin_bfgs, fmin_ncg -- multivariate local optimizers
leastsq -- nonlinear least squares minimizer
@@ -339,5 +332,5 @@
"""
if type(args) != type(()) :
args = (args,)
- r = _zeros._brenth(f,a,b,xtol,maxiter,args,full_output,disp)
+ r = _zeros._brenth(f,a, b, xtol, maxiter, args, full_output, disp)
return results_c(full_output, r)
More information about the Scipy-svn
mailing list