This was a sparsity structure defining function for e04vhc which has been superseded by e04src. e04src is part of the NAG optimization modelling suite (see Section 4.1 in the E04 Chapter Introduction) which uses the problem defining facilities common to that suite.
The function may be called by the names: e04vjc, nag_opt_nlp2_sparse_jacobian or nag_opt_sparse_nlp_jacobian.
When using e04vhc, if you set the optional parameter and usrfun provides none of the derivatives, you may need to call e04vjc 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
e04vjc determines the sparsity pattern for the Jacobian and identifies the constant elements automatically. To do so, e04vjc approximates the problem functions, , at three random perturbations of the given initial point . 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, e04vjc finds that the Jacobian can be permuted to the form:
where , and are constant. Note that might contain elements that are also constant, but e04vjc must classify them as nonlinear. This is because e04vhc ‘removes’ linear variables from the calculation of by setting them to zero before calling usrfun. A knowledgeable user would be able to move such elements from in usrfun and enter them as part of iafun, javar and a for e04vhc.
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems187 Springer–Verlag
Note: all optional parameters are described in detail in Section 12.1 in e04vhc.
1: – IntegerInput
On entry: , the number of problem functions in , including the objective function (if any) and the linear and nonlinear constraints. Simple upper and lower bounds on can be defined using the arguments xlow and xupp and should not be included in .
2: – IntegerInput
On entry: , the number of variables.
3: – function, supplied by the userExternal Function
usrfun must define the problem functions . This function is passed to e04vjc as the external argument usrfun.
On entry: concerns the calculations of the derivatives of the function .
On exit: e04vjc will always call usrfun with : g is not required to be set on exit but must be declared correctly.
10: – Nag_Comm *
Pointer to structure of type Nag_Comm; the following members are relevant to usrfun.
user – double *
iuser – Integer *
p – Pointer
The type Pointer will be void *. Before calling e04vjc you may allocate memory and initialize these pointers with various quantities for use by usrfun when called from e04vjc (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).
Note:usrfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by e04vjc. If your code inadvertently does return any NaNs or infinities, e04vjc is likely to produce unexpected results.
4: – IntegerOutput
5: – IntegerOutput
6: – doubleOutput
On exit: define the coordinates and values of the nonzero elements of the linear part of the function .
In particular, nea triples define the row and column indices and of the element .
7: – IntegerInput
On entry: the dimension of the arrays iafun, javar and a that hold . lena should be an overestimate of the number of elements in the linear part of the Jacobian.
8: – Integer *Output
On exit: is the number of nonzero entries in such that .
9: – IntegerOutput
10: – IntegerOutput
On exit: define the coordinates of the nonzero elements of , the nonlinear part of the derivatives of the function .
11: – IntegerInput
On entry: the dimension of the arrays igfun and jgvar that define the varying Jacobian elements . leng should be an overestimate of the number of elements in the nonlinear part of the Jacobian.
12: – Integer *Output
On exit: the number of nonzero entries in .
13: – const doubleInput
On entry: an initial estimate of the variables . The contents of will be used by e04vjc in the call of usrfun, and so each element of x should be within the bounds given by xlow and xupp.
14: – const doubleInput
15: – const doubleInput
On entry: contain the lower and upper bounds and on the variables .
To specify a nonexistent lower bound , set , where is the optional parameter . To specify a nonexistent upper bound .
To fix the th variable (say, , where ), set .
16: – Nag_E04State *Communication Structure
state contains internal information required for functions in this suite. It must not be modified in any way.
17: – Nag_Comm *
The NAG communication argument (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).
18: – NagError *Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).
6Error Indicators and Warnings
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
Internal error: memory allocation failed when attempting to allocate workspace sizes , and . Please contact NAG.
Internal memory allocation was insufficient. Please contact NAG.
Either lena or leng is too small. Increase both of them and corresponding array sizes. and .
On entry, argument had an illegal value.
The initialization function e04vgc has not been called.
On entry, .
On entry, .
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
Cannot estimate Jacobian structure at given point x.
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.
User-supplied function usrfun requested termination.
You have indicated the wish to terminate the call to e04vjc by setting status to a value on exit from usrfun.
User-supplied function usrfun indicates that functions are undefined near given point x.
You have indicated that the problem functions are undefined by setting on exit from usrfun. This exit occurs if e04vjc is unable to find a point at which the functions are defined.
8Parallelism and Performance
Background information to multithreading can be found in the Multithreading documentation.
e04vjc 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 function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.
This example shows how to call e04vjc to determine the sparsity pattern of the Jacobian before calling e04vhc to solve a sparse nonlinear programming problem without providing the Jacobian information in usrfun.