naginterfaces.library.roots.contfn_​brent_​rcomm

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

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://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/c05/c05azf.html

Parameters
xfloat

On initial entry: and must define an initial interval containing the zero, such that . It is not necessary that . Otherwise, and must be the same entities output by a previous call to contfn_brent_rcomm.

yfloat

On initial entry: and must define an initial interval containing the zero, such that . It is not necessary that . Otherwise, and must be the same entities output by a previous call to contfn_brent_rcomm.

fxfloat

On initial entry: if , need not be set.

If , must contain for the initial value of .

On intermediate entry: must contain for the current value of .

tolxfloat

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

cfloat, ndarray, shape , modified in place

On initial entry: if , no elements of need be set.

If , must contain , other elements of need not be set.

On final exit: is undefined.

indint

On initial entry: must be set to or .

and need not be set.

and must contain and respectively.

irint, optional

On initial entry: indicates the type of error test.

The test is: .

The test is: .

The test is: .

Returns
xfloat

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

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

yfloat

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

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

indint

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

On final exit: contains .

Raises
NagValueError
(errno )

On entry, and have the same sign with neither equalling : and .

(errno )

On entry, .

Constraint: , , , or .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: , or .

Warns
NagAlgorithmicWarning
(errno )

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 contains a zero, or it may not be taken when contains a pole. Both these cases occur most frequently when is large.

(errno )

The tolerance has been set too small for the problem being solved. However, the values and returned may well be good approximations to the zero. .

Notes

You must supply and to define an initial interval containing a simple zero of the function (the choice of and must be such that ). 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 contains the zero and is less than some tolerance specified by and (see Parameters). In fact, since the intermediate intervals are determined only so that , it is possible that the final interval may contain a discontinuity or a pole of (violating the requirement that be continuous). contfn_brent_rcomm checks if the sign change is likely to correspond to a pole of 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 function evaluations, where is related to the argument . See Brent (1973) for more details.

contfn_brent_rcomm returns to the calling program for each evaluation of . On each return you should set 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