NAG FL Interface
e04bbf  (one_var_deriv_old)
e04bba (one_var_deriv)

Settings help

FL Name Style:


FL Specification Language:


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
Subroutine e04bbf ( funct, e1, e2, a, b, maxcal, x, f, g, ifail)
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 <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.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 <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)

3 Description

e04bbf/​e04bba is applicable to problems of the form:
MinimizeF(x)  subject to  axb  
when the first derivative dF dx can be calculated. The routine normally computes a sequence of x values which tend in the limit to a minimum of F(x) subject to the given bounds. It also progressively reduces the interval [a,b] 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(x) and 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 Tol(x) to a previous point.
If the original interval [a,b] 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: funct Subroutine, supplied by the user. External Procedure
You must supply this routine to calculate the values of F(x) and dF dx at any point x in [a,b].
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
void  funct (const double *xc, double *fc, double *gc)
The specification of funct for e04bba is:
Fortran Interface
Subroutine funct ( xc, fc, gc, iuser, ruser)
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
void  funct (const double *xc, double *fc, double *gc, Integer iuser[], double ruser[])
1: xc Real (Kind=nag_wp) Input
On entry: the point x at which the values of F and dF dx are required.
2: fc Real (Kind=nag_wp) Output
On exit: must be set to the value of the function F at the current point x.
3: gc Real (Kind=nag_wp) Output
On exit: must be set to the value of the first derivative 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: iuser(*) Integer array User Workspace
5: ruser(*) 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: 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ε, and preferably not much less than ε, where ε is the machine precision.
On exit: if you set e1 to 0.0 (or to any value less than ε), e1 will be reset to the default value ε before starting the minimization process.
3: 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ε.
On exit: if you set e2 to 0.0 (or to any value less than ε), e2 will be reset to the default value ε.
4: 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: 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: maxcal Integer Input/Output
On entry: the maximum number of calls of funct to be allowed.
Constraint: maxcal2. (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: x Real (Kind=nag_wp) Output
On exit: the estimated position of the minimum.
8: f Real (Kind=nag_wp) Output
On exit: the function value at the final point given in x.
9: g Real (Kind=nag_wp) Output
On exit: the value of the first derivative at the final point in x.
10: 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 ifail0 on exit. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=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: iuser(*) Integer array User Workspace
11: ruser(*) 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: ifail Integer Input/Output
Note: see the argument description for ifail above.

6 Error Indicators and Warnings

If on entry 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.
ifail=1
On entry, a+e2=value and b=value.
Constraint: a+e2<b.
On entry, maxcal=value.
Constraint: maxcal2.
ifail=2
The maximum number of function calls, 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).
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
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.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

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

8 Parallelism and Performance

e04bbf/​e04bba is not threaded in any implementation.

9 Further Comments

Timing depends on the behaviour of F(x), the accuracy demanded and the length of the interval [a,b]. Unless F(x) and dF dx can be evaluated very quickly, the run time will usually be dominated by the time spent in funct.
If F(x) has more than one minimum in the original interval [a,b], 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(x-δ1)>F(x)<F(x+δ2) for some δ1,δ2Tol(x), the interval [x-δ1,x+δ2] will be regarded as containing a minimum, even if F(x) is less than F(x-δ1) and F(x+δ2) only due to rounding errors in the subroutine. Therefore, funct should be programmed to calculate F(x) as accurately as possible, so that e04bbf/​e04bba will not be liable to find a spurious minimum. (For similar reasons, dF dx should be evaluated as accurately as possible.)

10 Example

A sketch of the function
F(x)=sinxx  
shows that it has a minimum somewhere in the range [3.5,5.0]. 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)