NAG Library Routine Document

e04vjf (nlp2_sparse_jacobian)

1
Purpose

e04vjf may be used before e04vhf to determine the sparsity pattern for the Jacobian.

2
Specification

Fortran Interface
Subroutine e04vjf ( nf, n, usrfun, iafun, javar, a, lena, nea, igfun, jgvar, leng, neg, x, xlow, xupp, cw, lencw, iw, leniw, rw, lenrw, cuser, iuser, ruser, ifail)
Integer, Intent (In):: nf, n, lena, leng, lencw, leniw, lenrw
Integer, Intent (Inout):: iw(leniw), iuser(*), ifail
Integer, Intent (Out):: iafun(lena), javar(lena), nea, igfun(leng), jgvar(leng), neg
Real (Kind=nag_wp), Intent (In):: x(n), xlow(n), xupp(n)
Real (Kind=nag_wp), Intent (Inout):: rw(lenrw), ruser(*)
Real (Kind=nag_wp), Intent (Out):: a(lena)
Character (8), Intent (Inout):: cw(lencw), cuser(*)
External:: usrfun
C Header Interface
#include <nagmk26.h>
void  e04vjf_ (const Integer *nf, const Integer *n,
void (NAG_CALL *usrfun)(Integer *status, const Integer *n, const double x[], const Integer *needf, const Integer *nf, double f[], const Integer *needg, const Integer *leng, double g[], char cuser[], Integer iuser[], double ruser[], const Charlen length_cuser),
Integer iafun[], Integer javar[], double a[], const Integer *lena, Integer *nea, Integer igfun[], Integer jgvar[], const Integer *leng, Integer *neg, const double x[], const double xlow[], const double xupp[], char cw[], const Integer *lencw, Integer iw[], const Integer *leniw, double rw[], const Integer *lenrw, char cuser[], Integer iuser[], double ruser[], Integer *ifail, const Charlen length_cw, const Charlen length_cuser)

3
Description

When using e04vhf, if you set the optional parameter Derivative Option=0 and usrfun provides none of the derivatives, you may need to call e04vjf to determine the input arrays iafun, javar, a, igfun and jgvar. These arrays define the pattern of nonzeros in the Jacobian matrix. A typical sequence of calls could be
Call e04vgf (cw, lencw, ... )
Call e04vjf (nf, n, ... )
Call e04vlf ('Derivative Option = 0', cw, ... )
Call e04vhf (start, nf, ... )
e04vjf determines the sparsity pattern for the Jacobian and identifies the constant elements automatically. To do so, e04vjf approximates the problem functions, Fx , at three random perturbations of the given initial point x . If an element of the approximate Jacobian is the same at all three points, then it is taken to be constant. If it is zero, it is taken to be identically zero. Since the random points are not chosen close together, the heuristic will correctly classify the Jacobian elements in the vast majority of cases. In general, e04vjf finds that the Jacobian can be permuted to the form:
Gx A3 A2 A4 ,  
where A2 , A3  and A4  are constant. Note that Gx  might contain elements that are also constant, but e04vjf must classify them as nonlinear. This is because e04vhf ‘removes’ linear variables from the calculation of F  by setting them to zero before calling usrfun. A knowledgeable user would be able to move such elements from Fx  in usrfun and enter them as part of iafun, javar and a for e04vhf.

4
References

Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag

5
Arguments

