`scipy.optimize._chandrupatla:_chandrupatla`

source: /scipy/optimize/_chandrupatla.py:8

Signature

def _chandrupatla(func, a, b, *, args = (), kwargs = None, xatol = None, xrtol = None, fatol = None, frtol = 0, maxiter = None, callback = None)

Summary

Find the root of an elementwise function using Chandrupatla's algorithm.

Extended Summary

For each element of the output of func, chandrupatla seeks the scalar root that makes the element 0. This function allows for a, b, and the output of func to be of any broadcastable shapes.

Parameters

func : callable

The function whose root is desired. 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 components of any type(s).
``func`` must be an elementwise function: each element ``func(x)[i]``
must equal ``func(x[i])`` for all indices ``i``. `_chandrupatla`
seeks an array ``x`` such that ``func(x)`` is an array of zeros.

a, b : array_like

The lower and upper bounds of the root of the function. Must be broadcastable with one another.

args : tuple, optional

Additional positional arguments to be passed to func.

kwargs : dict of str:array_like, optional

Additional keyword arguments to be passed to func.

xatol, xrtol, fatol, frtol : float, optional

Absolute and relative tolerances on the root and function value. See Notes for details.

maxiter : int, optional

The maximum number of iterations of the algorithm to perform. The default is the maximum possible number of bisections within the (normal) floating point numbers of the relevant dtype.

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 _chandrupatla (but containing the current iterate's values of all variables). If callback raises a StopIteration, the algorithm will terminate immediately and _chandrupatla will return a result.

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.

x: The root of the function, if the algorithm terminated successfully.
nfev: The number of times the function was called to find the root.
nit: The number of iterations of Chandrupatla's algorithm performed.
status: 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 by callback. 1 : The algorithm is proceeding normally (in callback only).
success: True when the algorithm terminated successfully (status 0).
fun: The value of func evaluated at x.
xl,xr: The lower and upper ends of the bracket.
fl,fr: The function value at the lower and upper ends of the bracket.

Notes

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

If xl and xr are the left and right ends of the bracket, xmin = xl if abs(func(xl)) <= abs(func(xr)) else xr, and fmin0 = min(func(a), func(b)), then the algorithm is considered to have converged when abs(xr - xl) < xatol + abs(xmin) * xrtol or fun(xmin) <= fatol + abs(fmin0) * frtol. This is equivalent to the termination condition described in ^[1] with xrtol = 4e-10, xatol = 1e-5, and fatol = frtol = 0. The default values are xatol = 4*tiny, xrtol = 4*eps, frtol = 0, and fatol = tiny, where eps and tiny are the precision and smallest normal number of the result dtype of function inputs and outputs.

Examples

from scipy import optimize
def f(x, c):
    return x**3 - 2*x - c
c = 5
res = optimize._chandrupatla._chandrupatla(f, 0, 3, args=(c,))

✓

res.x

✗

np.float64(2.0945514815423265)

c = [3, 4, 5]
res = optimize._chandrupatla._chandrupatla(f, 0, 3, args=(c,))

✓

res.x

✗

array([1.89329, 2.     , 2.09455])

Aliases

scipy.optimize._chandrupatla._chandrupatla