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_29.2/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 callcontfn_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