Note: all optional parameters are described in detail in Section 12.1 in e04vhf.
1:     nf – IntegerInput
On entry: nf, the number of problem functions in Fx , including the objective function (if any) and the linear and nonlinear constraints. Simple upper and lower bounds on x  can be defined using the arguments xlow and xupp and should not be included in F .
Constraint: nf>0.
2:     n – IntegerInput
On entry: n, the number of variables.
Constraint: n>0.
3:     usrfun – Subroutine, supplied by the user.External Procedure
usrfun must define the problem functions Fx . This subroutine is passed to e04vjf as the external argument usrfun.
The specification of usrfun is:
Fortran Interface
Subroutine usrfun ( status, n, x, needf, nf, f, needg, leng, g, cuser, iuser, ruser)
Integer, Intent (In):: n, needf, nf, needg, leng
Integer, Intent (Inout):: status, iuser(*)
Real (Kind=nag_wp), Intent (In):: x(n)
Real (Kind=nag_wp), Intent (Inout):: f(nf), g(leng), ruser(*)
Character (8), Intent (Inout):: cuser(*)
C Header Interface
#include <nagmk26.h>
void  usrfun (Integer *status, const Integer *n, const double x[], const Integer *needf, const Integer *nf, double f[], const Integer *needg, const Integer *leng, double g[], char cuser[], Integer iuser[], double ruser[], const Charlen length_cuser)
1:     status – IntegerInput/Output
On entry: indicates the first call to usrfun.
status=0
There is nothing special about the current call to usrfun.
status=1
e04vjf is calling your subroutine for the first time. Some data may need to be input or computed and saved.
On exit: may be used to indicate that you are unable to evaluate F  at the current x . (For example, the problem functions may not be defined there).
e04vjf evaluates Fx  at random perturbation of the initial point x , say xp . If the functions cannot be evaluated at xp , you can set status=-1 , e04vjf will use another random perturbation.
If for some reason you wish to terminate the current problem, set status-2 .
2:     n – IntegerInput
On entry: n , the number of variables, as defined in the call to e04vjf.
3:     xn – Real (Kind=nag_wp) arrayInput
On entry: the variables x  at which the problem functions are to be calculated. The array x  must not be altered.
4:     needf – IntegerInput
On entry: indicates if f must be assigned during the call to usrfun (see f).
5:     nf – IntegerInput
On entry: nf, the number of problem functions.
6:     fnf – Real (Kind=nag_wp) arrayInput/Output
On entry: this will be set by e04vjf.
On exit: the computed Fx  according to the setting of needf.
If needf=0 , f is not required and is ignored.
If needf > 0 , the components of Fx  must be calculated and assigned to f. e04vjf will always call usrfun with needf>0 .
To simplify the code, you may ignore the value of needf and compute Fx  on every entry to usrfun.
7:     needg – IntegerInput
On entry: e04vjf will call usrfun with needg=0 to indicate that g is not required.
8:     leng – IntegerInput
On entry: the dimension of the array g as declared in the (sub)program from which e04vjf is called.
9:     gleng – Real (Kind=nag_wp) arrayInput/Output
On entry: concerns the calculations of the derivatives of the function fx .
On exit: e04vjf will always call usrfun with needg=0 : g is not required to be set on exit but must be declared correctly.
10:   cuser* – Character(8) arrayUser Workspace
11:   iuser* – Integer arrayUser Workspace
12:   ruser* – Real (Kind=nag_wp) arrayUser Workspace
usrfun is called with the arguments cuser, iuser and ruser as supplied to e04vjf. You should use the arrays cuser, iuser and ruser to supply information to usrfun.
usrfun must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e04vjf is called. Arguments denoted as Input must not be changed by this procedure.
Note: usrfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04vjf. If your code inadvertently does return any NaNs or infinities, e04vjf is likely to produce unexpected results.
4:     iafunlena – Integer arrayOutput
5:     javarlena – Integer arrayOutput
6:     alena – Real (Kind=nag_wp) arrayOutput
On exit: define the coordinates i,j  and values Aij  of the nonzero elements of the linear part A  of the function Fx=fx + Ax .
In particular, nea triples iafunk,javark,ak  define the row and column indices i=iafunk  and j=javark  of the element Aij=ak .
7:     lena – IntegerInput
On entry: the dimension of the arrays iafun, javar and a that hold i,j,Aij as declared in the (sub)program from which e04vjf is called. lena should be an overestimate of the number of elements in the linear part of the Jacobian.
Constraint: lena1.
8:     nea – IntegerOutput
On exit: is the number of nonzero entries in A  such that Fx=fx + Ax .
9:     igfunleng – Integer arrayOutput
10:   jgvarleng – Integer arrayOutput
On exit: define the coordinates i,j  of the nonzero elements of G , the nonlinear part of the derivatives Jx=Gx + A  of the function Fx=fx + Ax .
11:   leng – IntegerInput
On entry: the dimension of the arrays igfun and jgvar that define the varying Jacobian elements i,j,Gij as declared in the (sub)program from which e04vjf is called. leng should be an overestimate of the number of elements in the nonlinear part of the Jacobian.
Constraint: leng1.
12:   neg – IntegerOutput
On exit: the number of nonzero entries in G .
13:   xn – Real (Kind=nag_wp) arrayInput
On entry: an initial estimate of the variables x . The contents of x  will be used by e04vjf in the call of usrfun, and so each element of x should be within the bounds given by xlow and xupp.
14:   xlown – Real (Kind=nag_wp) arrayInput
15:   xuppn – Real (Kind=nag_wp) arrayInput
On entry: contain the lower and upper bounds lx  and ux  on the variables x .
To specify a nonexistent lower bound lx j =- , set xlowj -bigbnd , where bigbnd  is the optional parameter Infinite Bound Size. To specify a nonexistent upper bound xuppj bigbnd .
To fix the j th variable (say, xj=β , where β < bigbnd ), set xlowj=xuppj=β .
16:   cwlencw – Character(8) arrayCommunication Array
17:   lencw – IntegerInput
On entry: the dimension of the array cw as declared in the (sub)program from which e04vjf is called.
Constraint: lencw600.
18:   iwleniw – Integer arrayCommunication Array
19:   leniw – IntegerInput
On entry: the dimension of the array iw as declared in the (sub)program from which e04vjf is called.
Constraint: leniw600.
20:   rwlenrw – Real (Kind=nag_wp) arrayCommunication Array
21:   lenrw – IntegerInput
On entry: the dimension of the array rw as declared in the (sub)program from which e04vjf is called.
Constraint: lenrw600.
22:   cuser* – Character(8) arrayUser Workspace
23:   iuser* – Integer arrayUser Workspace
24:   ruser* – Real (Kind=nag_wp) arrayUser Workspace
cuser, iuser and ruser are not used by e04vjf, but are passed directly to usrfun and may be used to pass information to this routine.
25:   ifail – IntegerInput/Output
On entry: ifail must be set to 0, -1 or 1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
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, if you are not familiar with this argument, the recommended value is 0. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

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).
Errors or warnings detected by the routine:
ifail=1
On entry, lencw=value.
Constraint: lencw600.
On entry, leniw=value.
Constraint: leniw600.
On entry, lenrw=value.
Constraint: lenrw600.
The initialization routine e04vgf has not been called.
ifail=2
On entry, lena=value.
Constraint: lena1.
On entry, leng=value.
Constraint: leng1.
ifail=3
User-supplied routine usrfun indicates that functions are undefined near given point x.
You have indicated that the problem functions are undefined by setting status=-1  on exit from usrfun. This exit occurs if e04vjf is unable to find a point at which the functions are defined.
ifail=4
User-supplied routine usrfun requested termination.
You have indicated the wish to terminate the call to e04vjf by setting status to a value <-1 on exit from usrfun.
ifail=5
Either lena or leng is too small. Increase both of them and corresponding array sizes. lena=value and leng=value.
ifail=6
Cannot estimate Jacobian structure at given point x.
ifail=7
Internal error: memory allocation failed when attempting to allocate workspace sizes value, value and value. Please contact NAG.
ifail=8
Internal memory allocation was insufficient. Please contact NAG.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7
Accuracy

