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 (c05ay)

## Purpose

nag_roots_contfn_brent (c05ay) locates a simple zero of a continuous function in a given interval using Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection.

## Syntax

[x, user, ifail] = c05ay(a, b, eps, eta, f, 'user', user)
[x, user, ifail] = nag_roots_contfn_brent(a, b, eps, eta, f, 'user', user)

## Description

nag_roots_contfn_brent (c05ay) attempts to obtain an approximation to a simple zero of the function $f\left(x\right)$ given an initial interval $\left[a,b\right]$ such that $f\left(a\right)×f\left(b\right)\le 0$. The same core algorithm is used by nag_roots_contfn_brent_rcomm (c05az) whose specification should be consulted for details of the method used.
The approximation $x$ to the zero $\alpha$ is determined so that at least one of the following criteria is satisfied:
 (i) $\left|x-\alpha \right|\le {\mathbf{eps}}$, (ii) $\left|f\left(x\right)\right|\le {\mathbf{eta}}$.

## References

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{a}$ – double scalar
$a$, the lower bound of the interval.
2:     $\mathrm{b}$ – double scalar
$b$, the upper bound of the interval.
Constraint: ${\mathbf{b}}\ne {\mathbf{a}}$.
3:     $\mathrm{eps}$ – double scalar
The termination tolerance on $x$ (see Description).
Constraint: ${\mathbf{eps}}>0.0$.
4:     $\mathrm{eta}$ – double scalar
A value such that if $\left|f\left(x\right)\right|\le {\mathbf{eta}}$, $x$ is accepted as the zero. eta may be specified as $0.0$ (see Accuracy).
5:     $\mathrm{f}$ – function handle or string containing name of m-file
f must evaluate the function $f$ whose zero is to be determined.
[result, user] = f(x, user)

Input Parameters

1:     $\mathrm{x}$ – double scalar
The point at which the function must be evaluated.
2:     $\mathrm{user}$ – Any MATLAB object
f is called from nag_roots_contfn_brent (c05ay) with the object supplied to nag_roots_contfn_brent (c05ay).

Output Parameters

1:     $\mathrm{result}$ – double scalar
The value of $f$ evaluated at x.
2:     $\mathrm{user}$ – Any MATLAB object

### Optional Input Parameters

1:     $\mathrm{user}$ – Any MATLAB object
user is not used by nag_roots_contfn_brent (c05ay), 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.

### Output Parameters

1:     $\mathrm{x}$ – double scalar
If ${\mathbf{ifail}}={\mathbf{0}}$ or ${\mathbf{2}}$, 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:     $\mathrm{user}$ – Any MATLAB object
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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.

${\mathbf{ifail}}=1$
Constraint: ${\mathbf{a}}\ne {\mathbf{b}}$.
Constraint: ${\mathbf{eps}}>0.0$.
On entry, ${\mathbf{f}}\left({\mathbf{a}}\right)$ and ${\mathbf{f}}\left({\mathbf{b}}\right)$ have the same sign with neither equalling $0.0$.
W  ${\mathbf{ifail}}=2$
No further improvement in the solution is possible.
W  ${\mathbf{ifail}}=3$
The function values in the interval $\left[{\mathbf{a}},{\mathbf{b}}\right]$ might contain a pole rather than a zero. Reducing eps may help in distinguishing between a pole and a zero.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## 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{2}}$, 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.

The time taken by nag_roots_contfn_brent (c05ay) depends primarily on the time spent evaluating f (see Arguments).
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 nag_roots_contfn_brent_rcomm (c05az) is recommended. Use of nag_roots_contfn_brent_rcomm (c05az) 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 nag_roots_contfn_brent_rcomm (c05az) are more flexible than the direct communication of f required by nag_roots_contfn_brent (c05ay).

## Example

This example calculates an approximation to the zero of ${e}^{-x}-x$ within the interval $\left[0,1\right]$ using a tolerance of ${\mathbf{eps}}=\text{1.0e−5}$.
```function c05ay_example

fprintf('c05ay example results\n\n');

a = 0;
b = 1;
eps = 1e-5;
eta = 0;
fprintf('\n');
[x, user, ifail] = c05ay(a, b, eps, eta, @f);
switch ifail
case {0}
fprintf('With eps = %10.2e, root = %14.5f\n', eps, x);
case {2, 3}
fprintf('With eps = %10.2e, final value = %14.5f\n', eps, x);
end

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

With eps =   1.00e-05, root =        0.56714
```