NAG Library Routine Document

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

#include <nagmk26.h> 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

#include <nagmk26.h> 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 arrayUser Workspace

4:     $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser 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}$ – IntegerInput/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}$ – IntegerInput/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\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 e04aba. Users of e04abf therefore need not read the remainder of this description.

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

10:   $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) arrayUser 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}$ – IntegerInput/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 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

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (e04abfe.f90)

Program Text (e04abae.f90)

10.2

Program Data

10.3

Program Results

Program Results (e04abfe.r)

Program Results (e04abae.r)