NAG CPP Interface
nagcpp::roots::contfn_brent (c05ay)
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
given an initial interval
such that
.
The same core algorithm is used by
c05azf (no CPP interface) whose specification should be consulted for details of the method used.
The approximation
to the zero
is determined so that at least one of the following criteria is satisfied:
-
(i),
-
(ii).
4
References
Brent R P (1973) Algorithms for Minimization Without Derivatives Prentice–Hall
5
Arguments
-
1:
– double
Input
-
On entry: , the lower bound of the interval.
-
2:
– double
Input
-
On entry: , the upper bound of the interval.
Constraint:
.
-
3:
– double
Function
-
f must evaluate the function
whose zero is to be determined.
double f(const double x)
-
1:
– 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:
– double
Output
-
On exit: if
or
,
x is the final approximation to the zero. If
,
x is likely to be a pole of
. Otherwise,
x contains no useful information.
-
5:
– 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:
On entry: the termination tolerance on
(see
Section 3).
Constraint:
.
- eta – double
This optional parameter
may be set using the method
OptionalC05AY::eta
and accessed via
OptionalC05AY::get_eta.
Default:
On entry: a value such that if
,
is accepted as the zero.
eta may be specified as
(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
-
- On entry, .
Constraint: .
- On entry, and .
Constraint: .
- On entry, and have the same sign with neither equalling :
and .
- An unexpected error has been triggered by this routine.
- Your licence key may have expired or may not have been installed correctly.
- Dynamic memory allocation failed.
- Raises: WarningException
-
- No further improvement in the solution is possible.
eps is too small: .
The final value of x returned is an accurate approximation to the zero.
- The function values in the interval might contain
a pole rather than a zero. Reducing eps may help in distinguishing between
a pole and a zero.
- Raises: CallbackException
-
- 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
, although this may involve many more iterations than a lesser accuracy. You are recommended to set
and to use
eps to control the accuracy, unless you have considerable knowledge of the size of
for values of
near the zero.
8
Parallelism and Performance
Please see the description for the underlying computational routine in this section of the
FL Interface documentation.
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
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 within the interval using a tolerance of .
10.1
Example Program