NAG CL Interface
e04bbc (one_​var_​deriv)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{funct}$ – function, supplied by the user External Function

funct must calculate the values of $F\left(x\right)$ and $dF/dx$ at any point $x$ in $\left[a,b\right]$.

The specification of funct is:

void  funct (double xc, double *fc, double *gc, Nag_Comm *comm)

1: $\mathbf{xc}$ – double Input

On entry: $x$, the point at which the values of $F$ and $dF/dx$ are required.

2: $\mathbf{fc}$ – double * Output

On exit: the value of the function $F$ at the current point $x$.

3: $\mathbf{gc}$ – double * Output

On exit: the value of the first derivative $dF/dx$ at the current point $x$.

4: $\mathbf{comm}$ – Nag_Comm *

Pointer to structure of type Nag_Comm; the following members are relevant to funct.

first – Nag_BooleanInput

On entry: will be set to Nag_TRUE on the first call to funct and Nag_FALSE for all subsequent calls.

nf – IntegerInput

On entry: the number of calls made to funct so far.

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void * with a C compiler that defines void * and char * otherwise. Before calling e04bbc these pointers may be allocated memory and initialized with various quantities for use by funct when called from e04bbc.

Note: funct should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04bbc. If your code inadvertently does return any NaNs or infinities, e04bbc is likely to produce unexpected results.

Note: funct should be tested separately before being used in conjunction with e04bbc.

2: $\mathbf{e1}$ – double Input

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

It is recommended that e1 should be no smaller than $2\epsilon$, and preferably not much less than $\sqrt{\epsilon }$, where $\epsilon$ is the machine precision.

If e1 is set to a value less than $\epsilon$, its value is ignored and the default value of $\sqrt{\epsilon }$ is used instead. In particular, you may set $\mathbf{e1}=0.0$ to ensure that the default value is used.

3: $\mathbf{e2}$ – double Input

On entry: the absolute accuracy to which the position of a minimum is required. It is recommended that e2 should be no smaller than $2\epsilon$.

If e2 is set to a value less than $\epsilon$, its value is ignored and the default value of $\sqrt{\epsilon }$ is used instead. In particular, you may set $\mathbf{e2}=0.0$ to ensure that the default value is used.

4: $\mathbf{a}$ – double * 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}$ – double * 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.

Constraint: $\mathbf{b}>\mathbf{a}+\mathbf{e2}$.

Note that the value $\mathbf{e2}=\sqrt{\epsilon }$ applies here if $\mathbf{e2}<\epsilon$ on entry to e04bbc.

6: $\mathbf{max\_fun}$ – Integer Input

On entry: the maximum number of calls to funct which you are prepared to allow.

The number of calls to funct actually made by e04bbc may be determined by supplying a non-NULL argument comm (see below) and examining the structure member $\mathbf{comm}\mathbf{\to }\mathbf{nf}$ on exit.

Constraint: $\mathbf{max\_fun}\ge 2$

(Few problems will require more than 20 function calls.)

7: $\mathbf{x}$ – double * Output

On exit: the estimated position of the minimum.

8: $\mathbf{f}$ – double * Output

On exit: the value of $F$ at the final point x.

9: $\mathbf{g}$ – double * Output

On exit: the value of the first derivative $dF/dx$ at the final point x.

10: $\mathbf{comm}$ – Nag_Comm * Input/Output

Note: comm is a NAG defined type (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).

On entry/exit: structure containing pointers for communication to user-supplied functions; see the above description of funct for details. The number of times the function funct was called is returned in the member $\mathbf{comm}\mathbf{\to }\mathbf{nf}$.

If you do not need to make use of this communication feature, the null pointer NAGCOMM_NULL may be used in the call to e04bbc; comm will then be declared internally for use in calls to user-supplied functions.

11: $\mathbf{fail}$ – NagError * Input/Output

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_2_REAL_ARG_GE

On entry, $\mathbf{a}+\mathbf{e2}=〈\mathit{\text{value}}〉$ while $\mathbf{b}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{a}+\mathbf{e2}<\mathbf{b}$.

NE_INT_ARG_LT

On entry, max_fun must not be less than 2: $\mathbf{max\_fun}=〈\mathit{\text{value}}〉$.

NW_MAX_FUN

The maximum number of function calls, $〈\mathit{\text{value}}〉$, have been performed.

This may have happened simply because max_fun was set too small for a particular problem, or may be due to a mistake in the user-supplied function, funct. If no mistake can be found in funct, restart e04bbc (preferably with the values of a and b given on exit from the previous call to e04bbc).

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results