NAG CL Interface
e04hcc (check_​deriv)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{n}$ – Integer Input

On entry: the number $n$ of independent variables in the objective function.

Constraint: $\mathbf{n}\ge 1$.

2: $\mathbf{objfun}$ – function, supplied by the user External Function

objfun must evaluate the objective function and its first derivatives at a given point. (The minimization function e04kbc gives you the option of resetting an argument, $\mathbf{comm}\mathbf{\to }\mathbf{flag}$, to terminate the minimization process immediately. e04hcc will also terminate immediately, without finishing the checking process, if the argument in question is reset to a negative value.)

The specification of objfun is:

copy

void  objfun (Integer n, const double x[], double *objf, double g[], Nag_Comm *comm)

1: $\mathbf{n}$ – Integer Input

On entry: the number $n$ of variables.

2: $\mathbf{x}\left[\mathbf{n}\right]$ – const double Input

On entry: the point $x$ at which $F$ and its derivatives are required.

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

On exit: objfun must set objf to the value of the objective function $F$ at the current point $x$. If it is not possible to evaluate $F$ then objfun should assign a negative value to $\mathbf{comm}\mathbf{\to }\mathbf{flag}$; e04hcc will then terminate.

4: $\mathbf{g}\left[\mathbf{n}\right]$ – double Output

On exit: unless $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ is reset to a negative number, objfun must set $\mathbf{g}\left[j-1\right]$ to the value of the first derivative $\frac{\partial F}{\partial x_j}$ at the current point $x$ for $j=1,2,\dots ,n$

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

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

flag – IntegerInput/Output

On entry: $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ will be set to 2.

On exit: if objfun resets $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ to some negative number then e04hcc will terminate immediately with the error indicator NE_USER_STOP. If fail is supplied to e04hcc, $\mathbf{fail}\mathbf{.}\mathbf{errnum}$ will be set to your setting of $\mathbf{comm}\mathbf{\to }\mathbf{flag}$.

first – Nag_BooleanInput

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

nf – IntegerInput

On entry: the number of calculations of the objective function; this value will be equal to the number of calls made to objfun including the current one.

user – double *

iuser – Integer *

p – Pointer 

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

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

The array x must not be changed by objfun.

3: $\mathbf{x}\left[\mathbf{n}\right]$ – const double Input

On entry: $\mathbf{x}\left[\mathit{j}-1\right]$, for $\mathit{j}=1,2,\dots ,n$, must be set to the coordinates of a suitable point at which to check the derivatives calculated by objfun. ‘Obvious’ settings, such as $0.0$ or $1.0$, should not be used since, at such particular points, incorrect terms may take correct values (particularly zero), so that errors could go undetected. Similarly, it is preferable that no two elements of x should be the same.

4: $\mathbf{objf}$ – double * Output

On exit: unless you set $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ negative in the first call of objfun, objf contains the value of the objective function $F\left(x\right)$ at the point given in x.

5: $\mathbf{g}\left[\mathbf{n}\right]$ – double Output

On exit: unless you set $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ negative in the first call of objfun, $\mathbf{g}\left[\mathit{j}-1\right]$ contains the value of the derivative $\frac{\partial F}{\partial x_{\mathit{j}}}$ at the point given in x, as calculated by objfun, for $\mathit{j}=1,2,\dots ,n$.

6: $\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 with the user-defined function; see the above description of objfun for details. If you do not need to make use of this communication feature the null pointer NAGCOMM_NULL may be used in the call to e04hcc; comm will then be declared internally for use in calls to objfun.

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

Dynamic memory allocation failed.

NE_DERIV_ERRORS

Large errors were found in the derivatives of the objective function.

You should check carefully the derivation and programming of expressions for the derivatives of $F\left(x\right)$, because it is very unlikely that objfun is calculating them correctly.

NE_INT_ARG_LT

On entry, $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{n}\ge 1$.

NE_USER_STOP

User requested termination, user flag value $=⟨\mathit{\text{value}}⟩$.

This exit occurs if you set $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ to a negative value in objfun. If fail is supplied the value of $\mathbf{fail}\mathbf{.}\mathbf{errnum}$ will be the same as your setting of $\mathbf{comm}\mathbf{\to }\mathbf{flag}$. The check on objfun will not have been completed.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results