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

2 Specification

#include "c05/nagcpp_c05ay.hpp"

template <typename F>

void function contfn_brent(const double a, const double b, F &&f, double &x, OptionalC05AY opt)

template <typename F>

void function contfn_brent(const double a, const double b, F &&f, double &x)

3 Description

contfn_brent attempts to obtain an approximation to a simple zero of the function

f (x)

given an initial interval

[a, b]

such that

f (a) \times f (b) \leq 0

. The same core algorithm is used by c05azf (no CPP interface) whose specification should be consulted for details of the method used.

The approximation

x

to the zero

α

is determined so that at least one of the following criteria is satisfied:

(i) $| x - α | \leq eps$ ,
(ii) $| f (x) | \leq eta$ .

4 References

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

5 Arguments

1: $a$ – double Input

On entry:

a

, the lower bound of the interval.

2: $b$ – double Input

On entry:

b

, the upper bound of the interval.

Constraint:

b \neq a

3: $f$ – double Function

f must evaluate the function

f

whose zero is to be determined.

double f(const double x)

1: $x$ – double Input: On entry: the point at which the function must be evaluated.

Note: f should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by contfn_brent. If your code inadvertently does return any NaNs or infinities, contfn_brent is likely to produce unexpected results.

4: $x$ – double Output

On exit: if

errorid = 0

2

, x is the final approximation to the zero. If

errorid = 3

, x is likely to be a pole of

f (x)

. Otherwise, x contains no useful information.

5: $opt$ – OptionalC05AY Input/Output

Optional parameter container, derived from Optional.

Container for:

eps – double: This optional parameter may be set using the method OptionalC05AY::eps and accessed via OptionalC05AY::get_eps.
Default: $1000.0 * machine precision$

On entry: the termination tolerance on $x$ (see Section 3).

Constraint: $eps > 0.0$ .
eta – double: This optional parameter may be set using the method OptionalC05AY::eta and accessed via OptionalC05AY::get_eta.
Default: $0.0$

On entry: a value such that if $| f (x) | \leq eta$ , $x$ is accepted as the zero. eta may be specified as $0.0$ (see Section 7).

6 Exceptions and Warnings

Errors or warnings detected by the function:

All errors and warnings have an associated numeric error code field, errorid, stored either as a member of the thrown exception object (see errorid), or as a member of opt.ifail, depending on how errors and warnings are being handled (see Error Handling for more details).

Raises: ErrorException

$errorid = 1$: On entry, $eps = ⟨ value ⟩$ .
Constraint: $eps > 0.0$ .

$errorid = 1$: On entry, $a = ⟨ value ⟩$ and $b = ⟨ value ⟩$ .
Constraint: $a \neq b$ .

$errorid = 1$: On entry, $f (a)$ and $f (b)$ have the same sign with neither equalling $0.0$ :
$f (a) = ⟨ value ⟩$ and $f (b) = ⟨ value ⟩$ .

$errorid = −99$: An unexpected error has been triggered by this routine.

$errorid = −399$: Your licence key may have expired or may not have been installed correctly.

$errorid = −999$: Dynamic memory allocation failed.

Raises: WarningException

$errorid = 2$: No further improvement in the solution is possible.
eps is too small: $eps = ⟨ value ⟩$ .
The final value of x returned is an accurate approximation to the zero.

$errorid = 3$: The function values in the interval $[a, b]$ might contain
a pole rather than a zero. Reducing eps may help in distinguishing between
a pole and a zero.

Raises: CallbackException

$errorid = 10701$: An exception was thrown in a callback.

7 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

errorid = 2

, although this may involve many more iterations than a lesser accuracy. You are recommended to set

eta = 0.0

and to use eps to control the accuracy, unless you have considerable knowledge of the size of

f (x)

for values of

x

near the zero.

8 Parallelism and Performance

Please see the description for the underlying computational routine in this section of the FL Interface documentation.

9 Further Comments

The time taken by contfn_brent depends primarily on the time spent evaluating f (see Section 5).

If it is important to determine an interval of relative length less than

2 \times 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 c05azf (no CPP interface) is recommended. Use of c05azf (no CPP interface) 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 c05azf (no CPP interface) are more flexible than the direct communication of f required by contfn_brent.