NAG C Library Function Document

nag_opt_one_var_deriv (e04bbc)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{funct}$ – function, supplied by the userExternal 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}$ – doubleInput

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 nag_opt_one_var_deriv (e04bbc) these pointers may be allocated memory and initialized with various quantities for use by funct when called from nag_opt_one_var_deriv (e04bbc).

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

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

2:    $\mathbf{e1}$ – doubleInput

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}$ – doubleInput

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 nag_opt_one_var_deriv (e04bbc).

6:    $\mathbf{max\_fun}$ – IntegerInput

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

The number of calls to funct actually made by nag_opt_one_var_deriv (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.3.1.1 in How to Use the NAG Library and its Documentation).

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 nag_opt_one_var_deriv (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 3.7 in How to Use the NAG Library and its Documentation).

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 nag_opt_one_var_deriv (e04bbc) (preferably with the values of a and b given on exit from the previous call to nag_opt_one_var_deriv (e04bbc)).

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (e04bbce.c)

10.2

Program Data

10.3

Program Results

Program Results (e04bbce.r)