Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_roots_contfn_brent_interval (c05au)

## Purpose

nag_roots_contfn_brent_interval (c05au) 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.

## Syntax

[x, a, b, user, ifail] = c05au(x, h, eps, eta, f, 'user', user)
[x, a, b, user, ifail] = nag_roots_contfn_brent_interval(x, h, eps, eta, f, 'user', user)

## Description

nag_roots_contfn_brent_interval (c05au) attempts to locate an interval [a,b] $\left[a,b\right]$ containing a simple zero of the function f(x) $f\left(x\right)$ by a binary search starting from the initial point x = x $x={\mathbf{x}}$ and using repeated calls to nag_roots_contfn_interval_rcomm (c05av). If this search succeeds, then the zero is determined to a user-specified accuracy by a call to nag_roots_contfn_brent (c05ay). The specifications of functions nag_roots_contfn_interval_rcomm (c05av) and nag_roots_contfn_brent (c05ay) should be consulted for details of the methods used.
The approximation x$x$ to the zero α$\alpha$ is determined so that at least one of the following criteria is satisfied:
 (i) |x − α| ≤ eps $|x-\alpha |\le {\mathbf{eps}}$, (ii) |f(x)| ≤ eta $|f\left(x\right)|\le {\mathbf{eta}}$.

## References

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

## Parameters

### Compulsory Input Parameters

1:     x – double scalar
An initial approximation to the zero.
2:     h – double scalar
A step length for use in the binary search for an interval containing the zero. The maximum interval searched is [x256.0 × h,x + 256.0 × h] $\left[{\mathbf{x}}-256.0×{\mathbf{h}},{\mathbf{x}}+256.0×{\mathbf{h}}\right]$.
Constraint: ${\mathbf{h}}$ must be sufficiently large that x + hx ${\mathbf{x}}+{\mathbf{h}}\ne {\mathbf{x}}$ on the computer.
3:     eps – double scalar
The termination tolerance on x$x$ (see Section [Description]).
Constraint: eps > 0.0 ${\mathbf{eps}}>0.0$.
4:     eta – double scalar
A value such that if |f(x)|eta $|f\left(x\right)|\le {\mathbf{eta}}$, x$x$ is accepted as the zero. eta may be specified as 0.0$0.0$ (see Section [Accuracy]).
5:     f – function handle or string containing name of m-file
f must evaluate the function f$f$ whose zero is to be determined.
[result, user] = f(x, user)

Input Parameters

1:     x – double scalar
The point at which the function must be evaluated.
2:     user – Any MATLAB object
f is called from nag_roots_contfn_brent_interval (c05au) with the object supplied to nag_roots_contfn_brent_interval (c05au).

Output Parameters

1:     result – double scalar
The result of the function.
2:     user – Any MATLAB object

### Optional Input Parameters

1:     user – Any MATLAB object
user is not used by nag_roots_contfn_brent_interval (c05au), but is passed to f. Note that for large objects it may be more efficient to use a global variable which is accessible from the m-files than to use user.

iuser ruser

### Output Parameters

1:     x – double scalar
If ${\mathbf{ifail}}={\mathbf{0}}$ or 4${\mathbf{4}}$, x is the final approximation to the zero.
If ${\mathbf{ifail}}={\mathbf{3}}$, x is likely to be a pole of f(x)$f\left(x\right)$.
Otherwise, x contains no useful information.
2:     a – double scalar
3:     b – double scalar
The lower and upper bounds respectively of the interval resulting from the binary search. If the zero is determined exactly such that f(x) = 0.0 $f\left(x\right)=0.0$ or is determined so that |f(x)|eta $|f\left(x\right)|\le {\mathbf{eta}}$ at any stage in the calculation, then on exit a = b = x ${\mathbf{a}}={\mathbf{b}}=x$.
4:     user – Any MATLAB object
5:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

ifail = 1${\mathbf{ifail}}=1$
Constraint: eps > 0.0${\mathbf{eps}}>0.0$.
Constraint: x + hx${\mathbf{x}}+{\mathbf{h}}\ne {\mathbf{x}}$ (to machine accuracy).
ifail = 2${\mathbf{ifail}}=2$
An interval containing the zero could not be found. Increasing h and calling nag_roots_contfn_brent_interval (c05au) again will increase the range searched for the zero. Decreasing h and calling nag_roots_contfn_brent_interval (c05au) again will refine the mesh used in the search for the zero.
W ifail = 3${\mathbf{ifail}}=3$
Solution may be a pole rather than a zero.
W ifail = 4${\mathbf{ifail}}=4$
The tolerance eps has been set too small for the problem being solved.

## Accuracy

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 eta = 0.0 ${\mathbf{eta}}=0.0$ and to use eps to control the accuracy, unless you have considerable knowledge of the size of f(x) $f\left(x\right)$ for values of x$x$ near the zero.

The time taken by nag_roots_contfn_brent_interval (c05au) depends primarily on the time spent evaluating f (see Section [Parameters]). 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 × eps$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 nag_roots_contfn_interval_rcomm (c05av) followed by nag_roots_contfn_brent_rcomm (c05az) 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 functions are more flexible than the direct communication of f required by nag_roots_contfn_brent_interval (c05au).
If the iteration terminates with successful exit and a = b = x ${\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$f$ at the point x, preferably analytically, or, if this is not possible, numerically, perhaps by using a central difference estimate. If f(x) = 0.0 ${f}^{\prime }\left({\mathbf{x}}\right)=0.0$, then x must correspond to a multiple zero of f$f$ rather than a simple zero.

## Example

```function nag_roots_contfn_brent_interval_example
x = 1;
h = 0.1;
eps = 1e-5;
eta = 0;
[xOut, a, b, user, ifail] = nag_roots_contfn_brent_interval(x, h, eps, eta, @f)

function [result, user] = f(x, user)
result = x - exp(-x);
```
```

xOut =

0.5671

a =

0.5000

b =

0.9000

user =

0

ifail =

0

```
```function c05au_example
x = 1;
h = 0.1;
eps = 1e-5;
eta = 0;
[xOut, a, b, user, ifail] = c05au(x, h, eps, eta, @f)

function [result, user] = f(x, user)
result = x - exp(-x);
```
```

xOut =

0.5671

a =

0.5000

b =

0.9000

user =

0

ifail =

0

```