NAG Library Routine Document
e04bbf
(one_var_deriv_old)
e04bba (one_var_deriv)
1
Purpose
e04bbf/e04bba searches for a minimum, in a given finite interval, of a continuous function of a single variable, using function and first derivative values. The method (based on cubic interpolation) is intended for functions which have a continuous first derivative (although it will usually work if the derivative has occasional discontinuities).
e04bba is a version of
e04bbf that has additional arguments in order to make it safe for use in multithreaded applications (see
Section 5).
2
Specification
2.1
Specification for e04bbf
Fortran Interface
Integer, Intent (Inout)  :: 
maxcal,
ifail  Real (Kind=nag_wp), Intent (Inout)  :: 
e1,
e2,
a,
b  Real (Kind=nag_wp), Intent (Out)  :: 
x,
f,
g  External  :: 
funct 

C Header Interface
#include nagmk26.h
void 
e04bbf_ (
void (NAG_CALL *funct)(
const double *xc,
double *fc,
double *gc),
double *e1,
double *e2,
double *a,
double *b,
Integer *maxcal,
double *x,
double *f,
double *g,
Integer *ifail) 

2.2
Specification for e04bba
Fortran Interface
Subroutine e04bba ( 
funct,
e1,
e2,
a,
b,
maxcal,
x,
f,
g,
iuser,
ruser,
ifail) 
Integer, Intent (Inout)  :: 
maxcal,
iuser(*),
ifail  Real (Kind=nag_wp), Intent (Inout)  :: 
e1,
e2,
a,
b,
ruser(*)  Real (Kind=nag_wp), Intent (Out)  :: 
x,
f,
g  External  :: 
funct 

C Header Interface
#include nagmk26.h
void 
e04bba_ (
void (NAG_CALL *funct)(
const double *xc,
double *fc,
double *gc,
Integer iuser[],
double ruser[]),
double *e1,
double *e2,
double *a,
double *b,
Integer *maxcal,
double *x,
double *f,
double *g,
Integer iuser[],
double ruser[],
Integer *ifail) 

3
Description
e04bbf/e04bba is applicable to problems of the form:
when the first derivative
$\frac{dF}{dx}$ can be calculated. The routine 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 cubicinterpolation method described in
Gill and Murray (1973).
You must supply a
funct to evaluate
$F\left(x\right)$ and
$\frac{dF}{dx}$. The arguments
e1 and
e2 together specify the accuracy
to which the position of the minimum is required. Note that
funct is never called at a 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, e04bbf/e04bba will normally find one of the minima.
4
References
Gill P E and Murray W (1973) Safeguarded steplength algorithms for optimization using descent methods NPL Report NAC 37 National Physical Laboratory
5
Arguments
 1: $\mathbf{funct}$ – Subroutine, supplied by the user.External Procedure

You must supply this routine to calculate the values of $F\left(x\right)$ and $\frac{dF}{dx}$ at any point $x$ in $\left[a,b\right]$.
It should be tested separately before being used in conjunction with e04bbf/e04bba.
The specification of
funct
for
e04bbf is:
Fortran Interface
Subroutine funct ( 
xc,
fc,
gc) 
Real (Kind=nag_wp), Intent (In)  :: 
xc  Real (Kind=nag_wp), Intent (Out)  :: 
fc,
gc 

C Header Interface
#include nagmk26.h
void 
funct (
const double *xc,
double *fc,
double *gc) 

The specification of
funct
for
e04bba is:
Fortran Interface
Integer, Intent (Inout)  :: 
iuser(*)  Real (Kind=nag_wp), Intent (In)  :: 
xc  Real (Kind=nag_wp), Intent (Inout)  :: 
ruser(*)  Real (Kind=nag_wp), Intent (Out)  :: 
fc,
gc 

C Header Interface
#include nagmk26.h
void 
funct (
const double *xc,
double *fc,
double *gc,
Integer iuser[],
double ruser[]) 

 1: $\mathbf{xc}$ – Real (Kind=nag_wp)Input

On entry: the point $x$ at which the values of $F$ and $\frac{dF}{dx}$ are required.
 2: $\mathbf{fc}$ – Real (Kind=nag_wp)Output

On exit: must be set to the value of the function $F$ at the current point $x$.
 3: $\mathbf{gc}$ – Real (Kind=nag_wp)Output

On exit: must be set to the value of the first derivative $\frac{dF}{dx}$ at the current point $x$.
 Note: the following are additional arguments for specific use with e04bba. Users of e04bbf therefore need not read the remainder of this description.
 4: $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace
 5: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

