nag_opt_lsq_check_deriv (e04yac) : NAG Library, Mark 24

2 Specification

#include <nag.h>

#include <nage04.h>

void

nag_opt_lsq_check_deriv (Integer m, Integer n,

void	(lsqfun)(Integer m, Integer n, const double x[], double fvec[], double fjac[], Integer tdfjac, Nag_Comm comm),

const double x[], double fvec[], double fjac[], Integer tdfjac, Nag_Comm *comm, NagError *fail)

3 Description

The function nag_opt_lsq_deriv (e04gbc) 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

, requires you to supply a C function to evaluate the

f_{i}

and their first derivatives. nag_opt_lsq_check_deriv (e04yac) checks the derivatives calculated by such a user-supplied function. As well as the C function to be checked (lsqfun), you must supply a point

x = {(x_{1}, x_{2}, \dots, x_{n})}^{T}

at which the check is to be made.

nag_opt_lsq_check_deriv (e04yac) 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.

5 Arguments

1: m – IntegerInput

2: n – IntegerInput

On entry: the number

m

of residuals,

f_{i} (x)

, and the number

n

of variables,

x_{j}

Constraint:

1 \leq n \leq m

3: lsqfun – function, supplied by the userExternal Function

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 function nag_opt_lsq_deriv (e04gbc) gives you the option of resetting an argument,

comm \to flag

, to terminate the minimization process immediately. nag_opt_lsq_check_deriv (e04yac) will also terminate immediately, without finishing the checking process, if the argument in question is reset to a negative value.)

The specification of lsqfun is:

void	lsqfun (Integer m, Integer n, const double x[], double fvec[], double fjac[], Integer tdfjac, Nag_Comm *comm)

1: m – IntegerInput

2: n – IntegerInput

On entry: the numbers

m

and

n

of residuals and variables, respectively.

3: x[n] – const doubleInput

On entry: the point

x

at which the values of the

f_{i}

and the

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

are required.

4: fvec[m] – doubleOutput

On exit: unless

comm \to flag

is reset to a negative number, then

fvec [i - 1]

must contain the value of

f_{i}

at the point

x

, for

i = 1, 2, \dots, m

5: fjac[ $m \times tdfjac$ ] – doubleOutput

On exit: unless

comm \to flag

is reset to a negative number, then the value in

fjac [(i - 1) \times tdfjac + j - 1]

must be the first derivative

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

at the point x, for

i = 1, 2, \dots, m

and

j = 1, 2, \dots, n

6: tdfjac – IntegerInput

On entry: the stride separating matrix column elements in the array fjac.

7: comm – Nag_Comm *

Pointer to structure of type Nag_Comm; the following members are relevant to lsqfun.

flag – IntegerInput/Output: On entry: $comm \to flag$ will be set to 2.

On exit: if lsqfun resets $comm \to flag$ to some negative number then nag_opt_lsq_check_deriv (e04yac) will terminate immediately with the error indicator NE_USER_STOP. If fail is supplied to nag_opt_lsq_check_deriv (e04yac), $fail . errnum$ will be set to your setting of $comm \to flag$ .

first – Nag_BooleanInput: On entry: will be set to Nag_TRUE on the first call to lsqfun and Nag_FALSE for all subsequent calls.

nf – IntegerInput: On entry: the number of calls made to lsqfun including the current one.

user – double *
iuser – Integer *
p – Pointer: The type Pointer will be void * with a C compiler that defines void * and char * otherwise. Before calling nag_opt_lsq_check_deriv (e04yac) these pointers may be allocated memory and initialized with various quantities for use by lsqfun when called from nag_opt_lsq_check_deriv (e04yac).

The array x must not be changed within lsqfun.

4: x[n] – const doubleInput

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.0 or 1.0, 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.

5: fvec[m] – doubleOutput

On exit: unless

comm \to flag

is set negative in the first call of lsqfun,

fvec [i - 1]

contains the value of

f_{i}

at the point given in x, for

i = 1, 2, \dots, m

6: fjac[

m \times tdfjac

] – doubleOutput

On exit: unless

comm \to flag

is set negative in the first call of lsqfun,

fjac [(i - 1) \times tdfjac + 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

7: tdfjac – IntegerInput

On entry: the stride separating matrix column elements in the array fjac.

Constraint:

tdfjac \geq n

8: comm – Nag_Comm *Input/Output

Note: comm is a NAG defined type (see Section 3.2.1.1 in the Essential Introduction).

On entry/exit: structure containing pointers for communication to the user-defined function; see the above description of lsqfun for details. If you do not need to make use of this communication feature the null pointer NAGCOMM_NULL may be used in the call to nag_opt_lsq_check_deriv (e04yac); comm will then be declared internally for use in calls to lsqfun.

9: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_2_INT_ARG_LT

On entry,

m = ⟨value⟩

while

n = ⟨value⟩

. These arguments must satisfy

m \geq n

On entry,

tdfjac = ⟨value⟩

while

n = ⟨value⟩

. These arguments must satisfy

tdfjac \geq n

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_DERIV_ERRORS

Large errors were found in the derivatives of the objective function. 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.

NE_INT_ARG_LT

On entry,

n = ⟨value⟩

.
Constraint:

n \geq 1

NE_USER_STOP

User requested termination, user flag value

= ⟨value⟩

. This exit occurs if you set

comm \to flag

to a negative value in lsqfun. If fail is supplied the value of

fail . errnum

will be the same as your setting of

comm \to flag

. The check on lsqfun will not have been completed.

7 Accuracy

fail.code is set to NE_DERIV_ERRORS if

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

for

k = 1

or 2. (See Section 3 for definitions of the quantities involved.) The scalar

h

is set equal to

\sqrt{ε}

, where

ε

is the machine precision as given by nag_machine_precision (X02AJC).

10 Example

Suppose that it is intended to use nag_opt_lsq_deriv (e04gbc) to find least squares estimates of

x_{1}

x_{2}

and

x_{3}

in the model

y = x_{1} + \frac{t_{1}}{x_{2} t_{2} + x_{3} t_{3}}

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

\begin{array}{r} y & t_{1} & t_{2} & t_{3} \\ 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 \end{array}

The following program could be used to check the first derivatives calculated by the required function lsqfun. (The tests of whether

comm \to flag \neq 0

or 1 in lsqfun are present for when lsqfun is called by nag_opt_lsq_deriv (e04gbc). nag_opt_lsq_check_deriv (e04yac) will always call lsqfun with

comm \to flag

set to 2.)

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Function Document

nag_opt_lsq_check_deriv (e04yac)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Function Documentnag_opt_lsq_check_deriv (e04yac)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Function Document

nag_opt_lsq_check_deriv (e04yac)