naginterfaces.library.opt.lsq_​check_​hessian

naginterfaces.library.opt.lsq_check_hessian(m, lsqfun, lsqhes, x, lb, data=None, spiked_sorder='C')

lsq_check_hessian checks that a user-supplied function for evaluating the second derivative term of the Hessian matrix of a sum of squares is consistent with a user-supplied function for calculating the corresponding first derivatives.

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

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

Parameters

mint

The number $m$ of residuals, $f_i\left(x\right)$, and the number $n$ of variables, $x_j$.

lsqfuncallable (iflag, fvec, fjac) = lsqfun(iflag, m, xc, data=None)

$lsqfun$ must calculate the vector of values $f_i\left(x\right)$ and their first derivatives $\frac{\partial f_i}{\partial x_j}$ at any point $x$. (lsq_uncon_mod_deriv2_comp() gives you the option of resetting arguments of $lsqfun$ to cause the minimization process to terminate immediately. lsq_check_hessian will also terminate immediately, without finishing the checking process, if the argument in question is reset.)

Parameters

iflagint

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

mint

The numbers $m$ of residuals.

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

The point $x$ at which the values of the $f_i$ and the $\frac{\partial f_i}{\partial x_j}$ are required.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

iflagint

If you reset $iflag$ to some negative number in $lsqfun$ and return control to lsq_check_hessian, the function will terminate immediately with $\text{errno}$ set to your setting of $iflag$.

fvecfloat, array-like, shape $\left(m\right)$

Unless $iflag$ is reset to a negative number, $fvec[\text{i}-1]$ must contain the value of $f_{\text{i}}$ at the point $x$, for $\text{i}=1,2,\dots ,m$.

fjacfloat, array-like, shape $(m,n)$

Unless $iflag$ is reset to a negative number, $fjac[\text{i}-1,\text{j}-1]$ must contain the value of $\frac{\partial f_{\text{i}}}{\partial x_{\text{j}}}$ at the point $x$, for $\text{j}=1,2,\dots ,n$, for $\text{i}=1,2,\dots ,m$.

lsqhescallable (iflag, b) = lsqhes(iflag, fvec, xc, lb, data=None)

$lsqhes$ must calculate the elements of the symmetric matrix

$$B\left(x\right)=\sum _{i=1}^m{f}_i\left(x\right)G_i\left(x\right)\text{,}$$

at any point $x$, where $G_i\left(x\right)$ is the Hessian matrix of $f_i\left(x\right)$. (As with $lsqfun$, an argument can be set to cause immediate termination.)

Parameters

iflagint

Is set to a non-negative number.

fvecfloat, ndarray, shape $\left(m\right)$

The value of the residual $f_{\text{i}}$ at the point $x$, for $\text{i}=1,2,\dots ,m$, so that the values of the $f_{\text{i}}$ can be used in the calculation of the elements of $b$.

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

The point $x$ at which the elements of $b$ are to be evaluated.

lbint

Gives the length of the array $b$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

iflagint

If $lsqhes$ resets $iflag$ to some negative number, lsq_check_hessian will terminate immediately, with $\text{errno}$ set to your setting of $iflag$.

bfloat, array-like, shape $\left(lb\right)$

Unless $iflag$ is reset to a negative number $b$ must contain the lower triangle of the matrix $B\left(x\right)$, evaluated at the point in $xc$, stored by rows. (The upper triangle is not needed because the matrix is symmetric.) More precisely, $b[\text{j}(\text{j}-1)/2+\text{k}-1]$ must contain ${\sum }_{\text{i}=1}^m{f}_{\text{i}}\frac{{\partial }^2{f}_{\text{i}}}{\partial x_{\text{j}}\partial x_{\text{k}}}$ evaluated at the point $x$, for $\text{k}=1,2,\dots ,\text{j}$, 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 $b_{jk}$ calculated by $lsqhes$. ‘Obvious’ settings, such as $0$ or $1$, should not be used since, at such particular points, incorrect terms may take correct values (particularly zero), so that errors could go undetected. For a similar reason, it is preferable that no two elements of $x$ should have the same value.

lbint

The dimension of the array $b$.

dataarbitrary, optional

User-communication data for callback functions.

spiked_sorderstr, optional

If $fjac$ in $lsqfun$ is spiked (i.e., has unit extent in all but one dimension, or has size $1$), $spiked\_sorder$ selects the storage order to associate with it in the NAG Engine:

spiked_sorder = $\text{'C'}$

row-major storage will be used;

spiked_sorder = $\text{'F'}$

column-major storage will be used.

Returns

fvecfloat, ndarray, shape $\left(m\right)$

Unless you set $iflag$ negative in the first call of $lsqfun$, $fvec[\text{i}-1]$ contains the value of $f_{\text{i}}$ at the point supplied by you in $x$, for $\text{i}=1,2,\dots ,m$.

fjacfloat, ndarray, shape $(m,n)$

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

bfloat, ndarray, shape $\left(lb\right)$

Unless you set $iflag$ negative in $lsqhes$, $b[\text{j}\times (\text{j}-1)/2+\text{k}-1]$ contains the value of $b_{\text{j}\text{k}}$ at the point given in $x$ as calculated by $lsqhes$, for $\text{k}=1,2,\dots ,\text{j}$, for $\text{j}=1,2,\dots ,n$.

Raises

NagValueError

(errno $1$)

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

Constraint: $m\ge n$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $1$)

On entry, $lb=⟨value⟩$ and $(n+1)\times n/2=⟨value⟩$.

Constraint: $lb\ge (n+1)\times n/2$.

Warns

NagAlgorithmicWarning

(errno $i<0$)

User requested termination by setting $iflag$ negative in $lsqfun$ or $lsqhes$.

(errno $2$)

It is very likely that you have made an error in setting up $b$ in $lsqhes$.

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

Functions for minimizing a sum of squares of $m$ nonlinear functions (or ‘residuals’), $f_{\text{i}}(x_1,x_2,\dots ,x_n)$, for $\text{i}=1,2,\dots ,m$ and $m\ge n$, may require you to supply a function to evaluate the quantities

$$b_{jk}=\sum _{i=1}^m{f}_i\frac{{\partial }^2{f}_i}{\partial x_j\partial x_k}$$

for $j=1,2,\dots ,n$ and $k=1,2,\dots ,j$. lsq_check_hessian is designed to check the $b_{jk}$ calculated by such functions. As well as the function to be checked ($lsqhes$), you must supply a function ($lsqfun$) to evaluate the $f_i$ and their first derivatives, and a point $x={(x_1,x_2,\dots ,x_n)}^T$ at which the checks will be made. Note that lsq_check_hessian checks functions of the form required by lsq_uncon_mod_deriv2_comp(). lsq_check_hessian is essentially identical to CHKLSH in the NPL Algorithms Library.

lsq_check_hessian first calls functions $lsqfun$ and $lsqhes$ to evaluate the first derivatives and the $b_{jk}$ at $x$. Let $J$ denote the $m\times n$ matrix of first derivatives of the residuals. The Hessian matrix of the sum of squares,

$$G=J^{T}J+B\text{,}$$

is calculated and projected onto two orthogonal vectors $y$ and $z$ to give the scalars $y^{T}Gy$ and $z^{T}Gz$ respectively. The same projections of the Hessian matrix are also estimated by finite differences, giving

$$\begin{array}{c}\begin{array}{c}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 gradient vector of the sum of squares at the point in brackets and $h$ is a small positive scalar. If the relative difference between $p$ and $y^{T}Gy$ or between $q$ and $z^{T}Gz$ is judged too large, an error indicator is set.