`scipy.optimize._bracket:_bracket_root`

source: /scipy/optimize/_bracket.py :72

Signature

   def     _bracket_root (    func    ,    xl0    ,    xr0    =  None   ,  * ,     xmin    =  None   ,    xmax    =  None   ,    factor    =  None   ,    args    =  ()   ,    maxiter    =  1000     )

Summary

Bracket the root of a monotonic scalar function of one variable

Extended Summary

This function works elementwise when xl0, xr0, xmin, xmax, factor, and the elements of args are broadcastable arrays.

Parameters

func : callable

The function for which the root is to be bracketed. The signature must be

func(x: ndarray, *args) -> ndarray

where each element of x is a finite real and args is a tuple, which may contain an arbitrary number of arrays that are broadcastable with x. func must be an elementwise function: each element func(x)[i] must equal func(x[i]) for all indices i.

xl0, xr0: float array_like

Starting guess of bracket, which need not contain a root. If xr0 is not provided, xr0 = xl0 + 1. Must be broadcastable with one another.

xmin, xmax : float array_like, optional

Minimum and maximum allowable endpoints of the bracket, inclusive. Must be broadcastable with xl0 and xr0.

factor : float array_like, default: 2

The factor used to grow the bracket. See notes for details.

args : tuple, optional

Additional positional arguments to be passed to func. Must be arrays broadcastable with xl0, xr0, xmin, and xmax. If the callable to be bracketed requires arguments that are not broadcastable with these arrays, wrap that callable with func such that func accepts only x and broadcastable arrays.

maxiter : int, optional

The maximum number of iterations of the algorithm to perform.

Returns

res : _RichResult

An instance of scipy._lib._util._RichResult with the following attributes. The descriptions are written as though the values will be scalars; however, if func returns an array, the outputs will be arrays of the same shape.

xl,xr: xl, xr
fl,fr: fl, fr
nfev: nfev
nit: nit
status: status
success: success

Notes

This function generalizes an algorithm found in pieces throughout scipy.stats. The strategy is to iteratively grow the bracket (l, r) until func(l) < 0 < func(r). The bracket grows to the left as follows.

If xmin is not provided, the distance between xl0 and l is iteratively increased by factor.
If xmin is provided, the distance between xmin and l is iteratively decreased by factor. Note that this also increases the bracket size.

Growth of the bracket to the right is analogous.

Growth of the bracket in one direction stops when the endpoint is no longer finite, the function value at the endpoint is no longer finite, or the endpoint reaches its limiting value (xmin or xmax). Iteration terminates when the bracket stops growing in both directions, the bracket surrounds the root, or a root is found (accidentally).

If two brackets are found - that is, a bracket is found on both sides in the same iteration, the smaller of the two is returned. If roots of the function are found, both l and r are set to the leftmost root.

Aliases

scipy.optimize._bracket._bracket_root