`scipy.optimize._zeros_py:bisect`

source: /scipy/optimize/_zeros_py.py :496

Signature

   def     bisect (    f    ,    a    ,    b    ,    args    =  ()   ,    xtol    =  2e-12   ,    rtol    =  8.881784197001252e-16   ,    maxiter    =  100   ,    full_output    =  False   ,    disp    =  True     )

Summary

Find root of a function within an interval using bisection.

Extended Summary

Basic bisection routine to find a root of the function f between the arguments a and b. f(a) and f(b) cannot have the same signs. Slow but sure.

Parameters

f : function: Python function returning a number. f must be continuous, and f(a) and f(b) must have opposite signs.
a : scalar: One end of the bracketing interval [a,b].
b : scalar: The other end of the bracketing interval [a,b].
xtol : number, optional: The computed root x0 will satisfy np.isclose(x, x0, atol=xtol, rtol=rtol), where x is the exact root. The parameter must be positive.
rtol : number, optional: The computed root x0 will satisfy np.isclose(x, x0, atol=xtol, rtol=rtol), where x is the exact root. The parameter cannot be smaller than its default value of 4*np.finfo(float).eps.
maxiter : int, optional: If convergence is not achieved in maxiter iterations, an 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, raise RuntimeError if the algorithm didn't converge. Otherwise, the convergence status is recorded in a RootResults return object.

Returns

root : float: Root 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.

Notes

As mentioned in the parameter documentation, the computed root x0 will satisfy np.isclose(x, x0, atol=xtol, rtol=rtol), where x is the exact root. In equation form, this terminating condition is abs(x - x0) <= xtol + rtol * abs(x0).

The default value xtol=2e-12 may lead to surprising behavior if one expects bisect to always compute roots with relative error near machine precision. Care should be taken to select xtol for the use case at hand. Setting xtol=5e-324, the smallest subnormal number, will ensure the highest level of accuracy. Larger values of xtol may be useful for saving function evaluations when a root is at or near zero in applications where the tiny absolute differences available between floating point numbers near zero are not meaningful.

Examples

def f(x):
    return (x**2 - 1)

✓

from scipy import optimize

✓

root = optimize.bisect(f, 0, 2)
root

✓

root = optimize.bisect(f, -2, 0)
root

✓

Aliases

scipy.optimize.bisect