NAG FL Interface
e04bbf  (one_var_deriv_old)
e04bba (one_var_deriv)

1 Purpose

2 Specification

2.1 Specification for e04bbf

2.2 Specification for e04bba

3 Description

4 References

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 $[a,b]$.

It should be tested separately before being used in conjunction with e04bbf/​e04bba.

The specification of funct for e04bbf is:

Fortran Interface copy

Subroutine funct ( xc, fc, gc) Real (Kind=nag_wp), Intent (In) :: xc Real (Kind=nag_wp), Intent (Out) :: fc, gc

C Header Interface copy

void  funct (const double *xc, double *fc, double *gc)

C++ Header Interface copy

#include <nag.h> extern "C" { void  funct (const double &xc, double &fc, double &gc) }

The specification of funct for e04bba is:

Fortran Interface copy

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 copy

void  funct (const double *xc, double *fc, double *gc, Integer iuser[], double ruser[])

C++ Header Interface copy

#include <nag.h> extern "C" { 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.

6 Error Indicators and Warnings

$\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$

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.

$\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.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results