# NAG CPP Interfacenagcpp::roots::contfn_brent (c05ay)

Settings help

CPP Name Style:

## 1Purpose

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.

## 2Specification

```#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)```

## 3Description

contfn_brent 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 c05azf (no CPP interface) 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:
1. (i)$|x-\alpha |\le {\mathbf{eps}}$,
2. (ii)$|f\left(x\right)|\le {\mathbf{eta}}$.
Brent R P (1973) Algorithms for Minimization Without Derivatives Prentice–Hall

## 5Arguments

1: $\mathbf{a}$double Input
On entry: $a$, the lower bound of the interval.
2: $\mathbf{b}$double Input
On entry: $b$, the upper bound of the interval.
Constraint: ${\mathbf{b}}\ne {\mathbf{a}}$.
3: $\mathbf{f}$double Function
f must evaluate the function $f$ whose zero is to be determined.
`double f(const double x)`
1: $\mathbf{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: $\mathbf{x}$double Output
On exit: if $\mathbf{errorid}={\mathbf{0}}$ or ${\mathbf{2}}$, x is the final approximation to the zero. If $\mathbf{errorid}={\mathbf{3}}$, x is likely to be a pole of $f\left(x\right)$. Otherwise, x contains no useful information.
5: $\mathbf{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*\mathbit{machine precision}$
On entry: the termination tolerance on $x$ (see Section 3).
Constraint: ${\mathbf{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\left(x\right)|\le {\mathbf{eta}}$, $x$ is accepted as the zero. eta may be specified as $0.0$ (see Section 7).

## 6Exceptions 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
$\mathbf{errorid}=1$
On entry, ${\mathbf{eps}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{eps}}>0.0$.
$\mathbf{errorid}=1$
On entry, ${\mathbf{a}}=⟨\mathit{value}⟩$ and ${\mathbf{b}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{a}}\ne {\mathbf{b}}$.
$\mathbf{errorid}=1$
On entry, ${\mathbf{f}}\left({\mathbf{a}}\right)$ and ${\mathbf{f}}\left({\mathbf{b}}\right)$ have the same sign with neither equalling $0.0$:
${\mathbf{f}}\left({\mathbf{a}}\right)=⟨\mathit{value}⟩$ and ${\mathbf{f}}\left({\mathbf{b}}\right)=⟨\mathit{value}⟩$.
$\mathbf{errorid}=-99$
An unexpected error has been triggered by this routine.
$\mathbf{errorid}=-399$
Your licence key may have expired or may not have been installed correctly.
$\mathbf{errorid}=-999$
Dynamic memory allocation failed.
Raises: WarningException
$\mathbf{errorid}=2$
No further improvement in the solution is possible.
eps is too small: ${\mathbf{eps}}=⟨\mathit{value}⟩$.
The final value of x returned is an accurate approximation to the zero.
$\mathbf{errorid}=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.
Raises: CallbackException
$\mathbf{errorid}=10701$
An exception was thrown in a callback.

## 7Accuracy

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{errorid}={\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.

## 8Parallelism and Performance

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

## 9Further 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×{\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 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.

## 10Example

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}}=1.0E-5$.

### 10.1Example Program

Source File Data Results
ex_c05ay.cpp None ex_c05ay.r