`scipy.optimize._bracket:_bracket_root`

source: build-install/usr/lib/python3.14/site-packages/scipy/optimize/_bracket.py:78

Signature

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

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.

kwargs : dict of str:array_like, optional

Additional keyword arguments to be passed to func. See args.

maxiter : int, optional

The maximum number of iterations of the algorithm to perform.

preserve_shape : bool, default: False

Whether calls to func must preserve the broadcasted shape of the arguments to _bracket_root. See bracket_root documentation.

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

The lower and upper ends of the bracket, if the algorithm terminated successfully.

fl,fr

The function value at the lower and upper ends of the bracket.

nfev

The number of function evaluations required to find the bracket. This is distinct from the number of times func is called because the function may evaluated at multiple points in a single call.

nit

The number of iterations of the algorithm that were performed.

status

An integer representing the exit status of the algorithm.

0The algorithm produced a valid bracket.
-1The bracket expanded to the allowable limits without finding a bracket.
-2The maximum number of iterations was reached.
-3A non-finite value was encountered.
-4Iteration was terminated by callback.
-5: The initial bracket does not satisfy xmin <= xl0 < xr0 < xmax.
1The algorithm is proceeding normally (in callback only).
2A bracket was found in the opposite search direction (in callback only).

success

True when the algorithm terminated successfully (status 0).

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