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_opt_one_var_func (e04ab)

## Purpose

nag_opt_one_var_func (e04ab) searches for a minimum, in a given finite interval, of a continuous function of a single variable, using function values only. The method (based on quadratic interpolation) is intended for functions which have a continuous first derivative (although it will usually work if the derivative has occasional discontinuities).

## Syntax

[e1, e2, a, b, maxcal, x, f, user, ifail] = e04ab(funct, e1, e2, a, b, maxcal, 'user', user)
[e1, e2, a, b, maxcal, x, f, user, ifail] = nag_opt_one_var_func(funct, e1, e2, a, b, maxcal, 'user', user)

## Description

nag_opt_one_var_func (e04ab) is applicable to problems of the form:
 $Minimize⁡Fx subject to a≤x≤b.$
It normally computes a sequence of $x$ values which tend in the limit to a minimum of $F\left(x\right)$ subject to the given bounds. It also progressively reduces the interval $\left[a,b\right]$ in which the minimum is known to lie. It uses the safeguarded quadratic-interpolation method described in Gill and Murray (1973).
You must supply a funct to evaluate $F\left(x\right)$. The arguments e1 and e2 together specify the accuracy
 $Tolx=e1×x+e2$
to which the position of the minimum is required. Note that funct is never called at any point which is closer than $\mathit{Tol}\left(x\right)$ to a previous point.
If the original interval $\left[a,b\right]$ contains more than one minimum, nag_opt_one_var_func (e04ab) will normally find one of the minima.

## References

Gill P E and Murray W (1973) Safeguarded steplength algorithms for optimization using descent methods NPL Report NAC 37 National Physical Laboratory

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{funct}$ – function handle or string containing name of m-file
You must supply this function to calculate the value of the function $F\left(x\right)$ at any point $x$ in $\left[a,b\right]$. It should be tested separately before being used in conjunction with nag_opt_one_var_func (e04ab).
[fc, user] = funct(xc, user)

Input Parameters

1:     $\mathrm{xc}$ – double scalar
The point $x$ at which the value of $F$ is required.
2:     $\mathrm{user}$ – Any MATLAB object
funct is called from nag_opt_one_var_func (e04ab) with the object supplied to nag_opt_one_var_func (e04ab).

Output Parameters

1:     $\mathrm{fc}$ – double scalar
Must be set to the value of the function $F$ at the current point $x$.
2:     $\mathrm{user}$ – Any MATLAB object
2:     $\mathrm{e1}$ – double scalar
The relative accuracy to which the position of a minimum is required. (Note that, since e1 is a relative tolerance, the scaling of $x$ is automatically taken into account.)
e1 should be no smaller than $2\epsilon$, and preferably not much less than $\sqrt{\epsilon }$, where $\epsilon$ is the machine precision.
3:     $\mathrm{e2}$ – double scalar
The absolute accuracy to which the position of a minimum is required. e2 should be no smaller than $2\epsilon$.
4:     $\mathrm{a}$ – double scalar
The lower bound $a$ of the interval containing a minimum.
5:     $\mathrm{b}$ – double scalar
The upper bound $b$ of the interval containing a minimum.
6:     $\mathrm{maxcal}$int64int32nag_int scalar
The maximum number of calls of $F\left(x\right)$ to be allowed.
Constraint: ${\mathbf{maxcal}}\ge 3$. (Few problems will require more than $30$.)
There will be an error exit (see Error Indicators and Warnings) after maxcal calls of funct

### Optional Input Parameters

