[Scipysvn] r5265  trunk/scipy/optimize
scipysvn@scip...
scipysvn@scip...
Mon Dec 15 12:58:18 CST 2008
Author: charris
Date: 20081215 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 20081215 05:44:37 UTC (rev 5264)
+++ trunk/scipy/optimize/zeros.py 20081215 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 : onedimensional rootfinding
+ fixed_point : scalar fixedpoint finder
+ fsolve  ndimenstional rootfinding
 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  ndimenstional rootfinding

 brentq, brenth, ridder, bisect, newton  onedimensional rootfinding

 fixed_point  scalar fixedpoint 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 WijngaardenDekerBrent 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 WijngaardenDekerBrent 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 Scipysvn
mailing list