NAG C 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:    $\mathbf{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:    $\mathbf{n}$ – IntegerInput

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

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

3:    $\mathbf{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:    $\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$

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:    $\mathbf{n}$ – IntegerInput

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

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

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

4:    $\mathbf{needf}$ – IntegerInput

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

5:    $\mathbf{nf}$ – IntegerInput

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

6:    $\mathbf{f}\left[\mathbf{nf}\right]$ – 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:    $\mathbf{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:    $\mathbf{leng}$ – IntegerInput

On entry: the dimension of the array g.

9:    $\mathbf{g}\left[\mathbf{leng}\right]$ – 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:  $\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 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.3.1.1 in How to Use the NAG Library and its Documentation).

Note: usrfun should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by nag_opt_sparse_nlp_jacobian (e04vjc). If your code inadvertently does return any NaNs or infinities, nag_opt_sparse_nlp_jacobian (e04vjc) is likely to produce unexpected results.

4:    $\mathbf{iafun}\left[\mathbf{lena}\right]$ – IntegerOutput

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

6:    $\mathbf{a}\left[\mathbf{lena}\right]$ – 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:    $\mathbf{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:    $\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]$ – IntegerOutput

10:  $\mathbf{jgvar}\left[\mathbf{leng}\right]$ – 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:  $\mathbf{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:  $\mathbf{neg}$ – Integer *Output

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

13:  $\mathbf{x}\left[\mathbf{n}\right]$ – 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:  $\mathbf{xlow}\left[\mathbf{n}\right]$ – const doubleInput

15:  $\mathbf{xupp}\left[\mathbf{n}\right]$ – 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 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.3.1.1 in How to Use the NAG Library and its Documentation).

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

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation 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 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.
See Section 2.7.6 in How to Use the NAG Library and its Documentation 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 2.7.5 in How to Use the NAG Library and its Documentation for further information.

NE_USER_STOP

User-supplied function usrfun requested termination.

You have indicated the wish to terminate the call to nag_opt_sparse_nlp_jacobian (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 nag_opt_sparse_nlp_jacobian (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

Program Text (e04vjce.c)

10.2

Program Data

Program Data (e04vjce.d)

10.3

Program Results

Program Results (e04vjce.r)