naginterfaces.library.opt.lsq_​check_​deriv

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

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://www.nag.com/numeric/nl/nagdoc_28.7/flhtml/e04/e04yaf.html

Parameters
mint

The number of residuals, , and the number of variables, .

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

must calculate the vector of values and their first derivatives at any point . (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 , will be set to .

mint

The numbers of residuals.

xcfloat, ndarray, shape

, the point at which the values of the and the are required.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
iflagint

If you reset to some negative number in and return control to lsq_check_deriv, the function will terminate immediately with set to your setting of .

fvecfloat, array-like, shape

Unless is reset to a negative number, must contain the value of at the point , for .

fjacfloat, array-like, shape

Unless is reset to a negative number, must contain the value of at the point , for , for .

xfloat, array-like, shape

, for , must be set to the coordinates of a suitable point at which to check the derivatives calculated by . ‘Obvious’ settings, such as or , 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 should have the same value.

dataarbitrary, optional

User-communication data for callback functions.

spiked_sorderstr, optional

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

spiked_sorder =

row-major storage will be used;

spiked_sorder =

column-major storage will be used.

Returns
fvecfloat, ndarray, shape

Unless you set negative in the first call of , contains the value of at the point supplied by you in , for .

fjacfloat, ndarray, shape

Unless you set negative in the first call of , contains the value of the first derivative at the point given in , as calculated by , for , for .

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

On entry, and .

Constraint: .

Warns
NagAlgorithmicWarning
(errno )

User requested termination by setting negative in .

(errno )

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

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 nonlinear functions (or ‘residuals’), , for and , may require you to supply a function to evaluate the 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 (), you must supply a point 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 to evaluate the and their first derivatives, and uses these to calculate the sum of squares , and its first derivatives , for . The components of along two orthogonal directions (defined by unit vectors and , say) are then calculated; these will be and respectively. The same components are also estimated by finite differences, giving quantities

where is a small positive scalar. If the relative difference between and or between and is judged too large, an error indicator is set.