# NAG FL Interfacec05azf (contfn_​brent_​rcomm)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

c05azf 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.

## 2Specification

Fortran Interface
 Subroutine c05azf ( x, y, fx, tolx, ir, c, ind,
 Integer, Intent (In) :: ir Integer, Intent (Inout) :: ind, ifail Real (Kind=nag_wp), Intent (In) :: fx, tolx Real (Kind=nag_wp), Intent (Inout) :: x, y, c(17)
C Header Interface
#include <nag.h>
 void c05azf_ (double *x, double *y, const double *fx, const double *tolx, const Integer *ir, double c[], Integer *ind, Integer *ifail)
The routine may be called by the names c05azf or nagf_roots_contfn_brent_rcomm.

## 3Description

You must supply x and y to define an initial interval $\left[a,b\right]$ containing a simple zero of the function $f\left(x\right)$ (the choice of x and y must be such that $f\left({\mathbf{x}}\right)×f\left({\mathbf{y}}\right)\le 0.0$). The routine 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 $\left[{\mathbf{x}},{\mathbf{y}}\right]$ contains the zero and $|{\mathbf{x}}-{\mathbf{y}}|$ is less than some tolerance specified by tolx and ir (see Section 5). In fact, since the intermediate intervals $\left[{\mathbf{x}},{\mathbf{y}}\right]$ are determined only so that $f\left({\mathbf{x}}\right)×f\left({\mathbf{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). c05azf 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 routine is that unlike some other methods it guarantees convergence within about ${\left({\mathrm{log}}_{2}\left[\left(b-a\right)/\delta \right]\right)}^{2}$ function evaluations, where $\delta$ is related to the argument tolx. See Brent (1973) for more details.
c05azf returns to the calling program for each evaluation of $f\left(x\right)$. On each return you should set ${\mathbf{fx}}=f\left({\mathbf{x}}\right)$ and call c05azf again.
The routine is a modified version of procedure ‘zeroin’ given by Brent (1973).

## 4References

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

## 5Arguments

Note: this routine uses reverse communication. Its use involves an initial entry, intermediate exits and re-entries, and a final exit, as indicated by the argument ind. Between intermediate exits and re-entries, all arguments other than fx must remain unchanged.
1: $\mathbf{x}$Real (Kind=nag_wp) Input/Output
2: $\mathbf{y}$Real (Kind=nag_wp) Input/Output
On initial entry: x and y must define an initial interval $\left[a,b\right]$ containing the zero, such that $f\left({\mathbf{x}}\right)×f\left({\mathbf{y}}\right)\le 0.0$. It is not necessary that ${\mathbf{x}}<{\mathbf{y}}$.
On intermediate exit: x contains the point at which $f$ must be evaluated before re-entry to the routine.
On final exit: x and y define a smaller interval containing the zero, such that $f\left({\mathbf{x}}\right)×f\left({\mathbf{y}}\right)\le 0.0$, and $|{\mathbf{x}}-{\mathbf{y}}|$ satisfies the accuracy specified by tolx and ir, unless an error has occurred. If ${\mathbf{ifail}}={\mathbf{4}}$, x and y generally contain very good approximations to a pole; if ${\mathbf{ifail}}={\mathbf{5}}$, x and y generally contain very good approximations to the zero (see Section 6). If a point x is found such that $f\left({\mathbf{x}}\right)=0.0$, on final exit ${\mathbf{x}}={\mathbf{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.
3: $\mathbf{fx}$Real (Kind=nag_wp) Input
On initial entry: if ${\mathbf{ind}}=1$, fx need not be set.
If ${\mathbf{ind}}=-1$, fx must contain $f\left({\mathbf{x}}\right)$ for the initial value of x.
On intermediate re-entry: must contain $f\left({\mathbf{x}}\right)$ for the current value of x.
4: $\mathbf{tolx}$Real (Kind=nag_wp) Input
On initial entry: the accuracy to which the zero is required. The type of error test is specified by ir.
Constraint: ${\mathbf{tolx}}>0.0$.
5: $\mathbf{ir}$Integer Input
On initial entry: indicates the type of error test.
${\mathbf{ir}}=0$
The test is: $|{\mathbf{x}}-{\mathbf{y}}|\le 2.0×{\mathbf{tolx}}×\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1.0,|{\mathbf{x}}|\right)$.
${\mathbf{ir}}=1$
The test is: $|{\mathbf{x}}-{\mathbf{y}}|\le 2.0×{\mathbf{tolx}}$.
${\mathbf{ir}}=2$
The test is: $|{\mathbf{x}}-{\mathbf{y}}|\le 2.0×{\mathbf{tolx}}×|{\mathbf{x}}|$.
Suggested value: ${\mathbf{ir}}=0$.
Constraint: ${\mathbf{ir}}=0$, $1$ or $2$.
6: $\mathbf{c}\left(17\right)$Real (Kind=nag_wp) array Input/Output
On initial entry: if ${\mathbf{ind}}=1$, no elements of c need be set.
If ${\mathbf{ind}}=-1$, ${\mathbf{c}}\left(1\right)$ must contain $f\left({\mathbf{y}}\right)$, other elements of c need not be set.
On final exit: is undefined.
7: $\mathbf{ind}$Integer Input/Output
On initial entry: must be set to $1$ or $-1$.
${\mathbf{ind}}=1$
fx and ${\mathbf{c}}\left(1\right)$ need not be set.
${\mathbf{ind}}=-1$
fx and ${\mathbf{c}}\left(1\right)$ must contain $f\left({\mathbf{x}}\right)$ and $f\left({\mathbf{y}}\right)$ respectively.
On intermediate exit: contains $2$, $3$ or $4$. The calling program must evaluate $f$ at x, storing the result in fx, and re-enter c05azf with all other arguments unchanged.
On final exit: contains $0$.
Constraint: on entry ${\mathbf{ind}}=-1$, $1$, $2$, $3$ or $4$.
Note: any values you return to c05azf as part of the reverse communication procedure should not include floating-point NaN (Not a Number) or infinity values, since these are not handled by c05azf. If your code does inadvertently return any NaNs or infinities, c05azf is likely to produce unexpected results.
8: $\mathbf{ifail}$Integer Input/Output
On initial entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $-1$ is recommended since useful values can be provided in some output arguments even when ${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On final exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
On entry, $f\left({\mathbf{x}}\right)$ and $f\left({\mathbf{y}}\right)$ have the same sign with neither equalling $0.0$: $f\left({\mathbf{x}}\right)=⟨\mathit{\text{value}}⟩$ and $f\left({\mathbf{y}}\right)=⟨\mathit{\text{value}}⟩$.
${\mathbf{ifail}}=2$
On entry, ${\mathbf{ind}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ind}}=-1$, $1$, $2$, $3$ or $4$.
${\mathbf{ifail}}=3$
On entry, ${\mathbf{ir}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ir}}=0$, $1$ or $2$.
On entry, ${\mathbf{tolx}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{tolx}}>0.0$.
${\mathbf{ifail}}=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 $\left[{\mathbf{x}},{\mathbf{y}}\right]$ contains a zero, or it may not be taken when $\left[{\mathbf{x}},{\mathbf{y}}\right]$ contains a pole. Both these cases occur most frequently when tolx is large.
${\mathbf{ifail}}=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. ${\mathbf{tolx}}=⟨\mathit{\text{value}}⟩$.
${\mathbf{ifail}}=-99$
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

The accuracy of the final value x as an approximation of the zero is determined by tolx and ir (see Section 5). A relative accuracy criterion (${\mathbf{ir}}=2$) should not be used when the initial values x and y are of different orders of magnitude. In this case a change of origin of the independent variable may be appropriate. For example, if the initial interval $\left[{\mathbf{x}},{\mathbf{y}}\right]$ is transformed linearly to the interval $\left[1,2\right]$, then the zero can be determined to a precise number of figures using an absolute (${\mathbf{ir}}=1$) or relative (${\mathbf{ir}}=2$) error test and the effect of the transformation back to the original interval can also be determined. Except for the accuracy check, such a transformation has no effect on the calculation of the zero.

## 8Parallelism and Performance

c05azf is not threaded in any implementation.

## 9Further Comments

For most problems, the time taken on each call to c05azf will be negligible compared with the time spent evaluating $f\left(x\right)$ between calls to c05azf.
If the calculation terminates because $f\left({\mathbf{x}}\right)=0.0$, then on return y is set to x. (In fact, ${\mathbf{y}}={\mathbf{x}}$ on return only in this case and, possibly, when ${\mathbf{ifail}}={\mathbf{5}}$.) There is no guarantee that the value returned in x corresponds to a simple root and you should check whether it does. One way to check this is to compute the derivative of $f$ at the point x, preferably analytically, or, if this is not possible, numerically, perhaps by using a central difference estimate. If ${f}^{\prime }\left({\mathbf{x}}\right)=0.0$, then x must correspond to a multiple zero of $f$ rather than a simple zero.

## 10Example

This example calculates a zero of ${e}^{-x}-x$ with an initial interval $\left[0,1\right]$, ${\mathbf{tolx}}=\text{1.0E−5}$ and a mixed error test.

### 10.1Program Text

Program Text (c05azfe.f90)

None.

### 10.3Program Results

Program Results (c05azfe.r)