bundles / scipy latest / scipy / optimize / _elementwise / find_minimum

function

`scipy.optimize._elementwise:find_minimum`

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

Signature

def find_minimum(f, init, /, args = (), kwargs = None, tolerances = None, maxiter = 100, callback = None, preserve_shape = False)

Summary

Find the minimum of a unimodal, real-valued function of a real variable.

Extended Summary

For each element of the output of f, find_minimum seeks the scalar minimizer that minimizes the element. This function currently uses Chandrupatla's bracketing minimization algorithm ^[1] and therefore requires argument init to provide a three-point minimization bracket: x1 < x2 < x3 such that func(x1) >= func(x2) <= func(x3), where one of the inequalities is strict.

Provided a valid bracket, find_minimum is guaranteed to converge to a local minimum that satisfies the provided tolerances if the function is continuous within the bracket.

This function works elementwise when init and args contain (broadcastable) arrays.

Parameters

f : callable

The function whose minimizer is desired. The signature must be

f(xi: array, *argsi) -> array

where each element of xi is a finite real and argsi is a tuple, which may contain an arbitrary number of arrays that are broadcastable with xi.

f must be an elementwise function: each element f(xi)[j] must equal f(xi[j]) for all indices j. It must not mutate the array xi or the arrays in argsi.

find_minimum seeks an array x such that f(xi) is an array of local minima.

init : 3-tuple of float array_like

The abscissae of a standard scalar minimization bracket. A bracket is valid if arrays x1, x2, x3 = init satisfy x1 < x2 < x3 and func(x1) >= func(x2) <= func(x3), where one of the inequalities is strict. Arrays must be broadcastable with one another and the arrays of args.

args : tuple of array_like, optional

Additional positional array arguments to be passed to f. Arrays must be broadcastable with one another and the arrays of init. If the callable for which the root is desired requires arguments that are not broadcastable with x, wrap that callable with f such that f accepts only x and broadcastable *args.

kwargs : dict of str:array_like, optional

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

tolerances : dictionary of floats, optional

Absolute and relative tolerances on the root and function value. Valid keys of the dictionary are:

xatol - absolute tolerance on the root
xrtol - relative tolerance on the root
fatol - absolute tolerance on the function value
frtol - relative tolerance on the function value

See Notes for default values and explicit termination conditions.

maxiter : int, default: 100

The maximum number of iterations of the algorithm to perform.

callback : callable, optional

An optional user-supplied function to be called before the first iteration and after each iteration. Called as callback(res), where res is a _RichResult similar to that returned by find_minimum (but containing the current iterate's values of all variables). If callback raises a StopIteration, the algorithm will terminate immediately and find_root will return a result. callback must not mutate res or its attributes.

preserve_shape : bool, default: False

In the following, "arguments of f" refers to the array xi and any arrays within argsi. Let shape be the broadcasted shape of all elements of init and args (which is conceptually distinct from xi` and ``argsi passed into f).

When preserve_shape=False (default), f must accept arguments of any broadcastable shapes.
When preserve_shape=True, f must accept arguments of shape shape + (n,), where n is the number of abscissae at which the function is being evaluated.

In either case, for each scalar element xi[j] within xi, the array returned by f must include the scalar f(xi[j]) at the same index. Consequently, the shape of the output is always the shape of the input xi.

Returns

res : _RichResult

An object similar to an instance of scipy.optimize.OptimizeResult with the following attributes. The descriptions are written as though the values will be scalars; however, if f returns an array, the outputs will be arrays of the same shape.

success

True where the algorithm terminated successfully (status 0); False otherwise.

status

An integer representing the exit status of the algorithm.

0The algorithm converged to the specified tolerances.
-1The algorithm encountered an invalid bracket.
-2The maximum number of iterations was reached.
-3A non-finite value was encountered.
-4Iteration was terminated by callback.
1The algorithm is proceeding normally (in callback only).

x

The minimizer of the function, if the algorithm terminated successfully.

f_x

The value of f evaluated at x.

nfev

The number of abscissae at which f was evaluated to find the root. This is distinct from the number of times f is called because the the function may evaluated at multiple points in a single call.

nit

The number of iterations of the algorithm that were performed.

bracket

The final three-point bracket.

f_bracket

The value of f evaluated at the bracket points.

Notes

Implemented based on Chandrupatla's original paper ^[1].

If xl < xm < xr are the points of the bracket and fl >= fm <= fr (where one of the inequalities is strict) are the values of f evaluated at those points, then the algorithm is considered to have converged when:

abs(xr - xm)/2 <= abs(xm)*xrtol + xatol or
(fl - 2*fm + fr)/2 <= abs(fm)*frtol + fatol.

The default value of xrtol is the square root of the precision of the appropriate dtype, and xatol = fatol = frtol is the smallest normal number of the appropriate dtype.

Examples

Suppose we wish to minimize the following function.

def f(x, c=1):
    return (x - c)**2 + 2

✓

First, we must find a valid bracket. The function is unimodal, so `bracket_minimum` will easily find a bracket.

from scipy.optimize import elementwise
res_bracket = elementwise.bracket_minimum(f, 0)

✓

res_bracket.success
res_bracket.bracket

✗

(np.float64(0.0), np.float64(0.5), np.float64(1.5))

Indeed, the bracket points are ordered and the function value at the middle bracket point is less than at the surrounding points.

xl, xm, xr = res_bracket.bracket
fl, fm, fr = res_bracket.f_bracket

✓

(xl < xm < xr) and (fl > fm <= fr)

✗

np.True_

Once we have a valid bracket, `find_minimum` can be used to provide an estimate of the minimizer.

res_minimum = elementwise.find_minimum(f, res_bracket.bracket)

✓

res_minimum.x

✗

np.float64(1.0000000149011612)

The function value changes by only a few ULPs within the bracket, so the minimizer cannot be determined much more precisely by evaluating the function alone (i.e. we would need its derivative to do better).

import numpy as np
fl, fm, fr = res_minimum.f_bracket

✓

(fl - fm) / np.spacing(fm), (fr - fm) / np.spacing(fm)

✗

(np.float64(0.0), np.float64(2.0))

Therefore, a precise minimum of the function is given by:

res_minimum.f_x

✗

np.float64(2.0)

`bracket_minimum` and `find_minimum` accept arrays for most arguments. For instance, to find the minimizers and minima for a few values of the parameter ``c`` at once:

c = np.asarray([1, 1.5, 2])
res_bracket = elementwise.bracket_minimum(f, 0, args=(c,))
res_bracket.bracket
res_minimum = elementwise.find_minimum(f, res_bracket.bracket, args=(c,))

✓

res_minimum.x

✗

array([1. , 1.5, 2. ])

res_minimum.f_x

✓

array([2., 2., 2.])

Aliases

scipy.optimize._elementwise.find_minimum