naginterfaces.library.opt.lsq_​uncon_​mod_​deriv2_​easy

naginterfaces.library.opt.lsq_uncon_mod_deriv2_easy(m, lsfun2, lshes2, x, data=None, spiked_sorder='C')

lsq_uncon_mod_deriv2_easy is an easy-to-use modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of $m$ nonlinear functions in $n$ variables $(m\ge n)$. First and second derivatives are required.

It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/e04/e04hyf.html

Parameters

mint

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

lsfun2callable (fvec, fjac) = lsfun2(m, xc, data=None)

You must supply this function to calculate the vector of values $f_i\left(x\right)$ and the Jacobian matrix of first derivatives $\frac{\partial f_i}{\partial x_j}$ at any point $x$.

It should be tested separately before being used in conjunction with lsq_uncon_mod_deriv2_easy (see the E04 Introduction).

Parameters

mint

$m$, the numbers 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

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

$fvec[i-1]$ must be set to the value of $f_{\text{i}}$ at the point $x$, for $\text{i}=1,2,\dots ,m$.

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

$fjac[\text{i}-1,\text{j}-1]$ must be set to 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$.

lshes2callable b = lshes2(fvec, xc, lb, data=None)

You must supply this function to 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)$.

It should be tested separately before being used in conjunction with lsq_uncon_mod_deriv2_easy (see the E04 Introduction).

Parameters

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

The length of the array $b$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

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

Must contain the lower triangle of the matrix $B\left(x\right)$, evaluated at the point $x$, stored by rows. (The upper triangle is not required 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]$ must be set to a guess at the $\text{j}$th component of the position of the minimum, for $\text{j}=1,2,\dots ,n$. The function checks $lsfun2$ and $lshes2$ at the starting point and so is more likely to detect any error in your functions if the initial $x[j-1]$ are nonzero and mutually distinct.

dataarbitrary, optional

User-communication data for callback functions.

spiked_sorderstr, optional

If $fjac$ in $lsfun2$ 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

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

The lowest point found during the calculations. Thus, if no exception or warning is raised on exit, $x[j-1]$ is the $j$th component of the position of the minimum.

fsumsqfloat

The value of the sum of squares, $F\left(x\right)$, corresponding to the final point stored in $x$.

commdict, communication object

Communication structure.

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 $2$)

There have been $50\times n$ calls to $lsfun2$.

(errno $4$)

Failure in computing SVD of Jacobian matrix.

(errno $9$)

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

(errno $10$)

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

Warns

NagAlgorithmicWarning

(errno $3$)

The conditions for a minimum have not all been satisfied, but a lower point could not be found.

(errno $5$)

It is probable that a local minimum has been found, but it cannot be guaranteed.

(errno $6$)

It is possible that a local minimum has been found, but it cannot be guaranteed.

(errno $7$)

It is unlikely that a local minimum has been found.

(errno $8$)

It is very unlikely that a local minimum has been found.

Notes

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

lsq_uncon_mod_deriv2_easy is similar to the function LSSDN2 in the NPL Algorithms Library. It is applicable to problems of the form:

$$Minimize\left(F\right)\left(x\right)=\sum _{i=1}^m{\left[f_i\left(x\right)\right]}^2$$

where $x={(x_1,x_2,\dots ,x_n)}^T$ and $m\ge n$. (The functions $f_i\left(x\right)$ are often referred to as ‘residuals’.)

You must supply a function to evaluate the residuals and their first derivatives at any point $x$, and a function to evaluate the elements of the second derivative term of the Hessian matrix of $F\left(x\right)$.

Before attempting to minimize the sum of squares, the algorithm checks the functions for consistency. Then, from a starting point supplied by you, a sequence of points is generated which is intended to converge to a local minimum of the sum of squares. These points are generated using estimates of the curvature of $F\left(x\right)$.

References

Gill, P E and Murray, W, 1978, Algorithms for the solution of the nonlinear least squares problem, SIAM J. Numer. Anal. (15), 977–992