Not applicable.

8
Parallelism and Performance

e04vjf 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.

9
Further Comments

None.

10
Example

This example shows how to call e04vjf to determine the sparsity pattern of the Jacobian before calling e04vhf to solve a sparse nonlinear programming problem without providing the Jacobian information in usrfun.
It is a reformulation of Problem 74 from Hock and Schittkowski (1981) and involves the minimization of the nonlinear function
fx = 10-6 x33 + 23 × 10-6 x43+3 x3+2 x4  
subject to the bounds
-0.55x1 0.55, -0.55x2 0.55, 0x3 1200, 0x4 1200,  
to the nonlinear constraints
1000sin-x1-0.25+1000sin-x2-0.25-x3 = -894.8, 1000sinx1-0.25+1000sinx1-x2-0.25-x4 = -894.8, 1000sinx2-0.25+1000sinx2-x1-0.25 = -1294.8,  
and to the linear constraints
-x1+x2-0.55, -x1-x2-0.55.  
The initial point, which is infeasible, is
x0 = 0, 0, 0, 0 T ,  
and fx0=0.
The optimal solution (to five figures) is
x*=0.11887,-0.39623,679.94,1026.0T,  
and fx*=5126.4. All the nonlinear constraints are active at the solution.
The formulation of the problem combines the constraints and the objective into a single vector ( F ).
F = 1000 sin -x1 - 0.25 + 1000 sin -x2 - 0.25 - x3 1000 sin x1 - 0.25 + 1000 sin x1 - x2 - 0.25 - x4 1000 sin x2 - 0.25 + 1000 sin x2 - x1 - 0.25 -x1 + x2 x1 - x2 10-6 x33 + 23 × 10-6 x43 + 3x3 + 2x4  

10.1
Program Text

Program Text (e04vjfe.f90)

10.2
Program Data

Program Data (e04vjfe.d)

10.3
Program Results

Program Results (e04vjfe.r)