naginterfaces.library.roots.contfn_​brent

naginterfaces.library.roots.contfn_brent(a, b, f, eps=1.1102230246251565e-13, eta=0.0, data=None)

contfn_brent locates a simple zero of a continuous function in a given interval using Brent’s method, which is a combination of nonlinear interpolation, linear extrapolation and bisection.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/c05/c05ayf.html

Parameters

afloat

$a$, the lower bound of the interval.

bfloat

$b$, the upper bound of the interval.

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$ evaluated at $x$.

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$ = 2, $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.

Raises

NagValueError

(errno $1$)

On entry, $eps=⟨value⟩$.

Constraint: $eps>0.0$.

(errno $1$)

On entry, $a=⟨value⟩$ and $b=⟨value⟩$.

Constraint: $a\ne b$.

(errno $1$)

On entry, $f\left(a\right)$ and $f\left(b\right)$ have the same sign with neither equalling $0.0$: $f\left(a\right)=⟨value⟩$ and $f\left(b\right)=⟨value⟩$.

Warns

NagAlgorithmicWarning

(errno $2$)

No further improvement in the solution is possible. $eps$ is too small: $eps=⟨value⟩$. The final value of $x$ returned is an accurate approximation to the zero.

(errno $3$)

The function values in the interval $[a,b]$ might contain a pole rather than a zero. Reducing $eps$ may help in distinguishing between a pole and a zero.

Notes

contfn_brent attempts to obtain an approximation to a simple zero of the function $f\left(x\right)$ given an initial interval $[a,b]$ such that $f\left(a\right)\times f\left(b\right)\le 0$. The same core algorithm is used by contfn_brent_rcomm() whose specification should be consulted for details of the method 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