NAG Library Routine Document
E04ZCF/E04ZCA
1 Purpose
E04ZCF/E04ZCA checks that user-supplied subroutines for evaluating an objective function, constraint functions and their first derivatives, produce derivative values which are consistent with the function and constraint values calculated.
E04ZCA is a version of E04ZCF that has additional parameters in order to make it safe for use in multithreaded applications (see
Section 5).
2 Specification
2.1 Specification for E04ZCF
| SUBROUTINE E04ZCF ( | N, NCNLN, LDCJAC, CONFUN, OBJFUN, C, CJAC, OBJF, OBJGRD, X, WORK, LWORK, IFAIL) |
| INTEGER | N, NCNLN, LDCJAC, LWORK, IFAIL |
| double precision | C(LDCJAC), CJAC(LDCJAC,N), OBJF, OBJGRD(N), X(N), WORK(LWORK) |
| EXTERNAL | CONFUN, OBJFUN |
2.2 Specification for E04ZCA
| SUBROUTINE E04ZCA ( | N, NCNLN, LDCJAC, CONFUN, OBJFUN, C, CJAC, OBJF, OBJGRD, X, WORK, LWORK, IUSER, RUSER, IFAIL) |
| INTEGER | N, NCNLN, LDCJAC, LWORK, IUSER(*), IFAIL |
| double precision | C(LDCJAC), CJAC(LDCJAC,N), OBJF, OBJGRD(N), X(N), WORK(LWORK), RUSER(*) |
| EXTERNAL | CONFUN, OBJFUN |
3 Description
Routines for minimizing a function of several variables subject to general equality and/or inequality constraints may require you to provide subroutines to evaluate the objective function
Fx1,x2,…,xn, constraint functions
cix1,x2,…,xn, for
i=1,2,…,m, and their first derivatives. E04ZCF/E04ZCA is designed to check the derivatives calculated by such user-supplied subroutines . As well as the routines to be checked (
CONFUN and
OBJFUN), you must supply a point
x=x1,x2,…,xnT at which the checks will be made.
To check the first derivatives of
F, the routine first calls
OBJFUN to evaluate
F and its first derivatives
gj=
∂F
∂xj
, for
j=1,2,…,n, at
x. The components of the user-supplied derivatives 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
where
h is a small positive scalar. If the relative difference between
v1 and
gTp1 or between
v2 and
gTp2 is ‘judged’ too large, the error indicator
IFAIL (see
Section 6) is set to
2.
When n=1 only p1 and v1 are generated.
Similar checks are made of whether components of the first derivatives
(as calculated by
CONFUN at
x) are consistent with difference approximations to the same quantities.
4 References
Gill P E, Murray W and Wright M H (1981)
Practical Optimization Academic Press
5 Parameters
- 1: N – INTEGERInput
On entry:
the number n of independent variables in the objective and constraint functions.
Constraint:
N≥1.
- 2: NCNLN – INTEGERInput
On entry: the number m of constraint functions.
Constraint:
NCNLN≥0.
- 3: LDCJAC – INTEGERInput
On entry:
the dimension of the array
C and
the first dimension of the array
CJAC as declared in the (sub)program from which E04ZCF/E04ZCA is called.
Constraint:
LDCJAC≥max1,NCNLN.
- 4: CONFUN – SUBROUTINE, supplied by the NAG Library or the user.External Procedure
CONFUN must calculate the vector
cx of nonlinear constraint functions and its Jacobian for a specified
n-vector
x. If there are no nonlinear constraints (
NCNLN=0),
CONFUN will not be called by E04ZCF/E04ZCA and
CONFUN may be the dummy routine E04VDM/E54VDM. (E04VDM/E54VDM is included in the NAG Library.) If there are nonlinear constraints, E04ZCF/E04ZCA always calls
CONFUN and
OBJFUN together, in that order.
The specification of
CONFUN
for E04ZCF is:
| SUBROUTINE CONFUN ( | MODE, NCNLN, N, LDCJAC, X, C, CJAC, NSTATE) |
| INTEGER | MODE, NCNLN, N, LDCJAC, NSTATE |
| double precision | X(N), C(LDCJAC), CJAC(LDCJAC,N) |
The specification of
CONFUN
for E04ZCA is:
| SUBROUTINE CONFUN ( | MODE, NCNLN, N, LDCJAC, X, C, CJAC, NSTATE, IUSER, RUSER) |
| INTEGER | MODE, NCNLN, N, LDCJAC, NSTATE, IUSER(*) |
| double precision | X(N), C(LDCJAC), CJAC(LDCJAC,N), RUSER(*) |
- 1: MODE – INTEGERInput/Output
MODE is a flag that you may set within
CONFUN to indicate a failure in the evaluation of the nonlinear constraints.
On entry: is always non-negative.
On exit: if
MODE is negative on exit from
CONFUN, then execution of E04ZCF/E04ZCA will be terminated with
IFAIL containing the negative value of
MODE.
- 2: NCNLN – INTEGERInput
On entry: the number m of nonlinear constraints, as input to E04ZCF/E04ZCA.
- 3: N – INTEGERInput
On entry: the number n of variables, as input to E04ZCF/E04ZCA.
- 4: LDCJAC – INTEGERInput
On entry: the first dimension of the array
CJAC and the length of the array
C, as input to E04ZCF/E04ZCA.
- 5: X(N) – double precision arrayInput
-
On entry: the vector x of variables at which the constraint functions are to be evaluated.
- 6: C(LDCJAC) – double precision arrayOutput
-
On exit: must contain
NCNLN nonlinear constraint values, with the value of the
jth nonlinear constraint in
Cj.
- 7: CJAC(LDCJAC,N) – double precision arrayOutput
On exit: must contain the Jacobian of the nonlinear constraint functions with the
ith row of
CJAC containing the gradient of the
ith nonlinear constraint, i.e.,
CJACij must contain the partial derivative of
ci with respect to
xj. If
CJAC contains any constant elements, a saving in computation can be made by setting them once only, when
NSTATE=1.
- 8: NSTATE – INTEGERInput
On entry: will be
1 on the first call to
CONFUN by E04ZCF/E04ZCA, and is
0 for the two subsequent calls. Thus, if you wish,
NSTATE may be tested within
CONFUN in order to perform certain calculations once only. For example, you may read data or initialize COMMON block global variables when
NSTATE=1. In addition, the constant elements of
CJAC can be set in
CONFUN when
NSTATE=1, and need not be defined on subsequent calls.
- Note: the following are additional parameters for specific use with E04ZCA. Users of E04ZCF therefore need not read the remainder of this description.
- 9: IUSER(*) – INTEGER arrayUser Workspace
- 10: RUSER(*) – double precision arrayUser Workspace
CONFUN is called from E04ZCA with the parameters
IUSER and
RUSER as supplied to E04ZCA. You are free to use the arrays
IUSER and
RUSER to supply information to
CONFUN.
CONFUN must be declared as EXTERNAL in the (sub)program from which E04ZCF/E04ZCA is called. Parameters denoted as
Input must
not be changed by this procedure.
- 5: OBJFUN – SUBROUTINE, supplied by the user.External Procedure
OBJFUN must calculate the objective function
Fx and its gradient for a specified
n-element vector
x.
The specification of
OBJFUN
for E04ZCF is:
| SUBROUTINE OBJFUN ( | MODE, N, X, OBJF, OBJGRD, NSTATE) |
| INTEGER | MODE, N, NSTATE |
| double precision | X(N), OBJF, OBJGRD(N) |
The specification of
OBJFUN
for E04ZCA is:
| SUBROUTINE OBJFUN ( | MODE, N, X, OBJF, OBJGRD, NSTATE, IUSER, RUSER) |
| INTEGER | MODE, N, NSTATE, IUSER(*) |
| double precision | X(N), OBJF, OBJGRD(N), RUSER(*) |
- 1: MODE – INTEGERInput/Output
MODE is a flag that you may set within
OBJFUN to indicate a failure in the evaluation of the objective function.
On entry: is always non-negative.
On exit: if
MODE is negative on exit from
OBJFUN, then execution of E04ZCF/E04ZCA will be terminated with
IFAIL set to
MODE.
- 2: N – INTEGERInput
On entry: the number n of variables as input to E04ZCF/E04ZCA.
- 3: X(N) – double precision arrayInput
-
On entry: the vector x of variables at which the objective function is to be evaluated.
- 4: OBJF – double precisionOutput
-
On exit: must be set to the value of the objective function.
- 5: OBJGRD(N) – double precision arrayOutput
On exit: must contain the gradient vector of the objective function, with OBJGRDj containing the partial derivative of F with respect to xj.
- 6: NSTATE – INTEGERInput
On entry: will be
1 on the first call to
OBJFUN by E04ZCF/E04ZCA, and is
0 on the two subsequent calls. Thus, if you wish,
NSTATE may be tested in order to perform certain calculations only on the first call of
OBJFUN, e.g., read data or initialize COMMON blocksglobal variables. Note that if there are any nonlinear constraints,
CONFUN and
OBJFUN are called together, in that order.
- Note: the following are additional parameters for specific use with E04ZCA. Users of E04ZCF therefore need not read the remainder of this description.
- 7: IUSER(*) – INTEGER arrayUser Workspace
- 8: RUSER(*) – double precision arrayUser Workspace
OBJFUN is called from E04ZCA with the parameters
IUSER and
RUSER as supplied to E04ZCA. You are free to use the arrays
IUSER and
RUSER to supply information to
OBJFUN.
OBJFUN must be declared as EXTERNAL in the (sub)program from which E04ZCF/E04ZCA is called. Parameters denoted as
Input must
not be changed by this procedure.
- 6: C(LDCJAC) – double precision arrayOutput
On exit: unless you set
MODE<0 in the first call of
CONFUN,
Ci contains the value of
cix at the point given in
X, for
i=1,2,…,m.
If
NCNLN=0,
C is not referenced.
- 7: CJAC(LDCJAC,N) – double precision arrayOutput
On exit: unless you set
MODE<0 in the first call of
CONFUN,
CJACij contains the value of the derivative
∂ci
∂xj
at the point given in
X, as calculated by
CONFUN, for
j=1,2,…,n and
i=1,2,…,m.
If
NCNLN=0,
CJAC is not referenced.
- 8: OBJF – double precisionOutput
On exit: unless you set
MODE<0 in the first call of
OBJFUN,
OBJF contains the value of the objective function
Fx at the point given in
X.
- 9: OBJGRD(N) – double precision arrayOutput
On exit: unless you set
MODE<0 in the first call of
OBJFUN,
OBJGRDj contains the value of the derivative
∂F
∂xj
at the point given in
X, as calculated by
OBJFUN, for
j=1,2,…,n.
- 10: X(N) – double precision arrayInput
On entry:
Xj, for
j=1,2,…,n, must be set to the co-ordinates of a suitable point
x to check the derivatives calculated by
CONFUN and
OBJFUN. ‘Obvious’ settings such as
0 or
1, should not be used since, at such 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 equal.
- 11: WORK(LWORK) – double precision arrayWorkspace
- 12: LWORK – INTEGERInput
On entry: the dimension of the array
WORK as declared in the (sub)program from which E04ZCF/E04ZCA is called.
Constraint:
LWORK≥4×N+NCNLN+N×LDCJAC.
- 13: IFAIL – INTEGERInput/Output
-
Note: for E04ZCA, IFAIL does not occur in this position in the parameter list. See the additional parameters described below.
On entry:
IFAIL must be set to
0,
-1 or 1. If you are unfamiliar with this parameter you should refer to
Section 3.3 in the Essential Introduction for details.
On exit:
IFAIL=0 unless the routine detects an error (see
Section 6).
For environments where it might be inappropriate to halt program execution when an error is detected, the value
-1 or 1 is recommended. If the output of error messages is undesirable, then the value
1 is recommended. Otherwise, because for this routine the values of the output parameters may be useful even if
IFAIL≠0 on exit, the recommended value is
-1.
When the value -1 or 1 is used it is essential to test the value of IFAIL on exit. - Note: the following are additional parameters for specific use with E04ZCA. Users of E04ZCF therefore need not read the remainder of this description.
- 13: IUSER(*) – INTEGER arrayUser Workspace
Note: the dimension of the array
IUSER
must be at least
1.
IUSER is not used by E04ZCA, but is passed directly to
CONFUN and
OBJFUN and may be used to pass information to that routine.
- 14: RUSER(*) – double precision arrayUser Workspace
Note: the dimension of the array
RUSER
must be at least
1.
RUSER is not used by E04ZCA, but is passed directly to
CONFUN and
OBJFUN and may be used to pass information to that routine.
- 15: IFAIL – INTEGERInput/Output
Note: see the parameter description for
IFAIL above.
6 Error Indicators and Warnings
If on entry
IFAIL=0 or
-1, explanatory error messages are output on the current error message unit (as defined by
X04AAF).
Note: E04ZCF/E04ZCA may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
- IFAIL<0
-
A negative value of
IFAIL indicates an exit from E04ZCF/E04ZCA because you have set
MODE negative in
OBJFUN or
CONFUN. The value of
IFAIL will be the same as your setting of
MODE. The checks on
OBJFUN and
CONFUN will not have been completed.
- IFAIL=1
-
| On entry, | N<1, |
| or | NCNLN<0, |
| or | LDCJAC<max1,NCNLN, |
| or | LWORK<4×N+NCNLN+N×LDCJAC. |
- IFAIL=2
-
You should check carefully the derivation and programming of expressions for the derivatives of
Fx, because it is very unlikely that
OBJFUN is calculating them correctly.
- IFAIL=2+i, for i=1,2,…,NCNLN
-
You should check carefully the derivation and programming of expressions for the derivatives of
cix, because it is very unlikely that
CONFUN is calculating them correctly. See also
Section 7.
7 Accuracy
IFAIL is set to
2 if
for
k=1 or 2. (See
Section 3 for definitions of the quantities involved.) The scalar
h is set equal to
ε, where
ε is the
machine precision (see
X02AJF).
IFAIL is set to
2+i if a relation analogous to that given above holds for
ci and its calculated derivatives.
8 Further Comments
The user-supplied subroutines
CONFUN and
OBJFUN are both called three times unless
NCNLN=0, in which case
CONFUN is not called.
Before using E04ZCF/E04ZCA to check the calculation of first derivatives, you should be confident that
CONFUN and
OBJFUN are calculating
F and the
ci correctly. The usual way of checking the calculation of these function values is to compare values of
Fx and the
cix calculated by
OBJFUN and
CONFUN at nontrivial points
x with values calculated independently. (‘Non-trivial’ means that, as when setting
x before calling E04ZCF/E04ZCA, co-ordinates such as
0 or
1 should be avoided.)
9 Example
This example has nine variables, finite bounds on six of the variables, four general linear constraints, and 15 nonlinear constraints.
The objective function is
and the
15 nonlinear constraint functions are
The example checks the gradients at two separate points.
9.1 Program Text
Program Text (e04zcfe.f)
Program Text (e04zcae.f)
9.2 Program Data
Program Data (e04zcfe.d)
Program Data (e04zcae.d)
9.3 Program Results
Program Results (e04zcfe.r)
Program Results (e04zcae.r)