NAG Library Routine Document

E04VJF

1  Purpose

2  Specification

3  Description

CALL E04VGF (CW, LENCW, ... )
CALL E04VJF (NF, N, ... )
CALL E04VLF ('Derivative Option = 0', CW, ... )
CALL E04VHF (START, NF, ... )

4  References

5  Parameters

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 parameters 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 – SUBROUTINE, supplied by the user.External Procedure

USRFUN must define the problem functions $F\left(x\right)$. This subroutine is passed to E04VJF as the external parameter USRFUN.

The specification of USRFUN is:

SUBROUTINE USRFUN ( STATUS, N, X, NEEDF, NF, F, NEEDG, LENG, G, CUSER, IUSER, RUSER) INTEGER  STATUS, N, NEEDF, NF, NEEDG, LENG, IUSER(*) REAL (KIND=nag_wp)  X(N), F(NF), G(LENG), RUSER(*) CHARACTER(8)  CUSER(*)

1:     STATUS – INTEGERInput/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$

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 $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$, E04VJF 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 E04VJF.

3:     X(N) – 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: $\mathit{nf}$, the number of problem functions.

6:     F(NF) – REAL (KIND=nag_wp) arrayInput/Output

On entry: this will be set by E04VJF.

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. E04VJF 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: E04VJF 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 as declared in the (sub)program from which E04VJF is called.

9:     G(LENG) – REAL (KIND=nag_wp) arrayInput/Output

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

On exit: E04VJF will always call USRFUN with $\mathbf{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 parameters CUSER, IUSER and RUSER as supplied to E04VJF. You are free to use the arrays CUSER, IUSER and RUSER to supply information to USRFUN as an alternative to using COMMON global variables.

USRFUN must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which E04VJF is called. Parameters denoted as Input must not be changed by this procedure.

4:     IAFUN(LENA) – INTEGER arrayOutput

5:     JAVAR(LENA) – INTEGER arrayOutput

6:     A(LENA) – REAL (KIND=nag_wp) arrayOutput

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\right),\mathbf{JAVAR}\left(k\right),\mathbf{A}\left(k\right)\right)$ define the row and column indices $i=\mathbf{IAFUN}\left(k\right)$ and $j=\mathbf{JAVAR}\left(k\right)$ of the element $A_{ij}=\mathbf{A}\left(k\right)$.

7:     LENA – INTEGERInput

On entry: the dimension of the arrays IAFUN, JAVAR and A that hold $\left(i,j,A_{ij}\right)$ 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: $\mathbf{LENA}\ge 1$.

8:     NEA – INTEGEROutput

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

9:     IGFUN(LENG) – INTEGER arrayOutput

10:   JGVAR(LENG) – INTEGER arrayOutput

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)$ 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: $\mathbf{LENG}\ge 1$.

12:   NEG – INTEGEROutput

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

13:   X(N) – 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:   XLOW(N) – REAL (KIND=nag_wp) arrayInput

15:   XUPP(N) – REAL (KIND=nag_wp) arrayInput

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\right)\le -\mathit{bigbnd}$, where $\mathit{bigbnd}$ is the optional parameter Infinite Bound Size. To specify a nonexistent upper bound $\mathbf{XUPP}\left(j\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\right)=\mathbf{XUPP}\left(j\right)=\beta$.

16:   CW(LENCW) – 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: $\mathbf{LENCW}\ge 600$.

18:   IW(LENIW) – 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: $\mathbf{LENIW}\ge 600$.

20:   RW(LENRW) – 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: $\mathbf{LENRW}\ge 600$.

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 as an alternative to using COMMON global variables.

25:   IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ 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 parameter, the recommended value is $0$. When the value $-\mathbf{1}\text{ or }\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.

On exit: $\mathbf{IFAIL}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

$\mathbf{IFAIL}=1$

The initialization routine E04VGF has not been called or at least one of LENCW, LENIW or LENRW is less than $600$.

$\mathbf{IFAIL}=2$

An input parameter is invalid. The output message provides more details of the invalid parameter.

$\mathbf{IFAIL}=3$

Undefined user-supplied function.

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

$\mathbf{IFAIL}=4$

User requested termination.

You have indicated the wish to terminate the call to E04VJF by setting STATUS to a value $<-1$ on exit from USRFUN.

$\mathbf{IFAIL}=5$

Either LENA or LENG is too small, resulting in insufficient array to store the Jacobian information. Increase LENA and/or LENG

$\mathbf{IFAIL}=6$

Unable to estimate the Jacobian structure.

$\mathbf{IFAIL}=7$

Internal memory allocation failed when attempting to obtain the required workspace. Please contact NAG.

$\mathbf{IFAIL}=8$

Internal memory allocation insufficient. Please contact NAG.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (e04vjfe.f90)

9.2  Program Data

Program Data (e04vjfe.d)

9.3  Program Results

Program Results (e04vjfe.r)