naginterfaces.library.opt.check_​deriv2

naginterfaces.library.opt.check_deriv2(funct, h, x, lh, data=None)

check_deriv2 checks that a function for calculating second derivatives of an objective function is consistent with a function for calculating the corresponding first derivatives.

For full information please refer to the NAG Library document for e04hd

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e04/e04hdf.html

Parameters

functcallable (iflag, fc, gc) = funct(iflag, xc, data=None)

$funct$ must evaluate the function and its first derivatives at a given point. (bounds_mod_deriv2_comp() gives you the option of resetting arguments of $funct$ to cause the minimization process to terminate immediately. check_deriv2 will also terminate immediately, without finishing the checking process, if the argument in question is reset.)

Parameters

iflagint

To $funct$, $iflag$ will be set to $2$.

xcfloat, ndarray, shape $\left(n\right)$

The point $x$ at which the function and first derivatives are required.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

iflagint

If you set $iflag$ to some negative number in $funct$ and return control to check_deriv2, check_deriv2 will terminate immediately with $\text{errno}$ set to your setting of $iflag$.

fcfloat

Unless $funct$ resets $iflag$, $fc$ must be set to the value of the objective function $F$ at the current point $x$.

gcfloat, array-like, shape $\left(n\right)$

Unless $funct$ resets $iflag$, $gc[\text{j}-1]$ must be set to the value of the first derivative $\frac{\partial F}{\partial x_{\text{j}}}$ at the point $x$, for $\text{j}=1,2,\dots ,n$.

hcallable (iflag, fhesl, fhesd) = h(iflag, xc, lh, fhesd, data=None)

$h$ must evaluate the second derivatives of the function at a given point. (As with $funct$, an argument can be set to cause immediate termination.)

Parameters

iflagint

Is set to a non-negative number.

xcfloat, ndarray, shape $\left(n\right)$

The point $x$ at which the second derivatives of $F\left(x\right)$ are required.

lhint

The length of the array $fhesl$.

fhesdfloat, ndarray, shape $\left(n\right)$

Contains the value of $\frac{\partial F}{\partial x_{\text{j}}}$ at the point $x$, for $\text{j}=1,2,\dots ,n$. Functions written to take advantage of a similar feature of bounds_mod_deriv2_comp() can be tested as they stand by check_deriv2.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

iflagint

If $h$ resets $iflag$ to a negative number, check_deriv2 will terminate immediately with $\text{errno}$ set to your setting of $iflag$.

fheslfloat, array-like, shape $\left(lh\right)$

Unless $iflag$ is reset, $h$ must place the strict lower triangle of the second derivative matrix of $F$ (evaluated at the point $x$) in $fhesl$, stored by rows, i.e., $fhesl[(\text{i}-1)(\text{i}-2)/2+\text{j}-1]$ must be set to the value of $\frac{{\partial }^{2}F}{\partial x_{\text{i}}\partial x_{\text{j}}}$ at the point $x$, for $\text{j}=1,2,\dots ,\text{i}-1$, for $\text{i}=2,3,\dots ,n$. (The upper triangle is not required because the matrix is symmetric.)

fhesdfloat, array-like, shape $\left(n\right)$

Unless $iflag$ is reset, $h$ must place the diagonal elements of the second derivative matrix of $F$ (evaluated at the point $x$) in $fhesd$, i.e., $fhesd[\text{j}-1]$ must be set to the value of $\frac{{\partial }^{2}F}{\partial x_{\text{j}}^2}$ at the point $x$, for $\text{j}=1,2,\dots ,n$.

xfloat, array-like, shape $\left(n\right)$

$x[\text{j}-1]$, for $\text{j}=1,2,\dots ,n$, must contain the coordinates of a suitable point at which to check the derivatives calculated by $funct$. ‘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.

lhint

The dimension of the array $hesl$.

dataarbitrary, optional

User-communication data for callback functions.

Returns

gfloat, ndarray, shape $\left(n\right)$

Unless you set $iflag$ negative in the first call of $funct$, $g[\text{j}-1]$ contains the value of the first derivative $\frac{\partial F}{\partial x_{\text{j}}}$ at the point given in $x$, as calculated by $funct$, for $\text{j}=1,2,\dots ,n$.

heslfloat, ndarray, shape $\left(lh\right)$

Unless you set $iflag$ negative in $h$, $hesl$ contains the strict lower triangle of the second derivative matrix of $F$, as evaluated by $h$ at the point given in $x$, stored by rows.

hesdfloat, ndarray, shape $\left(n\right)$

Unless you set $iflag$ negative in $h$, $hesd$ contains the diagonal elements of the second derivative matrix of $F$, as evaluated by $h$ at the point given in $x$.

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $1$)

On entry, $lh=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $lh\ge max(1,n\times \frac{n-1}{2})$.

Warns

NagAlgorithmicWarning

(errno $i<0$)

User requested termination by setting $iflag$ negative in $funct$.

(errno $2$)

Large errors were found in the derivatives of $F$ computed by $funct$.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

Functions for minimizing a function $F(x_1,x_2,\dots ,x_n)$ of the variables $x_1,x_2,\dots ,x_n$ may require you to provide a function to evaluate the second derivatives of $F$. check_deriv2 is designed to check the second derivatives calculated by such functions. As well as the function to be checked ($h$), you must supply a function ($funct$) to evaluate the first derivatives, and a point $x={(x_1,x_2,\dots ,x_n)}^T$ at which the checks will be made. Note that check_deriv2 checks functions of the form required for bounds_mod_deriv2_comp().

check_deriv2 first calls functions $funct$ and $h$ to evaluate the first and second derivatives of $F$ at $x$. The user-supplied Hessian matrix ($H$, say) is projected onto two orthogonal vectors $y$ and $z$ to give the scalars $y^{T}Hy$ and $z^{T}Hz$ respectively. The same projections of the Hessian matrix are also estimated by finite differences, giving

$$\begin{array}{c}\begin{array}{cc}p=(y^{T}g(x+hy)-y^{T}g\left(x\right))/h& \text{and}\\ & q=(z^{T}g(x+hz)-z^{T}g\left(x\right))/h\end{array}\end{array}$$

respectively, where $g\left(\right)$ denotes the vector of first derivatives at the point in brackets and $h$ is a small positive scalar. If the relative difference between $p$ and $y^{T}Hy$ or between $q$ and $z^{T}Hz$ is judged too large, an error indicator is set.