naginterfaces.library.opt.lsq_​check_​deriv

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

lsq_check_deriv checks that a user-supplied function for evaluating a vector of functions and the matrix of their first derivatives produces derivative values which are consistent with the function values calculated.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/e04/e04yaf.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$. (The minimization functions mentioned in Notes give you the option of resetting an argument to terminate immediately. lsq_check_deriv 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)$

$x$, the point 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_deriv, 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$.

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 $lsqfun$. ‘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 can go undetected. For a similar reason, it is preferable that no two elements of $x$ should have the same value.

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

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $1$)

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

Constraint: $m\ge n$.

Warns

NagAlgorithmicWarning

(errno $i<0$)

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

(errno $2$)

It is very likely that you have made an error in forming the derivatives in $lsqfun$.

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 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 $f_i$ and their first derivatives. lsq_check_deriv checks the derivatives calculated by such functions, e.g., functions of the form required for lsq_uncon_quasi_deriv_comp(), lsq_uncon_mod_deriv_comp() and lsq_uncon_mod_deriv2_comp(). As well as the function to be checked ($lsqfun$), you must supply a point $x={(x_1,x_2,\dots ,x_n)}^T$ at which the check will be made. lsq_check_deriv is essentially identical to CHKLSJ in the NPL Algorithms Library.

lsq_check_deriv first calls $lsqfun$ to evaluate the $f_i\left(x\right)$ and their first derivatives, and uses these to calculate the sum of squares $F\left(x\right)={\sum }_{i=1}^m{\left[f_i\left(x\right)\right]}^2$, and its first derivatives $g_j={\frac{\partial F}{\partial x_j}|}_x$, for $j=1,2,\dots ,n$. The components of $g$ 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.