NAG CL Interface
e04vjc (nlp2_​sparse_​jacobian)

1 Purpose

2 Specification

3 Description

e04vgc (&state, ... );
e04vjc (nf, n, ... );
e04vlc ("Derivative Option = 0", &state, ... );
e04vhc (start, nf, ... );

4 References

5 Arguments

1: $\mathbf{nf}$ – Integer Input

On entry: $\mathit{nf}$, the number of problem functions in $F\left(x\right)$, 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: $\mathbf{nf}>0$.

2: $\mathbf{n}$ – Integer Input

On entry: $n$, the number of variables.

Constraint: $\mathbf{n}>0$.

3: $\mathbf{usrfun}$ – function, supplied by the user External Function

usrfun must define the problem functions $F\left(x\right)$. This function is passed to e04vjc as the external argument usrfun.

The specification of usrfun is:

void  usrfun (Integer *status, Integer n, const double x[], Integer needf, Integer nf, double f[], Integer needg, Integer leng, double g[], Nag_Comm *comm)

1: $\mathbf{status}$ – Integer * Input/Output

On entry: indicates the first call to usrfun.

$\mathbf{status}=0$

There is nothing special about the current call to usrfun.

$\mathbf{status}=1$

e04vjc is calling your function 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).

e04vjc evaluates $F\left(x\right)$ at random perturbation of the initial point $x$, say $x_p$. If the functions cannot be evaluated at $x_p$, you can set $\mathbf{status}=-1$, e04vjc will use another random perturbation.

If for some reason you wish to terminate the current problem, set $\mathbf{status}\le -2$.

2: $\mathbf{n}$ – Integer Input

On entry: $n$, the number of variables, as defined in the call to e04vjc.

3: $\mathbf{x}\left[\mathbf{n}\right]$ – const double Input

On entry: the variables $x$ at which the problem functions are to be calculated. The array $x$ must not be altered.

4: $\mathbf{needf}$ – Integer Input

On entry: indicates if f must be assigned during the call to usrfun (see f).

5: $\mathbf{nf}$ – Integer Input

On entry: $\mathit{nf}$, the number of problem functions.

6: $\mathbf{f}\left[\mathbf{nf}\right]$ – double Input/Output

On entry: this will be set by e04vjc.

On exit: the computed $F\left(x\right)$ according to the setting of needf.

If $\mathbf{needf}=0$, f is not required and is ignored.

If $\mathbf{needf}>0$, the components of $F\left(x\right)$ must be calculated and assigned to f. e04vjc will always call usrfun with $\mathbf{needf}>0$.

To simplify the code, you may ignore the value of needf and compute $F\left(x\right)$ on every entry to usrfun.

7: $\mathbf{needg}$ – Integer Input

On entry: e04vjc will call usrfun with $\mathbf{needg}=0$ to indicate that g is not required.

8: $\mathbf{leng}$ – Integer Input

On entry: the dimension of the array g.

9: $\mathbf{g}\left[\mathbf{leng}\right]$ – double Input/Output

On entry: concerns the calculations of the derivatives of the function $f\left(x\right)$.

On exit: e04vjc will always call usrfun with $\mathbf{needg}=0$: g is not required to be set on exit but must be declared correctly.

10: $\mathbf{comm}$ – 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: $\mathbf{iafun}\left[\mathbf{lena}\right]$ – Integer Output

5: $\mathbf{javar}\left[\mathbf{lena}\right]$ – Integer Output

6: $\mathbf{a}\left[\mathbf{lena}\right]$ – double Output

On exit: define the coordinates $\left(i,j\right)$ and values $A_{ij}$ of the nonzero elements of the linear part $A$ of the function $F\left(x\right)=f\left(x\right)+Ax$.

In particular, nea triples $\left(\mathbf{iafun}\left[k-1\right],\mathbf{javar}\left[k-1\right],\mathbf{a}\left[k-1\right]\right)$ define the row and column indices $i=\mathbf{iafun}\left[k-1\right]$ and $j=\mathbf{javar}\left[k-1\right]$ of the element $A_{ij}=\mathbf{a}\left[k-1\right]$.

