# NAG FL Interfacec05auf (contfn_​brent_​interval)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

c05auf locates a simple zero of a continuous function from a given starting value. It uses a binary search to locate an interval containing a zero of the function, then Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection, to locate the zero precisely.

## 2Specification

Fortran Interface
 Subroutine c05auf ( x, h, eps, eta, f, a, b,
 Integer, Intent (Inout) :: iuser(*), ifail Real (Kind=nag_wp), External :: f Real (Kind=nag_wp), Intent (In) :: h, eps, eta Real (Kind=nag_wp), Intent (Inout) :: x, ruser(*) Real (Kind=nag_wp), Intent (Out) :: a, b
#include <nag.h>
 void c05auf_ (double *x, const double *h, const double *eps, const double *eta, double (NAG_CALL *f)(const double *x, Integer iuser[], double ruser[]),double *a, double *b, Integer iuser[], double ruser[], Integer *ifail)
The routine may be called by the names c05auf or nagf_roots_contfn_brent_interval.

## 3Description

c05auf attempts to locate an interval $\left[a,b\right]$ containing a simple zero of the function $f\left(x\right)$ by a binary search starting from the initial point $x={\mathbf{x}}$ and using repeated calls to c05avf. If this search succeeds, then the zero is determined to a user-specified accuracy by a call to c05ayf. The specifications of routines c05avf and c05ayf should be consulted for details of the methods used.
The approximation $x$ to the zero $\alpha$ is determined so that at least one of the following criteria is satisfied:
1. (i)$|x-\alpha |\le {\mathbf{eps}}$,
2. (ii)$|f\left(x\right)|\le {\mathbf{eta}}$.
Brent R P (1973) Algorithms for Minimization Without Derivatives Prentice–Hall

## 5Arguments

1: $\mathbf{x}$Real (Kind=nag_wp) Input/Output
On entry: an initial approximation to the zero.
On exit: if ${\mathbf{ifail}}={\mathbf{0}}$ or ${\mathbf{4}}$, x is the final approximation to the zero.
If ${\mathbf{ifail}}={\mathbf{3}}$, x is likely to be a pole of $f\left(x\right)$.
Otherwise, x contains no useful information.
2: $\mathbf{h}$Real (Kind=nag_wp) Input
On entry: a step length for use in the binary search for an interval containing the zero. The maximum interval searched is $\left[{\mathbf{x}}-256.0×{\mathbf{h}},{\mathbf{x}}+256.0×{\mathbf{h}}\right]$.
Constraint: ${\mathbf{h}}$ must be sufficiently large that ${\mathbf{x}}+{\mathbf{h}}\ne {\mathbf{x}}$ on the computer.
3: $\mathbf{eps}$Real (Kind=nag_wp) Input
On entry: the termination tolerance on $x$ (see Section 3).
Constraint: ${\mathbf{eps}}>0.0$.
4: $\mathbf{eta}$Real (Kind=nag_wp) Input
On entry: a value such that if $|f\left(x\right)|\le {\mathbf{eta}}$, $x$ is accepted as the zero. eta may be specified as $0.0$ (see Section 7).
5: $\mathbf{f}$real (Kind=nag_wp) Function, supplied by the user. External Procedure
f must evaluate the function $f$ whose zero is to be determined.
The specification of f is:
Fortran Interface
 Function f ( x,
 Real (Kind=nag_wp) :: f Integer, Intent (Inout) :: iuser(*) Real (Kind=nag_wp), Intent (In) :: x Real (Kind=nag_wp), Intent (Inout) :: ruser(*)
 double f (const double *x, Integer iuser[], double ruser[])
1: $\mathbf{x}$Real (Kind=nag_wp) Input
On entry: the point at which the function must be evaluated.
2: $\mathbf{iuser}\left(*\right)$Integer array User Workspace
3: $\mathbf{ruser}\left(*\right)$Real (Kind=nag_wp) array User Workspace
f is called with the arguments iuser and ruser as supplied to c05auf. You should use the arrays iuser and ruser to supply information to f.
f must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which c05auf is called. Arguments denoted as Input must not be changed by this procedure.
Note: f should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by c05auf. If your code inadvertently does return any NaNs or infinities, c05auf is likely to produce unexpected results.
6: $\mathbf{a}$Real (Kind=nag_wp) Output
7: $\mathbf{b}$Real (Kind=nag_wp) Output
On exit: the lower and upper bounds respectively of the interval resulting from the binary search. If the zero is determined exactly such that $f\left(x\right)=0.0$ or is determined so that $|f\left(x\right)|\le {\mathbf{eta}}$ at any stage in the calculation, on exit ${\mathbf{a}}={\mathbf{b}}=x$.
8: $\mathbf{iuser}\left(*\right)$Integer array User Workspace
9: $\mathbf{ruser}\left(*\right)$Real (Kind=nag_wp) array User Workspace
iuser and ruser are not used by c05auf, but are passed directly to f and may be used to pass information to this routine.
10: $\mathbf{ifail}$Integer Input/Output
On 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 $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On 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, ${\mathbf{eps}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{eps}}>0.0$.
On entry, ${\mathbf{x}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{h}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{x}}+{\mathbf{h}}\ne {\mathbf{x}}$ (to machine accuracy).
${\mathbf{ifail}}=2$
An interval containing the zero could not be found. Increasing h and calling c05auf again will increase the range searched for the zero. Decreasing h and calling c05auf again will refine the mesh used in the search for the zero.
${\mathbf{ifail}}=3$
Solution may be a pole rather than a zero.
${\mathbf{ifail}}=4$
The tolerance eps has been set too small for the problem being solved. However, the value x returned is a good approximation to the zero. ${\mathbf{eps}}=⟨\mathit{\text{value}}⟩$.
${\mathbf{ifail}}=-99$
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 levels of accuracy depend on the values of eps and eta. If full machine accuracy is required, they may be set very small, resulting in an exit with ${\mathbf{ifail}}={\mathbf{4}}$, although this may involve many more iterations than a lesser accuracy. You are recommended to set ${\mathbf{eta}}=0.0$ and to use eps to control the accuracy, unless you have considerable knowledge of the size of $f\left(x\right)$ for values of $x$ near the zero.

## 8Parallelism and Performance

c05auf is not threaded in any implementation.

The time taken by c05auf depends primarily on the time spent evaluating f (see Section 5). The accuracy of the initial approximation x and the value of h will have a somewhat unpredictable effect on the timing.
If it is important to determine an interval of relative length less than $2×{\mathbf{eps}}$ containing the zero, or if f is expensive to evaluate and the number of calls to f is to be restricted, then use of c05avf followed by c05azf is recommended. Use of this combination is also recommended when the structure of the problem to be solved does not permit a simple f to be written: the reverse communication facilities of these routines are more flexible than the direct communication of f required by c05auf.
If the iteration terminates with successful exit and ${\mathbf{a}}={\mathbf{b}}={\mathbf{x}}$ there is no guarantee that the value returned in x corresponds to a simple zero 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 an approximation to the zero of $x-{e}^{-x}$ using a tolerance of ${\mathbf{eps}}=\text{1.0E−5}$ starting from ${\mathbf{x}}=1.0$ and using an initial search step ${\mathbf{h}}=0.1$.

### 10.1Program Text

Program Text (c05aufe.f90)

None.

### 10.3Program Results

Program Results (c05aufe.r)