# NAG FL Interfacee04bbf  (one_var_deriv_old)e04bba (one_var_deriv)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

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).

## 2Specification

### 2.1Specification for e04bbf

Fortran Interface
 Subroutine e04bbf ( e1, e2, a, b, x, f, g,
 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
#include <nag.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.2Specification for e04bba

Fortran Interface
 Subroutine e04bba ( e1, e2, a, b, x, f, g,
 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
#include <nag.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)

## 3Description

e04bbf/​e04bba is applicable to problems of the form:
 $Minimize⁡F(x) subject to a≤x≤b$
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 cubic-interpolation 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
 $Tol(x)=e1×|x|+e2$
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.
Gill P E and Murray W (1973) Safeguarded steplength algorithms for optimization using descent methods NPL Report NAC 37 National Physical Laboratory

## 5Arguments

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
 void funct (const double *xc, double *fc, double *gc)
The specification of funct for e04bba is:
Fortran Interface
 Subroutine funct ( xc, fc, gc,
 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
 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 array User Workspace
5: $\mathbf{ruser}\left(*\right)$Real (Kind=nag_wp) array User 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 floating-point 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}$Integer Input/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}$Integer Input/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$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $-1$ is recommended since useful values can be provided in some output arguments even when ${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit. When the value $-\mathbf{1}$ or $\mathbf{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 array User Workspace
11: $\mathbf{ruser}\left(*\right)$Real (Kind=nag_wp) array User 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}$Integer Input/Output
Note: see the argument description for ifail above.

## 6Error 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).
Errors or warnings detected by the routine:
Note: in some cases e04bbf/​e04bba may return useful information.
${\mathbf{ifail}}=1$
On entry, ${\mathbf{a}}+{\mathbf{e2}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{b}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{a}}+{\mathbf{e2}}<{\mathbf{b}}$.
On entry, ${\mathbf{maxcal}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{maxcal}}\ge 2$.
${\mathbf{ifail}}=2$
The maximum number of function calls, $⟨\mathit{\text{value}}⟩$, have been performed. This may have happened simply because maxcal was set too small for the particular problem, or may be due to a mistake in the user-supplied function 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 to e04bbf/​e04bba).
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

If $F\left(x\right)$ is $\delta$-unimodal for some $\delta <\mathit{Tol}\left(x\right)$, where $\mathit{Tol}\left(x\right)={\mathbf{e1}}×|x|+{\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)$.

## 8Parallelism 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) 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.)

## 10Example

A sketch of the function
 $F(x)=sin⁡xx$
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.1Program Text

Note: the following programs illustrate the use of e04bbf and e04bba.
Program Text (e04bbfe.f90)
Program Text (e04bbae.f90)

None.

### 10.3Program Results

Program Results (e04bbfe.r)
Program Results (e04bbae.r)