naginterfaces.library.opt.check_​deriv

naginterfaces.library.opt.check_deriv(funct, x, data=None)

check_deriv checks that a function for evaluating an objective function and its first derivatives produces derivative values which are consistent with the function values calculated.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/e04/e04hcf.html

Parameters

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

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

Parameters

iflagint

Will be set to $2$.

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

The point $x$ at which $F$ and its derivatives are required.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

iflagint

If you reset $iflag$ to a negative number in $funct$ and return control to check_deriv, check_deriv 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 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$.

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

$x[\text{j}-1]$, for $\text{j}=1,2,\dots ,n$, must be set to 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 preferable that no two elements of $x$ should be the same.

dataarbitrary, optional

User-communication data for callback functions.

Returns

ffloat

Unless you set $iflag$ negative in the first call of $funct$, $f$ contains the value of the objective function $F\left(x\right)$ at the point given by you in $x$.

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

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

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 of several variables may require you to supply a function to evaluate the objective function $F(x_1,x_2,\dots ,x_n)$ and its first derivatives. check_deriv is designed to check the derivatives calculated by such functions. As well as the function to be checked ( $funct$), you must supply a point $x={(x_1,x_2,\dots ,x_n)}^T$ at which the check will be made. Note that check_deriv checks functions of the form required for bounds_mod_deriv_comp() and bounds_mod_deriv2_comp().

check_deriv first calls $funct$ to evaluate $F$ and its first derivatives $g_{\text{j}}=\frac{\partial F}{\partial x_{\text{j}}}$, for $\text{j}=1,2,\dots ,n$ at $x$. The components of the user-supplied derivatives along two orthogonal directions (defined by unit vectors $p_1$ and $p_2$, say) are then calculated; these will be $g^T{p}_1$ and $g^T{p}_2$ respectively. The same components are also estimated by finite differences, giving quantities

$$v_k=\frac{F(x+h{p}_k)-F\left(x\right)}{h}\text{,}k=1,2$$

where $h$ is a small positive scalar. If the relative difference between $v_1$ and $g^T{p}_1$ or between $v_2$ and $g^T{p}_2$ is judged too large, an error indicator is set.