NAG Library Function Document

nag_opt_sparse_nlp_jacobian (e04vjc)

1  Purpose

2  Specification

3  Description

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

4  References

5  Arguments

1:     nf – IntegerInput

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:     n – IntegerInput

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

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

3:     usrfun – function, supplied by the userExternal Function

usrfun must define the problem functions $F\left(x\right)$. This function is passed to nag_opt_sparse_nlp_jacobian (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:     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$

nag_opt_sparse_nlp_jacobian (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).

nag_opt_sparse_nlp_jacobian (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$, nag_opt_sparse_nlp_jacobian (e04vjc) will use another random perturbation.

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

2:     n – IntegerInput

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

3:     x[n] – const doubleInput

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: $\mathit{nf}$, the number of problem functions.

6:     f[nf] – doubleInput/Output

On entry: this will be set by nag_opt_sparse_nlp_jacobian (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. nag_opt_sparse_nlp_jacobian (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:     needg – IntegerInput

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

8:     leng – IntegerInput

On entry: the dimension of the array g.

9:     g[leng] – doubleInput/Output

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

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

10:   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 nag_opt_sparse_nlp_jacobian (e04vjc) you may allocate memory and initialize these pointers with various quantities for use by usrfun when called from nag_opt_sparse_nlp_jacobian (e04vjc) (see Section 3.2.1.1 in the Essential Introduction).

4:     iafun[lena] – IntegerOutput

5:     javar[lena] – IntegerOutput

6:     a[lena] – doubleOutput

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:     lena – IntegerInput

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:     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:     igfun[leng] – IntegerOutput

10:   jgvar[leng] – IntegerOutput

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:   leng – IntegerInput

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:   neg – Integer *Output

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

13:   x[n] – const doubleInput

On entry: an initial estimate of the variables $x$. The contents of $x$ will be used by nag_opt_sparse_nlp_jacobian (e04vjc) in the call of usrfun, and so each element of x should be within the bounds given by xlow and xupp.

14:   xlow[n] – const doubleInput

15:   xupp[n] – const doubleInput

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 argument $\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:   state – Nag_E04State *Communication Structure

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

17:   comm – Nag_Comm *Communication Structure

The NAG communication argument (see Section 3.2.1.1 in the Essential Introduction).

18:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Internal error: memory allocation failed when attempting to allocate workspace sizes $⟨\mathit{\text{value}}⟩$, $⟨\mathit{\text{value}}⟩$ and $⟨\mathit{\text{value}}⟩$.

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

Initialization function nag_opt_sparse_nlp_init (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.

NE_JACOBIAN_STRUCTURE_FAIL

Cannot estimate Jacobian structure at given point x.

NE_USER_STOP

User-supplied function usrfun requested termination.

NE_USRFUN_UNDEFINED

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

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (e04vjce.c)

10.2  Program Data

Program Data (e04vjce.d)

10.3  Program Results

Program Results (e04vjce.r)