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_contfn_cntin (c05aw)

## Purpose

nag_roots_contfn_cntin (c05aw) attempts to locate a zero of a continuous function using a continuation method based on a secant iteration.

## Syntax

[x, user, ifail] = c05aw(x, eps, eta, f, nfmax, 'user', user)
[x, user, ifail] = nag_roots_contfn_cntin(x, eps, eta, f, nfmax, 'user', user)

## Description

nag_roots_contfn_cntin (c05aw) attempts to obtain an approximation to a simple zero $\alpha$ of the function $f\left(x\right)$ given an initial approximation $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$ to the zero $\alpha$ is determined so that at least one of the following criteria is satisfied:
 (i) $\left|x-\alpha \right|\sim {\mathbf{eps}}$, (ii) $\left|f\left(x\right)\right|<{\mathbf{eta}}$.

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}$ – double scalar
An initial approximation to the zero.
2:     $\mathrm{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 $\left|{\mathbf{x}}-\alpha \right|<{\mathbf{eps}}$. You are advised to call the function with more than one value for eps to check the accuracy obtained.
Constraint: ${\mathbf{eps}}>0.0$.
3:     $\mathrm{eta}$ – double scalar
A value such that if $\left|f\left(x\right)\right|<{\mathbf{eta}}$, $x$ is accepted as the zero. eta may be specified as $0.0$ (see Accuracy).
4:     $\mathrm{f}$ – function handle or string containing name of m-file
f must evaluate the function $f$ whose zero is to be determined.
[result, user] = f(x, user)

Input Parameters

1:     $\mathrm{x}$ – double scalar
The point at which the function must be evaluated.
2:     $\mathrm{user}$ – Any MATLAB object
f is called from nag_roots_contfn_cntin (c05aw) with the object supplied to nag_roots_contfn_cntin (c05aw).

Output Parameters

1:     $\mathrm{result}$ – double scalar
The value of $f$ evaluated at x.
2:     $\mathrm{user}$ – Any MATLAB object
5:     $\mathrm{nfmax}$int64int32nag_int scalar
The maximum permitted number of calls to f from nag_roots_contfn_cntin (c05aw). If f is inexpensive to evaluate, nfmax should be given a large value (say $\text{}>1000$).
Constraint: ${\mathbf{nfmax}}>0$.

### Optional Input Parameters

1:     $\mathrm{user}$ – Any MATLAB object
user is not used by nag_roots_contfn_cntin (c05aw), but is passed to f. Note that for large objects it may be more efficient to use a global variable which is accessible from the m-files than to use user.

### Output Parameters

1:     $\mathrm{x}$ – double scalar
The final approximation to the zero, unless ${\mathbf{ifail}}={\mathbf{1}}$, ${\mathbf{2}}$ or ${\mathbf{5}}$, in which case it contains no useful information.
2:     $\mathrm{user}$ – Any MATLAB object
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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:
${\mathbf{ifail}}=1$
Constraint: ${\mathbf{eps}}>0.0$.
Constraint: ${\mathbf{nfmax}}>0$.
${\mathbf{ifail}}=2$
Internal scale factor invalid for this problem. Consider using nag_roots_contfn_cntin_rcomm (c05ax) instead and setting scal.
${\mathbf{ifail}}=3$
Either f has no zero near x or too much accuracy has been requested. Check the coding of f or increase eps.
${\mathbf{ifail}}=4$
More than nfmax calls have been made to f.
nfmax may be too small for the problem (because x is too far away from the zero), or f has no zero near x, or too much accuracy has been requested in calculating the zero. Increase nfmax, check the coding of f or increase eps.
${\mathbf{ifail}}=5$
A serious error occurred in an internal call to an auxiliary function.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## 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 ${\mathbf{4}}$, 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.

The time taken by nag_roots_contfn_cntin (c05aw) depends primarily on the time spent evaluating the function $f$ (see Arguments) and on how close the initial value of x is to the zero.
If a more flexible way of specifying the function $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_contfn_cntin (c05aw).

## Example

This example calculates the zero of $f\left(x\right)={e}^{-x}-x$ from a starting value ${\mathbf{x}}=1.0$. Two calculations are made with ${\mathbf{eps}}=\text{1.0e−3}$ and $\text{1.0e−4}$ for comparison purposes, with ${\mathbf{eta}}=0.0$ in both cases.
```function c05aw_example

fprintf('c05aw example results\n\n');

x = 1;
eta = 0;
nfmax = int64(200);
fprintf('\n');
% Repeat with tolerance eps set to varying powers of 10
for k=3:4
[xOut, user, ifail] = c05aw(x, 10^-k, eta, @f, nfmax);
switch ifail
case {0}
fprintf('With eps = %10.2e, root = %14.5f\n', 10^-k, xOut);
case {3, 4}
fprintf('With eps = %10.2e, final value = %14.5f\n', 10^-k, xOut);
otherwise
break;
end
end

function [result, user] = f(x, user)
result = x - exp(-x);
```
```c05aw example results

With eps =   1.00e-03, root =        0.56715
With eps =   1.00e-04, root =        0.56715
```