naginterfaces.library.roots.contfn_​brent_​interval

naginterfaces.library.roots.contfn_brent_interval(x, f, h=0.1, eps=1.1102230246251565e-13, eta=0.0, data=None)

contfn_brent_interval locates a simple zero of a continuous function from a given starting value. It uses a binary search to locate an interval containing a zero of the function, then Brent’s method, which is a combination of nonlinear interpolation, linear extrapolation and bisection, to locate the zero precisely.

For full information please refer to the NAG Library document for c05au

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/c05/c05auf.html

Parameters

xfloat

An initial approximation to the zero.

fcallable retval = f(x, data=None)

$f$ must evaluate the function $f$ whose zero is to be determined.

Parameters

xfloat

The point at which the function must be evaluated.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalfloat

The value of $f$ at the specified point.

hfloat, optional

A step length for use in the binary search for an interval containing the zero. The maximum interval searched is $[x-256.0\times h,x+256.0\times h]$.

epsfloat, optional

The termination tolerance on $x$ (see Notes).

etafloat, optional

A value such that if $\left|f\left(x\right)\right|\le eta$, $x$ is accepted as the zero. $eta$ may be specified as $0.0$ (see Accuracy).

dataarbitrary, optional

User-communication data for callback functions.

Returns

xfloat

If the function exits successfully or $errno$ = 4, $x$ is the final approximation to the zero.

If $errno$ = 3, $x$ is likely to be a pole of $f\left(x\right)$.

Otherwise, $x$ contains no useful information.

afloat

The lower bound of the interval resulting from the binary search

bfloat

The upper bound of the interval resulting from the binary search

Raises

NagValueError

(errno $1$)

On entry, $eps=⟨value⟩$.

Constraint: $eps>0.0$.

(errno $1$)

On entry, $x=⟨value⟩$ and $h=⟨value⟩$.

Constraint: $x+h\ne x$ (to machine accuracy).

(errno $2$)

An interval containing the zero could not be found. Increasing $h$ and calling contfn_brent_interval again will increase the range searched for the zero. Decreasing $h$ and calling contfn_brent_interval again will refine the mesh used in the search for the zero.

Warns

NagAlgorithmicWarning

(errno $3$)

Solution may be a pole rather than a zero.

(errno $4$)

The tolerance $eps$ has been set too small for the problem being solved. However, the value $x$ returned is a good approximation to the zero. $eps=⟨value⟩$.

Notes

contfn_brent_interval attempts to locate an interval $[a,b]$ containing a simple zero of the function $f\left(x\right)$ by a binary search starting from the initial point $x=x$ and using repeated calls to contfn_interval_rcomm(). If this search succeeds, then the zero is determined to a user-specified accuracy by a call to contfn_brent(). The specifications of functions contfn_interval_rcomm() and contfn_brent() should be consulted for details of the methods used.

The approximation $x$ to the zero $\alpha$ is determined so that at least one of the following criteria is satisfied:

1. $|x-\alpha |\le eps$,

2. $\left|f\left(x\right)\right|\le eta$.

References

Brent, R P, 1973, Algorithms for Minimization Without Derivatives, Prentice–Hall

See also

naginterfaces.library.examples.roots.contfn_brent_interval_ex.main()