NAG CPP Interface
nagcpp::roots::contfn_brent (c05ay)

Settings help

CPP Name Style:



1 Purpose

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) × f(b) 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:
  1. (i) |x-α| eps ,
  2. (ii) |f(x)|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: ba .
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 or 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:
epsdouble
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 .
etadouble
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)|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 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×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.

10 Example

This example calculates an approximation to the zero of e-x - x within the interval [0,1] using a tolerance of eps=1.0E−5.

10.1 Example Program

Source File Data Results
ex_c05ay.cpp None ex_c05ay.r