NAG FL Interface
e04abf  (one_var_func_old)
e04aba (one_var_func)

1 Purpose

2 Specification

2.1 Specification for e04abf

2.2 Specification for e04aba

3 Description

4 References

5 Arguments

1: $\mathbf{funct}$ – Subroutine, supplied by the user. External Procedure

You must supply this routine to calculate the value of the function $F\left(x\right)$ at any point $x$ in $\left[a,b\right]$. It should be tested separately before being used in conjunction with e04abf/​e04aba.

The specification of funct for e04abf is:

Fortran Interface

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

C Header Interface

void  funct_ (const double *xc, double *fc)

C++ Header Interface

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

The specification of funct for e04aba is:

Fortran Interface

Subroutine funct ( xc, fc, 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

C Header Interface

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

C++ Header Interface

#include <nag.h> extern "C" { void  funct_ (const double &xc, double &fc, Integer iuser[], double ruser[]) }

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

On entry: the point $x$ at which the value of $F$ is 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$.

Note: the following are additional arguments for specific use with e04aba. Users of e04abf therefore need not read the remainder of this description.

3: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

4: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

funct is called with the arguments iuser and ruser as supplied to e04abf/​e04aba. 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 e04abf/​e04aba 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 e04abf/​e04aba. If your code inadvertently does return any NaNs or infinities, e04abf/​e04aba 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 $F\left(x\right)$ to be allowed.

Constraint: $\mathbf{maxcal}\ge 3$. (Few problems will require more than $30$.)

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{ifail}$ – Integer Input/Output

Note: for e04aba, 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 e04aba. Users of e04abf therefore need not read the remainder of this description.

9: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

10: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

iuser and ruser are not used by e04abf/​e04aba, but are passed directly to funct and may be used to pass information to this routine.

11: $\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}=〈\mathit{\text{value}}〉$, $\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 3$.

$\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 e04abf/​e04aba (preferably with the values of a and b given on exit from the previous call to e04abf/​e04aba).

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