`scipy.optimize._bracket:_bracket_minimum`

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

Signature

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

Summary

Bracket the minimum of a unimodal scalar function of one variable

Extended Summary

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

Parameters

func : callable

The function for which the minimum 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.

xm0: float array_like

Starting guess for middle point of bracket.

xl0, xr0: float array_like, optional

Starting guesses for left and right endpoints of the bracket. Must be broadcastable with one another and with xm0.

xmin, xmax : float array_like, optional

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

factor : float array_like, optional

Controls expansion of bracket endpoint in downhill direction. Works differently in the cases where a limit is set in the downhill direction with xmax or xmin. See Notes.

args : tuple, optional

Additional positional arguments to be passed to func. Must be arrays broadcastable with xl0, xm0, 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 f. See args.

maxiter : int, optional

The maximum number of iterations of the algorithm to perform. The number of function evaluations is three greater than the number of iterations.

preserve_shape : bool, default: False

Whether calls to func must preserve the broadcasted shape of the arguments to _bracket_minimum. See bracket_minimum 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,xm,xr

The left, middle, and right points of the bracket, if the algorithm terminated successfully.

fl,fm,fr

The function value at the left, middle, and right points of the bracket.

nfev

The number of function evaluations required to find the bracket.

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.
-1
unimodality, this implies the endpoint at the limit is a minimizer.
-2The maximum number of iterations was reached.
-3A non-finite value was encountered.
-4None shall pass.
-5
xmin <= xl0 < xm0 < xr0 <= xmax.

success

True when the algorithm terminated successfully (status 0).

Notes

Similar to scipy.optimize.bracket, this function seeks to find real points xl < xm < xr such that f(xl) >= f(xm) and f(xr) >= f(xm), where at least one of the inequalities is strict. Unlike scipy.optimize.bracket, this function can operate in a vectorized manner on array input, so long as the input arrays are broadcastable with each other. Also unlike scipy.optimize.bracket, users may specify minimum and maximum endpoints for the desired bracket.

Given an initial trio of points xl = xl0, xm = xm0, xr = xr0, the algorithm checks if these points already give a valid bracket. If not, a new endpoint, w is chosen in the "downhill" direction, xm becomes the new opposite endpoint, and either xl or xr becomes the new middle point, depending on which direction is downhill. The algorithm repeats from here.

The new endpoint w is chosen differently depending on whether or not a boundary xmin or xmax has been set in the downhill direction. Without loss of generality, suppose the downhill direction is to the right, so that f(xl) > f(xm) > f(xr). If there is no boundary to the right, then w is chosen to be xr + factor * (xr - xm) where factor is controlled by the user (defaults to 2.0) so that step sizes increase in geometric proportion. If there is a boundary, xmax in this case, then w is chosen to be xmax - (xmax - xr)/factor, with steps slowing to a stop at xmax. This cautious approach ensures that a minimum near but distinct from the boundary isn't missed while also detecting whether or not the xmax is a minimizer when xmax is reached after a finite number of steps.

Aliases

scipy.optimize._bracket._bracket_minimum