naginterfaces.library.roots.contfn_​brent_​rcomm

naginterfaces.library.roots.contfn_brent_rcomm(x, y, fx, tolx, c, ind, ir=0)

contfn_brent_rcomm locates a simple zero of a continuous function in a given interval by using Brent’s method, which is a combination of nonlinear interpolation, linear extrapolation and bisection. It uses reverse communication for evaluating the function.

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

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

Parameters

xfloat

On initial entry: $x$ and $y$ must define an initial interval $[a,b]$ containing the zero, such that $f\left(x\right)\times f\left(y\right)\le 0.0$. It is not necessary that $x<y$. Otherwise, $x$ and $y$ must be the same entities output by a previous call to contfn_brent_rcomm.

yfloat

On initial entry: $x$ and $y$ must define an initial interval $[a,b]$ containing the zero, such that $f\left(x\right)\times f\left(y\right)\le 0.0$. It is not necessary that $x<y$. Otherwise, $x$ and $y$ must be the same entities output by a previous call to contfn_brent_rcomm.

fxfloat

On initial entry: if $ind=1$, $fx$ need not be set.

If $ind=-1$, $fx$ must contain $f\left(x\right)$ for the initial value of $x$.

On intermediate entry: must contain $f\left(x\right)$ for the current value of $x$.

tolxfloat

On initial entry: the accuracy to which the zero is required. The type of error test is specified by $ir$.

cfloat, ndarray, shape $\left(17\right)$, modified in place

On initial entry: if $ind=1$, no elements of $c$ need be set.

If $ind=-1$, $c\left[0\right]$ must contain $f\left(y\right)$, other elements of $c$ need not be set.

On final exit: is undefined.

indint

On initial entry: must be set to $1$ or $-1$.

$ind=1$

$fx$ and $c\left[0\right]$ need not be set.

$ind=-1$

$fx$ and $c\left[0\right]$ must contain $f\left(x\right)$ and $f\left(y\right)$ respectively.

irint, optional

On initial entry: indicates the type of error test.

$ir=0$

The test is: $|x-y|\le 2.0\times tolx\times max(1.0,\left|x\right|)$.

$ir=1$

The test is: $|x-y|\le 2.0\times tolx$.

$ir=2$

The test is: $|x-y|\le 2.0\times tolx\times \left|x\right|$.

Returns

xfloat

On intermediate exit: $x$ contains the point at which $f$ must be evaluated before re-entry to the function. $y$ has no external significance but must be communicated back to the next call of contfn_brent_rcomm as argument $y$.

On final exit: $x$ and $y$ define a smaller interval containing the zero, such that $f\left(x\right)\times f\left(y\right)\le 0.0$, and $|x-y|$ satisfies the accuracy specified by $tolx$ and $ir$, unless an error has occurred. If $errno$ = 4, $x$ and $y$ generally contain very good approximations to a pole; if $errno$ = 5, $x$ and $y$ generally contain very good approximations to the zero (see Exceptions). If a point $x$ is found such that $f\left(x\right)=0.0$, on final exit $x=y$ (in this case there is no guarantee that $x$ is a simple zero). In all cases, the value returned in $x$ is the better approximation to the zero.

yfloat

On intermediate exit: $x$ contains the point at which $f$ must be evaluated before re-entry to the function. $y$ has no external significance but must be communicated back to the next call of contfn_brent_rcomm as argument $y$.

On final exit: $x$ and $y$ define a smaller interval containing the zero, such that $f\left(x\right)\times f\left(y\right)\le 0.0$, and $|x-y|$ satisfies the accuracy specified by $tolx$ and $ir$, unless an error has occurred. If $errno$ = 4, $x$ and $y$ generally contain very good approximations to a pole; if $errno$ = 5, $x$ and $y$ generally contain very good approximations to the zero (see Exceptions). If a point $x$ is found such that $f\left(x\right)=0.0$, on final exit $x=y$ (in this case there is no guarantee that $x$ is a simple zero). In all cases, the value returned in $x$ is the better approximation to the zero.

indint

On intermediate exit: contains $2$, $3$ or $4$. The calling program must evaluate $f$ at $x$, storing the result in $fx$, and re-enter contfn_brent_rcomm with all other arguments unchanged.

On final exit: contains $0$.

Raises

NagValueError

(errno $1$)

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

(errno $2$)

On entry, $ind=⟨value⟩$.

Constraint: $ind=-1$, $1$, $2$, $3$ or $4$.

(errno $3$)

On entry, $tolx=⟨value⟩$.

Constraint: $tolx>0.0$.

(errno $3$)

On entry, $ir=⟨value⟩$.

Constraint: $ir=0$, $1$ or $2$.

Warns

NagAlgorithmicWarning

(errno $4$)

The final interval may contain a pole rather than a zero. Note that this error exit is not completely reliable: it may be taken in extreme cases when $[x,y]$ contains a zero, or it may not be taken when $[x,y]$ contains a pole. Both these cases occur most frequently when $tolx$ is large.

(errno $5$)

The tolerance $tolx$ has been set too small for the problem being solved. However, the values $x$ and $y$ returned may well be good approximations to the zero. $tolx=⟨value⟩$.

Notes

You must supply $x$ and $y$ to define an initial interval $[a,b]$ containing a simple zero of the function $f\left(x\right)$ (the choice of $x$ and $y$ must be such that $f\left(x\right)\times f\left(y\right)\le 0.0$). The function combines the methods of bisection, nonlinear interpolation and linear extrapolation (see Dahlquist and Björck (1974)), to find a sequence of sub-intervals of the initial interval such that the final interval $[x,y]$ contains the zero and $|x-y|$ is less than some tolerance specified by $tolx$ and $ir$ (see Parameters). In fact, since the intermediate intervals $[x,y]$ are determined only so that $f\left(x\right)\times f\left(y\right)\le 0.0$, it is possible that the final interval may contain a discontinuity or a pole of $f$ (violating the requirement that $f$ be continuous). contfn_brent_rcomm checks if the sign change is likely to correspond to a pole of $f$ and gives an error return in this case.

A feature of the algorithm used by this function is that unlike some other methods it guarantees convergence within about ${\left({log}_2\left[(b-a)/\delta \right]\right)}^2$ function evaluations, where $\delta$ is related to the argument $tolx$. See Brent (1973) for more details.

contfn_brent_rcomm returns to the calling program for each evaluation of $f\left(x\right)$. On each return you should set $fx=f\left(x\right)$ and call contfn_brent_rcomm again.

The function is a modified version of procedure ‘zeroin’ given by Brent (1973).

References

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

Bus, J C P and Dekker, T J, 1975, Two efficient algorithms with guaranteed convergence for finding a zero of a function, ACM Trans. Math. Software (1), 330–345

Dahlquist, G and Björck, Å, 1974, Numerical Methods, Prentice–Hall