NAG CL Interface
e04hdc (check_​deriv2)

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 function $F\left(x\right)$ and its first derivatives $\frac{\partial F}{\partial x_j}$ at a specified point. (However, if you do not wish to calculate $F$ or its first derivatives at a particular point, there is the option of setting an argument to cause e04hdc to terminate immediately.)

The specification of objfun is:

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 the value of $F$, or $F$ and the $\frac{\partial F}{\partial x_j}$, 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}$; e04hdc 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 – IntegerOutput

On exit: if objfun resets $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ to some negative number then e04hdc will terminate immediately with the error indicator NE_USER_STOP. If fail is supplied to e04hdc $\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 evaluations 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 e04hdc these pointers may be allocated memory and initialized with various quantities for use by objfun when called from e04hdc.

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

Note: e04hcc should be used to check the first derivatives calculated by objfun before e04hdc is used to check the second derivatives, since e04hdc assumes that the first derivatives are correct.

3: $\mathbf{hessfun}$ – function, supplied by the user External Function

hessfun must calculate the second derivatives of $F\left(x\right)$ at any point $x$. (As with objfun there is the option of causing e04hdc to terminate immediately.)

The specification of hessfun is:

void  hessfun (Integer n, const double x[], double h[], double hd[], Nag_Comm *comm)

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

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

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

On entry: the point $x$ at which the second derivatives are required.

3: $\mathbf{h}\left[\mathbf{n}\times \left(\mathbf{n}-1\right)/2\right]$ – double Output

This array is allocated internally by e04hdc.

On exit: unless $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ is reset to a negative number hessfun must place the strict lower triangle of the second derivative matrix of $F$ (evaluated at the point $x$) in h, stored by rows, i.e., set

• $\mathbf{h}\left[\left(i-1\right)\left(i-2\right)/2+j-1\right]={\left.\frac{{\partial }^{2}F}{\partial x_i\partial x_j}\right|}_{x=\mathbf{x}}\text{, \hspace{1em} for }i=2,3,\dots ,n\text{; }j=1,2,\dots ,i-1\text{.}$

(The upper triangle is not required because the matrix is symmetric.)

4: $\mathbf{hd}\left[\mathbf{n}\right]$ – double Input/Output

On entry: the value of $\frac{\partial F}{\partial x_{\mathit{j}}}$ at the point $x$, for $\mathit{j}=1,2,\dots ,n$. These values may be useful in the evaluation of the second derivatives.

On exit: unless $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ is reset to a negative number hessfun must place the diagonal elements of the second derivative matrix of $F$ (evaluated at the point $x$) in hd, i.e., set

$$\mathbf{hd}\left[j-1\right]={\left(\frac{{\partial }^{2}F}{\partial x_j^2}\right)}_{x=\mathbf{x}}\text{, \hspace{1em} for }j=1,2,\dots ,n\text{.}$$

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

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

flag – IntegerOutput

On exit: if hessfun resets $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ to some negative number then e04hdc will terminate immediately with the error indicator NE_USER_STOP. If fail is supplied to e04hdc $\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 hessfun and Nag_FALSE for all subsequent calls.

nf – IntegerInput

On entry: the number of evaluations of the objective function; this value will be equal to the number of calls made to hessfun (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 e04hdc these pointers may be allocated memory and initialized with various quantities for use by hessfun when called from e04hdc.

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

Note: the array x must not be changed by hessfun.

4: $\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 contain 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 advisable that no two elements of x should be the same.

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

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

6: $\mathbf{hesl}\left[\mathbf{n}\times \left(\mathbf{n}-1\right)/2\right]$ – double Output

On exit: unless $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ is reset to a negative number hesl contains the strict lower triangle of the second derivative matrix of $F$, as evaluated by hessfun at the point given in x, stored by rows.

7: $\mathbf{hesd}\left[\mathbf{n}\right]$ – double Output

On exit: unless $\mathbf{comm}\mathbf{\to }\mathbf{flag}$ is reset to a negative number hesd contains the diagonal elements of the second derivative matrix of $F$, as evaluated by hessfun at the point given in x.

8: $\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 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 e04hdc; comm will then be declared internally for use in calls to user-supplied functions.

9: $\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.

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}}〉$.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results