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_withdraw_contfn_cntin_start (c05aj)

## Purpose

nag_roots_withdraw_contfn_cntin_start (c05aj) attempts to locate a zero of a continuous function using a continuation method based on a secant iteration.
Note: this function is scheduled to be withdrawn, please see c05aj in Advice on Replacement Calls for Withdrawn/Superseded Routines..

## Syntax

[x, ifail] = c05aj(x, eps, eta, f, nfmax)
[x, ifail] = nag_roots_withdraw_contfn_cntin_start(x, eps, eta, f, nfmax)

## Description

nag_roots_withdraw_contfn_cntin_start (c05aj) attempts to obtain an approximation to a simple zero α$\alpha$ of the function f(x) $f\left(x\right)$ given an initial approximation x$x$ to α$\alpha$. The zero is found by a call to nag_roots_contfn_cntin_rcomm (c05ax) whose specification should be consulted for details of the method used.
The approximation x$x$ to the zero α$\alpha$ is determined so that at least one of the following criteria is satisfied:
 (i) |x − α| ∼ eps $|x-\alpha |\sim {\mathbf{eps}}$, (ii) |f(x)| < eta $|f\left(x\right)|<{\mathbf{eta}}$.

None.

## Parameters

### Compulsory Input Parameters

1:     x – double scalar
An initial approximation to the zero.
2:     eps – double scalar
An absolute tolerance to control the accuracy to which the zero is determined. In general, the smaller the value of eps the more accurate x will be as an approximation to α$\alpha$. Indeed, for very small positive values of eps, it is likely that the final approximation will satisfy |xα| < eps $|{\mathbf{x}}-\alpha |<{\mathbf{eps}}$. You are advised to call the function with more than one value for eps to check the accuracy obtained.
Constraint: eps > 0.0 ${\mathbf{eps}}>0.0$.
3:     eta – double scalar
A value such that if |f(x)| < eta $|f\left(x\right)|<{\mathbf{eta}}$, x$x$ is accepted as the zero. eta may be specified as 0.0$0.0$ (see Section [Accuracy]).
4:     f – function handle or string containing name of m-file
f must evaluate the function f$f$ whose zero is to be determined.
[result] = f(xx)

Input Parameters

1:     xx – double scalar
The point at which the function must be evaluated.

Output Parameters

1:     result – double scalar
The result of the function.
5:     nfmax – int64int32nag_int scalar
The maximum permitted number of calls to f from nag_roots_withdraw_contfn_cntin_start (c05aj). If f is inexpensive to evaluate, nfmax should be given a large value (say > 1000 $\text{}>1000$).
Constraint: nfmax > 0 ${\mathbf{nfmax}}>0$.

None.

None.

### Output Parameters

1:     x – double scalar
The final approximation to the zero, unless ${\mathbf{ifail}}={\mathbf{1}}$, 2${\mathbf{2}}$ or 5${\mathbf{5}}$, in which case it contains no useful information.
2:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = 1${\mathbf{ifail}}=1$
 On entry, eps ≤ 0.0 ${\mathbf{eps}}\le 0.0$, or nfmax ≤ 0 ${\mathbf{nfmax}}\le 0$.
ifail = 2${\mathbf{ifail}}=2$
An internally calculated scale factor has the wrong order of magnitude for the problem. If this error exit occurs, you are advised to call nag_roots_contfn_cntin_rcomm (c05ax) instead where different scale values can be tried.
ifail = 3${\mathbf{ifail}}=3$
Either the function f(x) $f\left(x\right)$ given by f has no zero near x or too much accuracy has been requested in calculating the zero. The first is a more likely cause of this error exit and you should check the coding of f and make an independent investigation of its behaviour near x. The second can be alleviated by increasing eps.
ifail = 4${\mathbf{ifail}}=4$
More than nfmax calls have been made to f. This error exit can occur because nfmax is too small for the problem (essentially because x is too far away from the zero) or for either of the reasons given under ${\mathbf{ifail}}={\mathbf{3}}$ above. If nfmax is increased considerably and this error exit occurs again at approximately the same final value of x, then it is likely that one of the reasons given under ${\mathbf{ifail}}={\mathbf{3}}$ is the cause.
ifail = 5 ${\mathbf{ifail}}=5$ (nag_roots_contfn_cntin_rcomm (c05ax))
A serious error has occurred in the specified function. Check all function calls. Seek expert help.

## 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{3}}$ or 4${\mathbf{4}}$, although this may involve many more iterations than a lesser accuracy. You are recommended to set eta = 0.0 ${\mathbf{eta}}=0.0$ and to use eps to control the accuracy, unless you have considerable knowledge of the size of f(x) $f\left(x\right)$ for values of x$x$ near the zero.

The time taken by nag_roots_withdraw_contfn_cntin_start (c05aj) depends primarily on the time spent evaluating the function f$f$ (see Section [Parameters]) and on how close the initial value of x is to the zero.
If a more flexible way of specifying the function f$f$ is required or if you wish to have closer control of the calculation, then the reverse communication function nag_roots_contfn_cntin_rcomm (c05ax) is recommended instead of nag_roots_withdraw_contfn_cntin_start (c05aj).

## Example

```function nag_roots_withdraw_contfn_cntin_start_example
x = 1;
eta = 0;
nfmax = int64(200);
f = @(x) exp(-x)-x;
for k=3:4
[xOut, ifail] = nag_roots_withdraw_contfn_cntin_start(x, 10^-k, eta, f, nfmax);

if ifail == 3 || ifail == 4
fprintf('With epsilon = %10.2e, final value = %14.5f\n', 10^-k, xOut);
else
fprintf('With epsilon = %10.2e, root = %14.5f\n', 10^-k, xOut);
end
end
```
```
With epsilon =   1.00e-03, root =        0.56715
With epsilon =   1.00e-04, root =        0.56715

```
```function c05aj_example
x = 1;
eta = 0;
nfmax = int64(200);
f = @(x) exp(-x)-x;
for k=3:4
[xOut, ifail] = c05aj(x, 10^-k, eta, f, nfmax);

if ifail == 3 || ifail == 4
fprintf('With epsilon = %10.2e, final value = %14.5f\n', 10^-k, xOut);
else
fprintf('With epsilon = %10.2e, root = %14.5f\n', 10^-k, xOut);
end
end
```
```
With epsilon =   1.00e-03, root =        0.56715
With epsilon =   1.00e-04, root =        0.56715

```