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

Syntax

C#
public static void e04ya( int m, int n, E04..::.E04YA_LSQFUN lsqfun, double[] x, double[] fvec, double[,] fjac, out int ifail )

Visual Basic (Declaration)
Public Shared Sub e04ya ( _ m As Integer, _ n As Integer, _ lsqfun As E04..::.E04YA_LSQFUN, _ x As Double(), _ fvec As Double(), _ fjac As Double(,), _ <OutAttribute> ByRef ifail As Integer _ )

Visual C++
public: static void e04ya( int m, int n, E04..::.E04YA_LSQFUN^ lsqfun, array<double>^ x, array<double>^ fvec, array<double,2>^ fjac, [OutAttribute] int% ifail )

F#
static member e04ya : m:int * n:int * lsqfun:E04..::.E04YA_LSQFUN * x:float[] * fvec:float[] * fjac:float[,] * ifail:int byref -> unit

Parameters

m: Type: System..::.Int32

On entry: the number m of residuals, fix, and the number n of variables, xj.

Constraint: 1≤n≤m.

n: Type: System..::.Int32

On entry: the number m of residuals, fix, and the number n of variables, xj.

Constraint: 1≤n≤m.

lsqfun: Type: NagLibrary..::.E04..::.E04YA_LSQFUN

lsqfun must calculate the vector of values fix and their first derivatives ∂fi ∂xj at any point x. (The minimization methods mentioned in [Description] give you the option of resetting a parameter to terminate immediately. e04ya will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)

A delegate of type E04YA_LSQFUN.

x: Type: array< System..::.Double >[]()[]
An array of size [n]

On entry: x[j-1], for j=1,2,…,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.

fvec: Type: array< System..::.Double >[]()[]
An array of size [m]

On exit: unless you set iflag negative in the first call of lsqfun, fvec[i-1] contains the value of fi at the point supplied by you in x, for i=1,2,…,m.

fjac: Type: array< System..::.Double ,2>[,](,)[,]
An array of size [ldfjac, n]
Note: ldfjac must satisfy the constraint: ldfjac≥m

On exit: unless you set iflag negative in the first call of lsqfun, fjac[i-1,j-1] contains the value of the first derivative ∂fi ∂xj at the point given in x, as calculated by lsqfun, for i=1,2,…,m and j=1,2,…,n.

ifail: Type: System..::.Int32 %

On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

Routines for minimizing a sum of squares of m nonlinear functions (or ‘residuals’), fix1,x2,…,xn, for i=1,2,…,m and m≥n, may require you to supply a method to evaluate the fi and their first derivatives. e04ya checks the derivatives calculated by such user-supplied delegates, e.g., methods of the form required for e04gd and e04he. As well as the method to be checked (lsqfun), you must supply a point x = x1,x2,…,xnT at which the check will be made. e04ya is essentially identical to CHKLSJ in the NPL Algorithms Library.

e04ya first calls lsqfun to evaluate the fix and their first derivatives, and uses these to calculate the sum of squares Fx=∑i=1 m fix2, and its first derivatives gj = ∂ F ∂ x j x , for j=1,2,…,n. The components of g along two orthogonal directions (defined by unit vectors p1 and p2, say) are then calculated; these will be gTp1 and gTp2 respectively. The same components are also estimated by finite differences, giving quantities

vk=Fx+hpk-Fxh, k=1,2

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

References

None.

Error Indicators and Warnings

Note: e04ya may return useful information for one or more of the following detected errors or warnings.

Errors or warnings detected by the method:

ifail<0: A negative value of ifail indicates an exit from e04ya because you have set iflag negative in lsqfun. The setting of ifail will be the same as your setting of iflag. The check on lsqfun will not have been completed.

ifail=1: On entry, m<n,
or n<1,

ifail=2: You should check carefully the derivation and programming of expressions for the ∂fi ∂xj , because it is very unlikely that lsqfun is calculating them correctly.

ifail=-4000: Invalid dimension for array value
ifail=-8000: Negative dimension for array value
ifail=-6000: Invalid Parameters value

Accuracy

ifail is set to 2 if

vk - gT pk 2 ≥ h× gT pk 2 +1

for k=1 or 2. (See [Description] for definitions of the quantities involved.) The scalar h is set equal to ε, where ε is the machine precision as given by x02aj.

Further Comments

e04ya calls lsqfun three times.

Before using e04ya to check the calculation of the first derivatives, you should be confident that lsqfun is calculating the residuals correctly.

e04ya only checks the derivatives calculated by a user-supplied method when iflag=2. So, if lsqfun is intended for use in conjunction with a minimization method which may set iflag to 1, you must check that, for given settings of the xc[j-1], lsqfun produces the same values for the ∂fi ∂xj when iflag is set to 1 as when iflag is set to 2.

Example

Suppose that it is intended to use e04gd to find least-squares estimates of x1,x2 and x3 in the model

y=x1+t1x2t2+x3t3

using the 15 sets of data given in the following table.

y t1 t2 t3 0.14 1.0 15.0 1.0 0.18 2.0 14.0 2.0 0.22 3.0 13.0 3.0 0.25 4.0 12.0 4.0 0.29 5.0 11.0 5.0 0.32 6.0 10.0 6.0 0.35 7.0 9.0 7.0 0.39 8.0 8.0 8.0 0.37 9.0 7.0 7.0 0.58 10.0 6.0 6.0 0.73 11.0 5.0 5.0 0.96 12.0 4.0 4.0 1.34 13.0 3.0 3.0 2.10 14.0 2.0 2.0 4.39 15.0 1.0 1.0

The following program could be used to check the first derivatives calculated by lsqfun. (The tests of whether iflag=0 or 1 in lsqfun are present ready for when lsqfun is called by e04gd. e04ya will always call lsqfun with iflag set to 2.)

Example program (C#): e04yae.cs

Example program data: e04yae.d

Example program results: e04yae.r

On entry,	m<n,
or	n<1,