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
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, $f_{i} (x)$ , and the number $n$ of variables, $x_{j}$ .

Constraint: $1 \leq n \leq m$ .

n: Type: System..::..Int32
On entry: the number $m$ of residuals, $f_{i} (x)$ , and the number $n$ of variables, $x_{j}$ .

Constraint: $1 \leq n \leq m$ .

lsqfun: Type: NagLibrary..::..E04..::..E04YA_LSQFUN
lsqfun must calculate the vector of values $f_{i} (x)$ and their first derivatives $\frac{\partial f_{i}}{\partial x_{j}}$ 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, \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.

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 $f_{i}$ at the point supplied by you in x, for $i = 1, 2, \dots, m$ .

fjac: Type: array<System..::..Double,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: $dim1 \geq 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 $\frac{\partial f_{i}}{\partial x_{j}}$ at the point given in x, as calculated by lsqfun, for $i = 1, 2, \dots, m$ and $j = 1, 2, \dots, n$ .

ifail: Type: System..::..Int32%
On exit: $ifail = 0$ unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Routines for minimizing a sum of squares of

m

nonlinear functions (or ‘residuals’),

f_{i} (x_{1}, x_{2}, \dots, x_{n})

, for

i = 1, 2, \dots, m

and

m \geq n

, may require you to supply a method to evaluate the

f_{i}

and their first derivatives. e04ya checks the derivatives calculated by such user-supplied delegates, e.g., methods of the form required for (E04GBF not in this release) e04gd e04he. As well as the method 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. e04ya is essentially identical to CHKLSJ in the NPL Algorithms Library.

e04ya first calls lsqfun to evaluate the

f_{i} (x)

and their first derivatives, and uses these to calculate the sum of squares

F (x) = \sum_{i = 1}^{m} {[f_{i} (x)]}^{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 (x)}{h}, 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.

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:

Some error messages may refer to parameters that are dropped from this interface (LDFJAC, IW, LIW, W, LW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.

$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 $\frac{\partial f_{i}}{\partial x_{j}}$ , because it is very unlikely that lsqfun is calculating them correctly.

$ifail = -9000$: An error occured, see message report.
$ifail = -6000$: Invalid Parameters $〈value〉$
$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

{(v_{k} - g^{T} p_{k})}^{2} \geq h \times ({(g^{T} p_{k})}^{2} + 1)

for

k = 1 ​ or ​ 2

. (See [Description] for definitions of the quantities involved.) The scalar

h

is set equal to

\sqrt{ε}

, where

ε

is the machine precision as given by x02aj.

Parallelism and Performance

None.

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

\frac{\partial f_{i}}{\partial x_{j}}

when iflag is set to

1

as when iflag is set to

2

Example

Example program (C#): e04yae.cs

Example program data: e04yae.d

Example program results: e04yae.r