NAG FL Interface
e04hcf (check_deriv)
1
Purpose
e04hcf checks that a subroutine for evaluating an objective function and its first derivatives produces derivative values which are consistent with the function values calculated.
2
Specification
Fortran Interface
Integer, Intent (In) |
:: |
n, liw, lw |
Integer, Intent (Inout) |
:: |
iw(liw), ifail |
Real (Kind=nag_wp), Intent (In) |
:: |
x(n) |
Real (Kind=nag_wp), Intent (Inout) |
:: |
w(lw) |
Real (Kind=nag_wp), Intent (Out) |
:: |
f, g(n) |
External |
:: |
funct |
|
C Header Interface
#include <nag.h>
void |
e04hcf_ (const Integer *n, void (NAG_CALL *funct)(Integer *iflag, const Integer *n, const double xc[], double *fc, double gc[], Integer iw[], const Integer *liw, double w[], const Integer *lw), const double x[], double *f, double g[], Integer iw[], const Integer *liw, double w[], const Integer *lw, Integer *ifail) |
|
C++ Header Interface
#include <nag.h> extern "C" {
void |
e04hcf_ (const Integer &n, void (NAG_CALL *funct)(Integer &iflag, const Integer &n, const double xc[], double &fc, double gc[], Integer iw[], const Integer &liw, double w[], const Integer &lw), const double x[], double &f, double g[], Integer iw[], const Integer &liw, double w[], const Integer &lw, Integer &ifail) |
}
|
The routine may be called by the names e04hcf or nagf_opt_check_deriv.
3
Description
Routines for minimizing a function of several variables may require you to supply a subroutine to evaluate the objective function
and its first derivatives.
e04hcf is designed to check the derivatives calculated by such user-supplied subroutines. As well as the routine to be checked (
funct), you must supply a point
at which the check will be made. Note that
e04hcf checks routines of the form required for
e04kdf and
e04lbf.
e04hcf first calls
funct to evaluate
and its first derivatives
, for
at
. The components of the user-supplied derivatives 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.
4
References
None.
5
Arguments
-
1:
– Integer
Input
-
On entry: the number of independent variables in the objective function.
Constraint:
.
-
2:
– Subroutine, supplied by the user.
External Procedure
-
funct must evaluate the function and its first derivatives at a given point. (The minimization routines mentioned in
Section 3 gives you the option of resetting arguments of
funct to cause the minimization process to terminate immediately.
e04hcf will also terminate immediately, without finishing the checking process, if the argument in question is reset.)
The specification of
funct is:
Fortran Interface
Integer, Intent (In) |
:: |
n, liw, lw |
Integer, Intent (Inout) |
:: |
iflag, iw(liw) |
Real (Kind=nag_wp), Intent (In) |
:: |
xc(n) |
Real (Kind=nag_wp), Intent (Inout) |
:: |
w(lw) |
Real (Kind=nag_wp), Intent (Out) |
:: |
fc, gc(n) |
|
C Header Interface
void |
funct_ (Integer *iflag, const Integer *n, const double xc[], double *fc, double gc[], Integer iw[], const Integer *liw, double w[], const Integer *lw) |
|
C++ Header Interface
#include <nag.h> extern "C" {
void |
funct_ (Integer &iflag, const Integer &n, const double xc[], double &fc, double gc[], Integer iw[], const Integer &liw, double w[], const Integer &lw) |
}
|
-
1:
– Integer
Input/Output
-
On entry: will be set to .
On exit: if you reset
iflag to a negative number in
funct and return control to
e04hcf,
e04hcf will terminate immediately with
ifail set to your setting of
iflag.
-
2:
– Integer
Input
-
On entry: the number of variables.
-
3:
– Real (Kind=nag_wp) array
Input
-
On entry: the point at which and its derivatives are required.
-
4:
– Real (Kind=nag_wp)
Output
-
On exit: unless
funct resets
iflag,
fc must be set to the value of the function
at the current point
.
-
5:
– Real (Kind=nag_wp) array
Output
-
On exit: unless
funct resets
iflag,
must be set to the value of the first derivative
at the point
, for
.
-
6:
– Integer array
Workspace
-
7:
– Integer
Input
-
8:
– Real (Kind=nag_wp) array
Workspace
-
9:
– Integer
Input
-
These arguments are present so that
funct will be of the form required by the minimization routines mentioned in
Section 3.
funct is called with
e04hcf's arguments
iw,
liw,
w,
lw as these arguments. If the advice given in the minimization routine documents is being followed, you will have no reason to examine or change any elements of
iw or
w. In any case,
funct must not change the first
elements of
w.
funct must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which
e04hcf is called. Arguments denoted as
Input must
not be changed by this procedure.
Note: funct should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by
e04hcf. If your code inadvertently
does return any NaNs or infinities,
e04hcf is likely to produce unexpected results.
-
3:
– Real (Kind=nag_wp) array
Input
-
On entry:
, for
, must be set to the coordinates of a suitable point at which to check the derivatives calculated by
funct. ‘Obvious’ settings, such as
, should not be used since, at such particular points, incorrect terms may take correct values (particularly zero), so that errors could go undetected. Similarly, it is preferable that no two elements of
x should be the same.
-
4:
– Real (Kind=nag_wp)
Output
-
On exit: unless you set
iflag negative in the first call of
funct,
f contains the value of the objective function
at the point given by you in
x.
-
5:
– Real (Kind=nag_wp) array
Output
-
On exit: unless you set
iflag negative in the first call of
funct,
contains the value of the derivative
at the point given in
x, as calculated by
funct, for
.
-
6:
– Integer array
Workspace
-
7:
– Integer
Input
-
This array is in the argument list so that it can be used by other library routines for passing integer quantities to
funct. It is not examined or changed by
e04hcf. Generally, you must provide an array
iw but are advised not to use it.
Constraint:
.
-
8:
– Real (Kind=nag_wp) array
Workspace
-
9:
– Integer
Input
-
On entry: the dimension of the array
w as declared in the (sub)program from which
e04hcf is called.
Constraint:
.
-
10:
– Integer
Input/Output
-
On entry:
ifail must be set to
,
. If you are unfamiliar with this argument you should refer to
Section 4 in the Introduction to the NAG Library FL Interface for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
is recommended. If the output of error messages is undesirable, then the value
is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if
on exit, the recommended value is
.
When the value is used it is essential to test the value of ifail on exit.
On exit:
unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
or
, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
Note: in some cases e04hcf may return useful information.
-
On entry, .
Constraint: .
On entry, and .
Constraint: .
On entry, .
Constraint: .
-
Large errors were found in the derivatives of
computed by
funct.
-
User requested termination by setting
iflag negative in
funct.
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
Accuracy
ifail is set to
if
for
. (See
Section 3 for definitions of the quantities involved.) The scalar
is set equal to
, where
is the
machine precision as given by
x02ajf.
8
Parallelism and Performance
e04hcf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
Before using
e04hcf to check the calculation of first derivatives, you should be confident that
funct is calculating
correctly. The usual way of checking the calculation of the function is to compare values of
calculated by
funct at nontrivial points
with values calculated independently. (‘Non-trivial’ means that, as when setting
before calling
e04hcf, coordinates such as
or
should be avoided.)
e04hcf only checks the derivatives calculated when
. So, if
funct is intended for use in conjunction with a minimization routine which may set
iflag to
, you must check that, for given settings of the
,
funct produces the same values for the
when
iflag is set to
as when
iflag is set to
.
10
Example
Suppose that it is intended to use
e04kdf to minimize
The following program could be used to check the first derivatives calculated by
funct. (The tests of whether
or
in
funct are present ready for when
funct is called by
e04kdf.
e04hcf will always call
funct with
iflag set to 2.)
10.1
Program Text
10.2
Program Data
None.
10.3
Program Results