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:
 MinimizeF(x)  subject to  a ≤ x ≤ b. $Minimize⁡F(x) subject to a≤x≤b.$
It normally computes a sequence of x$x$ values which tend in the limit to a minimum of F(x)$F\left(x\right)$ subject to the given bounds. It also progressively reduces the interval [a,b]$\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(x)$F\left(x\right)$. The parameters e1 and e2 together specify the accuracy
 Tol(x) = e1 × |x| + e2 $Tol(x)=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 Tol(x)$\mathit{Tol}\left(x\right)$ to a previous point.
If the original interval [a,b]$\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:     funct – function handle or string containing name of m-file
You must supply this function to calculate the value of the function F(x)$F\left(x\right)$ at any point x$x$ in [a,b]$\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:     xc – double scalar
The point x$x$ at which the value of F$F$ is required.
2:     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:     fc – double scalar
Must be set to the value of the function F$F$ at the current point x$x$.
2:     user – Any MATLAB object
2:     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$x$ is automatically taken into account.)
e1 should be no smaller than 2ε$2\epsilon$, and preferably not much less than sqrt(ε)$\sqrt{\epsilon }$, where ε$\epsilon$ is the machine precision.
3:     e2 – double scalar
The absolute accuracy to which the position of a minimum is required. e2 should be no smaller than 2ε$2\epsilon$.
4:     a – double scalar
The lower bound a$a$ of the interval containing a minimum.
5:     b – double scalar
The upper bound b$b$ of the interval containing a minimum.
6:     maxcal – int64int32nag_int scalar
The maximum number of calls of F(x)$F\left(x\right)$ to be allowed.
Constraint: maxcal3${\mathbf{maxcal}}\ge 3$. (Few problems will require more than 30$30$.)
There will be an error exit (see Section [Error Indicators and Warnings]) after maxcal calls of funct

### Optional Input Parameters

1:     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.

iuser ruser

### Output Parameters

1:     e1 – double scalar
If you set e1 to 0.0$0.0$ (or to any value less than ε$\epsilon$), e1 will be reset to the default value sqrt(ε)$\sqrt{\epsilon }$ before starting the minimization process.
2:     e2 – double scalar
If you set e2 to 0.0$0.0$ (or to any value less than ε$\epsilon$), e2 will be reset to the default value sqrt(ε)$\sqrt{\epsilon }$.
3:     a – double scalar
An improved lower bound on the position of the minimum.
4:     b – double scalar
An improved upper bound on the position of the minimum.
5:     maxcal – int64int32nag_int scalar
The total number of times that funct was actually called.
6:     x – double scalar
The estimated position of the minimum.
7:     f – double scalar
The function value at the final point given in x.
8:     user – Any MATLAB object
9:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = 1${\mathbf{ifail}}=1$
 On entry, (a + e2) ≥ b$\left({\mathbf{a}}+{\mathbf{e2}}\right)\ge {\mathbf{b}}$, or maxcal < 3${\mathbf{maxcal}}<3$,
ifail = 2${\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)).

## Accuracy

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

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

```function nag_opt_one_var_func_example
e1 = 0;
e2 = 0;
a = 3.5;
b = 5;
maxcal = int64(30);
[e1Out, e2Out, aOut, bOut, maxcalOut, x, f, user, ifail] = ...
nag_opt_one_var_func(@funct, e1, e2, a, b, maxcal)

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

e1Out =

1.0537e-08

e2Out =

1.0537e-08

aOut =

4.4934

bOut =

4.4934

maxcalOut =

10

x =

4.4934

f =

-0.2172

user =

0

ifail =

0

```
```function e04ab_example
e1 = 0;
e2 = 0;
a = 3.5;
b = 5;
maxcal = int64(30);
[e1Out, e2Out, aOut, bOut, maxcalOut, x, f, user, ifail] = ...
e04ab(@funct, e1, e2, a, b, maxcal)

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

e1Out =

1.0537e-08

e2Out =

1.0537e-08

aOut =

4.4934

bOut =

4.4934

maxcalOut =

10

x =

4.4934

f =

-0.2172

user =

0

ifail =

0

```