1:     $\mathrm{user}$ – Any MATLAB object
user is not used by nag_opt_one_var_func (e04ab), but is passed to funct. 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{e1}$ – double scalar
If you set e1 to $0.0$ (or to any value less than $\epsilon$), e1 will be reset to the default value $\sqrt{\epsilon }$ before starting the minimization process.
2:     $\mathrm{e2}$ – double scalar
If you set e2 to $0.0$ (or to any value less than $\epsilon$), e2 will be reset to the default value $\sqrt{\epsilon }$.
3:     $\mathrm{a}$ – double scalar
An improved lower bound on the position of the minimum.
4:     $\mathrm{b}$ – double scalar
An improved upper bound on the position of the minimum.
5:     $\mathrm{maxcal}$int64int32nag_int scalar
The total number of times that funct was actually called.
6:     $\mathrm{x}$ – double scalar
The estimated position of the minimum.
7:     $\mathrm{f}$ – double scalar
The function value at the final point given in x.
8:     $\mathrm{user}$ – Any MATLAB object
9:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Note: nag_opt_one_var_func (e04ab) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
 On entry, $\left({\mathbf{a}}+{\mathbf{e2}}\right)\ge {\mathbf{b}}$, or ${\mathbf{maxcal}}<3$,
${\mathbf{ifail}}=2$
The number of calls of funct has exceeded maxcal. This may have happened simply because maxcal was set too small for a particular problem, or may be due to a mistake in funct. If no mistake can be found in funct, restart nag_opt_one_var_func (e04ab) (preferably with the values of a and b given on exit from the previous call of nag_opt_one_var_func (e04ab)).
${\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

If $F\left(x\right)$ is $\delta$-unimodal for some $\delta <\mathit{Tol}\left(x\right)$, where $\mathit{Tol}\left(x\right)={\mathbf{e1}}×\left|x\right|+{\mathbf{e2}}$, then, on exit, $x$ approximates the minimum of $F\left(x\right)$ in the original interval $\left[a,b\right]$ with an error less than $3×\mathit{Tol}\left(x\right)$.

Timing depends on the behaviour of $F\left(x\right)$, the accuracy demanded and the length of the interval $\left[a,b\right]$. Unless $F\left(x\right)$ can be evaluated very quickly, the run time will usually be dominated by the time spent in funct.
If $F\left(x\right)$ has more than one minimum in the original interval $\left[a,b\right]$, nag_opt_one_var_func (e04ab) will determine an approximation $x$ (and improved bounds $a$ and $b$) for one of the minima.
If nag_opt_one_var_func (e04ab) finds an $x$ such that $F\left(x-{\delta }_{1}\right)>F\left(x\right) for some ${\delta }_{1},{\delta }_{2}\ge \mathit{Tol}\left(x\right)$, the interval $\left[x-{\delta }_{1},x+{\delta }_{2}\right]$ will be regarded as containing a minimum, even if $F\left(x\right)$ is less than $F\left(x-{\delta }_{1}\right)$ and $F\left(x+{\delta }_{2}\right)$ only due to rounding errors in the function. Therefore funct should be programmed to calculate $F\left(x\right)$ as accurately as possible, so that nag_opt_one_var_func (e04ab) will not be liable to find a spurious minimum.

## Example

A sketch of the function
 $Fx=sin⁡xx$
shows that it has a minimum somewhere in the range $\left[3.5,5.0\right]$. The following program shows how nag_opt_one_var_func (e04ab) can be used to obtain a good approximation to the position of a minimum.
```function e04ab_example

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

e1 = 0;
e2 = 0;
a = 3.5;
b = 5;
maxcal = int64(30);

[e1, e2, a, b, maxcal, x, f, user, ifail] = ...
e04ab( ...
@funct, e1, e2, a, b, maxcal);

fprintf('The minimum lies in the interval  [%11.8f,%11.8f]\n', a, b);
fprintf('Estimated position of minimum, x = %11.8f\n', x);
fprintf('Function value at minimum,  f(x) = %7.4f\n', f);
fprintf('Number of function evaluations   = %2d\n', maxcal);

function [fc, user] = funct(xc, user)
fc = sin(xc)/xc;
```
```e04ab example results

The minimum lies in the interval  [ 4.49340940, 4.49340951]
Estimated position of minimum, x =  4.49340945
Function value at minimum,  f(x) = -0.2172
Number of function evaluations   = 10
```