# [Scipy-svn] r5265 - trunk/scipy/optimize

scipy-svn@scip... scipy-svn@scip...
Mon Dec 15 12:58:18 CST 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.
+    --------
+        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.
-
-
-      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
-    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.
-
-
--------
-
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.
-
-
+    --------
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)

```