scipy.optimize.elementwise.

find_minimum#

scipy.optimize.elementwise.find_minimum(f,init,/,*,args=(),tolerances=None,maxiter=100,callback=None)[source]#

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

For each element of the output off,find_minimum seeks the scalar minimizerthat minimizes the element. This function currently uses Chandrupatla’sbracketing minimization algorithm[1] and therefore requires argumentinitto provide a three-point minimization bracket:x1<x2<x3 such thatfunc(x1)>=func(x2)<=func(x3), where one of the inequalities is strict.

Provided a valid bracket,find_minimum is guaranteed to converge to a localminimum that satisfies the providedtolerances if the function is continuouswithin the bracket.

This function works elementwise wheninit andargs contain (broadcastable)arrays.

Parameters:
fcallable

The function whose minimizer is desired. The signature must be:

f(x:array,*args)->array

where each element ofx is a finite real andargs is a tuple,which may contain an arbitrary number of arrays that are broadcastablewithx.

f must be an elementwise function: each elementf(x)[i]must equalf(x[i]) for all indicesi. It must not mutate thearrayx or the arrays inargs.

find_minimum seeks an arrayx such thatf(x) is an array oflocal minima.

init3-tuple of float array_like

The abscissae of a standard scalar minimization bracket. A bracket isvalid if arraysx1,x2,x3=init satisfyx1<x2<x3 andfunc(x1)>=func(x2)<=func(x3), where one of the inequalitiesis strict. Arrays must be broadcastable with one another and the arraysofargs.

argstuple of array_like, optional

Additional positional array arguments to be passed tof. Arraysmust be broadcastable with one another and the arrays ofinit.If the callable for which the root is desired requires arguments that arenot broadcastable withx, wrap that callable withf such thatfaccepts onlyx and broadcastable*args.

tolerancesdictionary 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.

maxiterint, default: 100

The maximum number of iterations of the algorithm to perform.

callbackcallable, optional

An optional user-supplied function to be called before the firstiteration and after each iteration.Called ascallback(res), whereres is a_RichResultsimilar to that returned byfind_minimum (but containing the currentiterate’s values of all variables). Ifcallback raises aStopIteration, the algorithm will terminate immediately andfind_root will return a result.callback must not mutateres or its attributes.

Returns:
res_RichResult

An object similar to an instance ofscipy.optimize.OptimizeResult with thefollowing attributes. The descriptions are written as though the values willbe scalars; however, iff returns an array, the outputs will bearrays of the same shape.

successbool array

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

statusint array

An integer representing the exit status of the algorithm.

  • 0 : The algorithm converged to the specified tolerances.

  • -1 : The algorithm encountered an invalid bracket.

  • -2 : The maximum number of iterations was reached.

  • -3 : A non-finite value was encountered.

  • -4 : Iteration was terminated bycallback.

  • 1 : The algorithm is proceeding normally (incallback only).

xfloat array

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

f_xfloat array

The value off evaluated atx.

nfevint array

The number of abscissae at whichf was evaluated to find the root.This is distinct from the number of timesf iscalled because thethe function may evaluated at multiple points in a single call.

nitint array

The number of iterations of the algorithm that were performed.

brackettuple of float arrays

The final three-point bracket.

f_brackettuple of float arrays

The value off evaluated at the bracket points.

Notes

Implemented based on Chandrupatla’s original paper[1].

Ifxl<xm<xr are the points of the bracket andfl>=fm<=fr(where one of the inequalities is strict) are the values off evaluatedat 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 ofxrtol is the square root of the precision of theappropriate dtype, andxatol=fatol=frtol is the smallest normalnumber of the appropriate dtype.

Array API Standard Support

find_minimum has experimental support for Python Array API Standard compatiblebackends in addition to NumPy. Please consider testing these featuresby setting an environment variableSCIPY_ARRAY_API=1 and providingCuPy, PyTorch, JAX, or Dask arrays as array arguments. The followingcombinations of backend and device (or other capability) are supported.

Library

CPU

GPU

NumPy

✅

n/a

CuPy

n/a

✅

PyTorch

✅

✅

JAX

⛔

⛔

Dask

⛔

n/a

SeeSupport for the array API standard for more information.

References

[1](1,2)

Chandrupatla, Tirupathi R. (1998).“An efficient quadratic fit-sectioning algorithm for minimizationwithout derivatives”.Computer Methods in Applied Mechanics and Engineering, 152 (1-2),211-217.https://doi.org/10.1016/S0045-7825(97)00190-4

Examples

Suppose we wish to minimize the following function.

>>>deff(x,c=1):...return(x-c)**2+2

First, we must find a valid bracket. The function is unimodal,sobracket_minium will easily find a bracket.

>>>fromscipy.optimizeimportelementwise>>>res_bracket=elementwise.bracket_minimum(f,0)>>>res_bracket.successTrue>>>res_bracket.bracket(0.0, 0.5, 1.5)

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

>>>xl,xm,xr=res_bracket.bracket>>>fl,fm,fr=res_bracket.f_bracket>>>(xl<xm<xr)and(fl>fm<=fr)True

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

>>>res_minimum=elementwise.find_minimum(f,res_bracket.bracket)>>>res_minimum.x1.0000000149011612

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

>>>importnumpyasnp>>>fl,fm,fr=res_minimum.f_bracket>>>(fl-fm)/np.spacing(fm),(fr-fm)/np.spacing(fm)(0.0, 2.0)

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

>>>res_minimum.f_x2.0

bracket_minimum andfind_minimum accept arrays for most arguments.For instance, to find the minimizers and minima for a few values of theparameterc at once:

>>>c=np.asarray([1,1.5,2])>>>res_bracket=elementwise.bracket_minimum(f,0,args=(c,))>>>res_bracket.bracket(array([0. , 0.5, 0.5]), array([0.5, 1.5, 1.5]), array([1.5, 2.5, 2.5]))>>>res_minimum=elementwise.find_minimum(f,res_bracket.bracket,args=(c,))>>>res_minimum.xarray([1.00000001, 1.5       , 2.        ])>>>res_minimum.f_xarray([2., 2., 2.])
On this page