funct is called with the arguments
iuser and
ruser as supplied to
e04bbf/e04bba. You should use the arrays
iuser and
ruser to supply information to
funct.
funct must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which
e04bbf/e04bba is called. Arguments denoted as
Input must
not be changed by this procedure.
Note: funct should not return floatingpoint NaN (Not a Number) or infinity values, since these are not handled by
e04bbf/e04bba. If your code inadvertently
does return any NaNs or infinities,
e04bbf/e04bba is likely to produce unexpected results.
 2: $\mathbf{e1}$ – Real (Kind=nag_wp)Input/Output

On entry: 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.
On exit: 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.
 3: $\mathbf{e2}$ – Real (Kind=nag_wp)Input/Output

On entry: the absolute accuracy to which the position of a minimum is required.
e2 should be no smaller than
$2\epsilon $.
On exit: if you set
e2 to
$0.0$ (or to any value less than
$\epsilon $),
e2 will be reset to the default value
$\sqrt{\epsilon}$.
 4: $\mathbf{a}$ – Real (Kind=nag_wp)Input/Output

On entry: the lower bound $a$ of the interval containing a minimum.
On exit: an improved lower bound on the position of the minimum.
 5: $\mathbf{b}$ – Real (Kind=nag_wp)Input/Output

On entry: the upper bound $b$ of the interval containing a minimum.
On exit: an improved upper bound on the position of the minimum.
 6: $\mathbf{maxcal}$ – IntegerInput/Output

On entry: the maximum number of calls of
funct to be allowed.
Constraint:
${\mathbf{maxcal}}\ge 2$. (Few problems will require more than
$20$.)
There will be an error exit (see
Section 6) after
maxcal calls of
funct
On exit: the total number of times that
funct was actually called.
 7: $\mathbf{x}$ – Real (Kind=nag_wp)Output

On exit: the estimated position of the minimum.
 8: $\mathbf{f}$ – Real (Kind=nag_wp)Output

On exit: the function value at the final point given in
x.
 9: $\mathbf{g}$ – Real (Kind=nag_wp)Output

On exit: the value of the first derivative at the final point in
x.
 10: $\mathbf{ifail}$ – IntegerInput/Output

Note: for e04bba, ifail does not occur in this position in the argument list. See the additional arguments described below.
On entry:
ifail must be set to
$0$,
$1\text{ or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{ or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if
${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit, the recommended value is
$1$.
When the value $\mathbf{1}\text{ or}1$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
 Note: the following are additional arguments for specific use with e04bba. Users of e04bbf therefore need not read the remainder of this description.
 10: $\mathbf{iuser}\left(*\right)$ – Integer arrayUser Workspace
 11: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser Workspace

iuser and
ruser are not used by
e04bbf/e04bba, but are passed directly to
funct and may be used to pass information to this routine.
 12: $\mathbf{ifail}$ – IntegerInput/Output

Note: see the argument description for
ifail above.
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Note: e04bbf/e04bba may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry,  $\left({\mathbf{a}}+{\mathbf{e2}}\right)\ge {\mathbf{b}}$, 
or  ${\mathbf{maxcal}}<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
e04bbf/e04bba (preferably with the values of
a and
b given on exit from the previous call of
e04bbf/e04bba).
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
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}}\times \leftx\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\times \mathit{Tol}\left(x\right)$.
8
Parallelism and Performance
e04bbf/e04bba is not threaded in any implementation.
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)$ and
$\frac{dF}{dx}$ 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]$, e04bbf/e04bba will determine an approximation $x$ (and improved bounds $a$ and $b$) for one of the minima.
If
e04bbf/e04bba finds an
$x$ such that
$F\left(x{\delta}_{1}\right)>F\left(x\right)<F\left(x+{\delta}_{2}\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 subroutine. Therefore
funct should be programmed to calculate
$F\left(x\right)$ as accurately as possible, so that
e04bbf/e04bba will not be liable to find a spurious minimum. (For similar reasons,
$\frac{dF}{dx}$ should be evaluated as accurately as possible.)
10
Example
A sketch of the function
shows that it has a minimum somewhere in the range
$\left[3.5,5.0\right]$. The following program shows how
e04bbf/e04bba can be used to obtain a good approximation to the position of a minimum.
10.1
Program Text
Note: the following programs illustrate the use of e04bbf and e04bba.
Program Text (e04bbfe.f90)
Program Text (e04bbae.f90)
10.2
Program Data
None.
10.3
Program Results
Program Results (e04bbfe.r)
Program Results (e04bbae.r)