7: $\mathbf{lena}$ – Integer Input

On entry: the dimension of the arrays iafun, javar and a that hold $\left(i,j,A_{ij}\right)$. lena should be an overestimate of the number of elements in the linear part of the Jacobian.

Constraint: $\mathbf{lena}\ge 1$.

8: $\mathbf{nea}$ – Integer * Output

On exit: is the number of nonzero entries in $A$ such that $F\left(x\right)=f\left(x\right)+Ax$.

9: $\mathbf{igfun}\left[\mathbf{leng}\right]$ – Integer Output

10: $\mathbf{jgvar}\left[\mathbf{leng}\right]$ – Integer Output

On exit: define the coordinates $\left(i,j\right)$ of the nonzero elements of $G$, the nonlinear part of the derivatives $J\left(x\right)=G\left(x\right)+A$ of the function $F\left(x\right)=f\left(x\right)+Ax$.

11: $\mathbf{leng}$ – Integer Input

On entry: the dimension of the arrays igfun and jgvar that define the varying Jacobian elements $\left(i,j,G_{ij}\right)$. leng should be an overestimate of the number of elements in the nonlinear part of the Jacobian.

Constraint: $\mathbf{leng}\ge 1$.

12: $\mathbf{neg}$ – Integer * Output

On exit: the number of nonzero entries in $G$.

13: $\mathbf{x}\left[\mathbf{n}\right]$ – const double Input

On entry: an initial estimate of the variables $x$. The contents of $x$ 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: $\mathbf{xlow}\left[\mathbf{n}\right]$ – const double Input

15: $\mathbf{xupp}\left[\mathbf{n}\right]$ – const double Input

On entry: contain the lower and upper bounds $l_x$ and $u_x$ on the variables $x$.

To specify a nonexistent lower bound ${\left[l_x\right]}_j=-\infty$, set $\mathbf{xlow}\left[j-1\right]\le -\mathit{bigbnd}$, where $\mathit{bigbnd}$ is the optional parameter $\mathbf{Infinite\; Bound\; Size}$. To specify a nonexistent upper bound $\mathbf{xupp}\left[j-1\right]\ge \mathit{bigbnd}$.

To fix the $j$th variable (say, $x_j=\beta$, where $\left|\beta \right|<\mathit{bigbnd}$), set $\mathbf{xlow}\left[j-1\right]=\mathbf{xupp}\left[j-1\right]=\beta$.

16: $\mathbf{state}$ – Nag_E04State * Communication Structure

state contains internal information required for functions in this suite. It must not be modified in any way.

17: $\mathbf{comm}$ – Nag_Comm *

The NAG communication argument (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).

18: $\mathbf{fail}$ – NagError * Input/Output

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ALLOC_FAIL

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 $〈\mathit{\text{value}}〉$, $〈\mathit{\text{value}}〉$ and $〈\mathit{\text{value}}〉$. Please contact NAG.

NE_ALLOC_INSUFFICIENT

Internal memory allocation was insufficient. Please contact NAG.

NE_ARRAY_TOO_SMALL

Either lena or leng is too small. Increase both of them and corresponding array sizes. $\mathbf{lena}=〈\mathit{\text{value}}〉$ and $\mathbf{leng}=〈\mathit{\text{value}}〉$.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_E04VGC_NOT_INIT

The initialization function e04vgc has not been called.

NE_INT

On entry, $\mathbf{lena}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lena}\ge 1$.

On entry, $\mathbf{leng}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{leng}\ge 1$.

NE_INTERNAL_ERROR

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.

NE_JACOBIAN_STRUCTURE_FAIL

Cannot estimate Jacobian structure at given point x.

NE_NO_LICENCE

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.

NE_USER_STOP

User-supplied function usrfun requested termination.

You have indicated the wish to terminate the call to e04vjc by setting status to a value $<-1$ on exit from usrfun.

NE_USRFUN_UNDEFINED

User-supplied function usrfun indicates that functions are undefined near given point x.

You have indicated that the problem functions are undefined by setting $\mathbf{status}=-1$ on exit from usrfun. This exit occurs if e04vjc is unable to find a point at which the functions are defined.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results