NAG Library Function Document

nag_opt_sparse_nlp_solve (e04vhc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     start – Nag_StartInput

On entry: indicates how a starting point is to be obtained.

$\mathbf{start}=\mathrm{Nag\_Cold}$

Requests that the Crash procedure be used, unless a Basis file is provided via optional arguments $\mathbf{Old\; Basis\; File}$, $\mathbf{Insert\; File}$ or $\mathbf{Load\; File}$.

$\mathbf{start}=\mathrm{Nag\_BasisFile}$

Is the same as $\mathbf{start}=\mathrm{Nag\_Cold}$ but is more meaningful when a Basis file is given.

$\mathbf{start}=\mathrm{Nag\_Warm}$

Means that xstate and fstate define a valid starting point (probably from an earlier call, though not necessarily).

Constraint: $\mathbf{start}=\mathrm{Nag\_Cold}$, $\mathrm{Nag\_BasisFile}$ or $\mathrm{Nag\_Warm}$.

2:     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. 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$.

3:     n – IntegerInput

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

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

4:     nxname – IntegerInput

On entry: the number of names provided in the array xnames.

$\mathbf{nxname}=1$

There are no names provided and generic names will be used in the output.

$\mathbf{nxname}=\mathbf{n}$

Names for all variables must be provided and will be used in the output.

Constraint: $\mathbf{nxname}=1\text{ or }\mathbf{n}$.

5:     nfname – IntegerInput

On entry: the number of names provided in the array fnames.

$\mathbf{nfname}=1$

There are no names provided and generic names will be used in the output.

$\mathbf{nfname}=\mathbf{nf}$

Names for all functions must be provided and will be used in the output.

Constraint: $\mathbf{nfname}=1\text{ or }\mathbf{nf}$.

Note: if $\mathbf{nxname}=1$ then nfname must also be $1$ (and vice versa). Similarly, if $\mathbf{nxname}=\mathbf{n}$ then nfname must be nf (and vice versa).

6:     objadd – doubleInput

On entry: is a constant that will be added to the objective row $F_{\mathrm{obj}}$ for printing purposes. Typically, $\mathbf{objadd}=0.0$.

7:     objrow – Integer Input

On entry: says which row of $F\left(x\right)$ is to act as the objective function. If there is no such row, set $\mathbf{objrow}=0$. Then nag_opt_sparse_nlp_solve (e04vhc) will seek a feasible point such that $l_F\le F\left(x\right)\le u_F$ and $l_x\le x\le u_x$.

Constraint: $1\le \mathbf{objrow}\le \mathbf{nf}\text{ or }\mathbf{objrow}=0$ (or a feasible point problem).

8:     prob – const char *Input

On entry: the name for the problem. prob is used in the printed solution and in some functions that output Basis files. Only the first eight characters of prob are significant.

9:     usrfun – function, supplied by the userExternal Function

usrfun must define the nonlinear portion $f\left(x\right)$ of the problem functions $F\left(x\right)=f\left(x\right)+Ax$, along with its gradient elements $G_{ij}\left(x\right)=\frac{\partial f_i\left(x\right)}{\partial x_j}$. A dummy function is needed even if $f\left(x\right)=0$ and all functions are linear.

In general, usrfun should return all function and gradient values on every entry except perhaps the last. This provides maximum reliability and corresponds to the default option setting, $\mathbf{Derivative\; Option}=1$.

The elements of $G\left(x\right)$ are stored in the array $\mathbf{g}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,\mathbf{leng}$, in the order specified by the input arrays igfun and jgvar.

In practice it is often convenient not to code gradients. nag_opt_sparse_nlp_solve (e04vhc) is able to estimate them by finite differences, using a call to usrfun for each variable $x_j$ for which some $\frac{\partial f_i\left(x\right)}{\partial x_j}$ needs to be estimated. However, this reduces the reliability of the optimization algorithm, and it can be very expensive if there are many such variables $x_j$.

As a compromise, nag_opt_sparse_nlp_solve (e04vhc) allows you to code as many gradients as you like. This option is implemented as follows. Just before usrfun is called, each element of the derivative array g is initialized to a specific value. On exit, any element retaining that value must be estimated by finite differences.

Some rules of thumb follow:

(i)	for maximum reliability, compute all gradients;
(ii)	if the gradients are expensive to compute, specify optional argument $\mathbf{Nonderivative\; Linesearch}$ and use the value of the input argument needg to avoid computing them on certain entries. (There is no need to compute gradients if $\mathbf{needg}=0$ on entry to usrfun.);
(iii)	if not all gradients are known, you must specify $\mathbf{Derivative\; Option}=0$. You should still compute as many gradients as you can. (It often happens that some of them are constant or zero.);
(iv)	again, if the known gradients are expensive, don't compute them if $\mathbf{needg}=0$ on entry to usrfun;
(v)	use the input argument status to test for special actions on the first or last entries;
(vi)	while usrfun is being developed, use the optional argument $\mathbf{Verify\; Level}$ to check the computation of gradients that are supposedly known;
(vii)	usrfun is not called until the linear constraints and bounds on $x$ are satisfied. This helps confine $x$ to regions where the functions $f_i\left(x\right)$ are likely to be defined. However, be aware of the optional argument $\mathbf{Minor\; Feasibility\; Tolerance}$ if the functions have singularities on the constraint boundaries;
(viii)	set $\mathbf{status}=-1$ if some of the functions are undefined. The linesearch will shorten the step and try again;
(ix)	set $\mathbf{status}\le -2$ if you want nag_opt_sparse_nlp_solve (e04vhc) to stop.

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 and last calls to usrfun.

$\mathbf{status}=0$

There is nothing special about the current call to usrfun.

$\mathbf{status}=1$

nag_opt_sparse_nlp_solve (e04vhc) is calling your function for the first time. You may wish to do something special such as read data from a file.

$\mathbf{status}\ge 2$

nag_opt_sparse_nlp_solve (e04vhc) is calling your function for the last time. This argument setting allows you to perform some additional computation on the final solution.

$\mathbf{status}=2$

The current x is optimal.

$\mathbf{status}=3$

The problem appears to be infeasible.

$\mathbf{status}=4$

The problem appears to be unbounded.

$\mathbf{status}=5$

An iterations limit was reached.

If the functions are expensive to evaluate, it may be desirable to do nothing on the last call. The first executable statement could be

if (*status ≥ 2) return;

On exit: may be used to indicate that you are unable to evaluate $f$ or its gradients at the current $x$. (For example, the problem functions may not be defined there.)

During the linesearch, $f\left(x\right)$ is evaluated at points $x=x_k+\alpha p_k$ for various step lengths $\alpha$, where $f\left(x_k\right)$ has already been evaluated satisfactorily. For any such $x$, if you set $\mathbf{status}=-1$, nag_opt_sparse_nlp_solve (e04vhc) will reduce $\alpha$ and evaluate $f$ again (closer to $x_k$, where $f\left(x_k\right)$ is more likely to be defined).

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_solve (e04vhc).

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 whether f must be assigned during this call of usrfun.

$\mathbf{needf}=0$

f is not required and is ignored.

$\mathbf{needf}>0$

The components of $f\left(x\right)$ corresponding to the nonlinear part of $F\left(x\right)$ must be calculated and assigned to f.

If $F_i\left(x\right)$ is linear and completely defined by the $i$th row of $A$, $A_i^{\prime }$, then the associated value $f_i\left(x\right)$ is ignored and need not be assigned. However, if $F_i\left(x\right)$ has a nonlinear portion $f_i\left(x\right)$ that happens to be zero at $x$, then it is still necessary to set $f_i\left(x\right)=0$. If the linear part $A_i^{\prime }$ of a nonlinear $F_i\left(x\right)$ is provided using the arrays iafun, javar and a, then it must not be computed again as part of $f_i\left(x\right)$.

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

needf may also be ignored with $\mathbf{Derivative\; Linesearch}$ and $\mathbf{Derivative\; Option}=1$. In this case, needf is always $1$, and f must always be assigned.

5:     nf – IntegerInput

On entry: is the length of the full vector $F\left(x\right)=f\left(x\right)+Ax$ as defined in the call to nag_opt_sparse_nlp_solve (e04vhc).

6:     f[nf] – doubleInput/Output

On entry: concerns the calculation of $f\left(x\right)$.

On exit: f contains the computed functions $f\left(x\right)$ (except perhaps if $\mathbf{needf}=0$).

7:     needg – IntegerInput

On entry: indicates whether g must be assigned during this call of usrfun.

$\mathbf{needg}=0$

g is not required and is ignored.

$\mathbf{needg}>0$

The partial derivatives of $f\left(x\right)$ must be calculated and assigned to g. The value of $\mathbf{g}\left[k-1\right]$ should be $\frac{\partial f_i\left(x\right)}{\partial x_j}$, where $i=\mathbf{igfun}\left[k-1\right]$, $j=\mathbf{jgvar}\left[k-1\right]$ and $k=1,2,\dots ,\mathbf{leng}$.

8:     leng – IntegerInput

On entry: is the length of the coordinate arrays jgvar and igfun in the call to nag_opt_sparse_nlp_solve (e04vhc).

9:     g[leng] – doubleInput/Output

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

On exit: contains the computed derivatives $G\left(x\right)$ (unless $\mathbf{needg}=0$).

These derivative elements must be stored in g in exactly the same positions as implied by the definitions of arrays igfun and jgvar. There is no internal check for consistency (except indirectly via the optional argument $\mathbf{Verify\; Level}$), so great care is essential.

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

10:   iafun[lena] – const IntegerInput

11:   javar[lena] – const IntegerInput

12:   a[lena] – const doubleInput

On entry: 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]$.

The coordinates may define the elements of $A$ in any order.

13:   lena – IntegerInput

On entry: the dimension of the arrays iafun, javar and a that hold $\left(i,j,A_{ij}\right)$.

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

14:   nea – IntegerInput

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

Constraint: $0\le \mathbf{nea}\le \mathbf{lena}$.

15:   igfun[leng] – const IntegerInput

16:   jgvar[leng] – const IntegerInput

On entry: define the coordinates $\left(i,j\right)$ of the nonzero elements of $G$, the nonlinear part of the derivative $J\left(x\right)=G\left(x\right)+A$ of the function $F\left(x\right)=f\left(x\right)+Ax$. nag_opt_sparse_nlp_jacobian (e04vjc) may be used to define these two arrays.

The coordinates can define the elements of $G$ in any order. However, usrfun must define the actual elements of g in exactly the same order as defined by the coordinates $\left(\mathbf{igfun},\mathbf{jgvar}\right)$.

17:   leng – IntegerInput

On entry: the dimension of the arrays igfun and jgvar that define the varying Jacobian elements $\left(i,j,G_{ij}\right)$.

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

18:   neg – IntegerInput

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

Constraint: $0\le \mathbf{neg}\le \mathbf{leng}$.

19:   xlow[n] – const doubleInput

20:   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 ${\left[u_x\right]}_j=\infty$, set $\mathbf{xupp}\left[j-1\right]\ge \mathit{bigbnd}$.

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

Constraint: $\mathbf{xlow}\left[\mathit{i}-1\right]\le \mathbf{xupp}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$.

21:   xnames[nxname] – const char *Input

On entry: the optional names for the variables.

If $\mathbf{nxname}=1$, xnames is not referenced and default names will be used for output.

If $\mathbf{nxname}=\mathbf{n}$, $\mathbf{xnames}\left[\mathit{j}-1\right]$ must contain the name of the $\mathit{j}$th variable, for $\mathit{j}=1,2,\dots ,\mathbf{nxname}$.

Note: that only the first eight characters of the rows of xnames are significant.

22:   flow[nf] – const doubleInput

23:   fupp[nf] – const doubleInput

On entry: contain the lower and upper bounds $l_F$ and $u_F$ on $F\left(x\right)$.

To specify a nonexistent lower bound ${\left[l_F\right]}_i=-\infty$, set $\mathbf{flow}\left[i-1\right]\le -\mathit{bigbnd}$. For a nonexistent upper bound ${\left[u_F\right]}_i=\infty$, set $\mathbf{fupp}\left[i-1\right]\ge \mathit{bigbnd}$.

To make the $i$th constraint an equality at $F_i=\beta$, where $\left|\beta \right|<\mathit{bigbnd}$, set $\mathbf{flow}\left[i-1\right]=\mathbf{fupp}\left[i-1\right]=\beta$.

Constraint: $\mathbf{flow}\left[\mathit{i}-1\right]\le \mathbf{fupp}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$.

24:   fnames[nfname] – const char *Input

On entry: the optional names for the problem functions.

If $\mathbf{nfname}=1$, fnames is not referenced and default names will be used for the output.

If $\mathbf{nfname}=\mathbf{nf}$, $\mathbf{fnames}\left[\mathit{i}-1\right]$ should contain the name of the $\mathit{i}$th row of $F$, for $\mathit{i}=1,2,\dots ,\mathbf{nfname}$.

Note: that only the first eight characters of the rows of fnames are significant.

25:   x[n] – doubleInput/Output

On entry: an initial estimate of the variables $x$. See the following description of xstate.

On exit: the final values of the variable $x$.

26:   xstate[n] – IntegerInput/Output

On entry: the initial state for each variable $x$.

If $\mathbf{start}=\mathrm{Nag\_Cold}$ or $\mathrm{Nag\_BasisFile}$ and no basis information is provided (the optional arguments $\mathbf{Old\; Basis\; File}$, $\mathbf{Insert\; File}$ and $\mathbf{Load\; File}$ are all set to $0$; the default) x and xstate must be defined.

If nothing special is known about the problem, or if there is no wish to provide special information, you may set $\mathbf{x}\left[j-1\right]=0.0$, $\mathbf{xstate}\left[j-1\right]=0$, for all $j=1,2,\dots ,\mathbf{n}$. If you set $\mathbf{x}\left[j-1\right]=\mathbf{xlow}\left[j-1\right]$ set $\mathbf{xstate}\left[j-1\right]=4$; if you set $\mathbf{x}\left[j-1\right]=\mathbf{xupp}\left[j-1\right]$ then set $\mathbf{xstate}\left[j-1\right]=5$. In this case a Crash procedure is used to select an initial basis.

If $\mathbf{start}=\mathrm{Nag\_Cold}$ or $\mathrm{Nag\_BasisFile}$ and basis information is provided (at least one of the optional arguments $\mathbf{Old\; Basis\; File}$, $\mathbf{Insert\; File}$ and $\mathbf{Load\; File}$ is nonzero) x and xstate need not be set.

If $\mathbf{start}=\mathrm{Nag\_Warm}$, x and xstate must be set (probably from a previous call). In this case $\mathbf{xstate}\left[\mathit{j}-1\right]$ must be $0$, $1$, $2\text{ or }3$, for $\mathit{j}=1,2,\dots ,\mathbf{n}$.

On exit: the final state of the variables.

$\mathbf{xstate}\left[j-1\right]$	State of variable $j$	Usual value of $\mathbf{x}\left[j-1\right]$
0	nonbasic	$\mathbf{xlow}\left[j-1\right]$
1	nonbasic	$\mathbf{xupp}\left[j-1\right]$
2	superbasic	Between $\mathbf{xlow}\left[j-1\right]$ and $\mathbf{xupp}\left[j-1\right]$
3	basic	Between $\mathbf{xlow}\left[j-1\right]$ and $\mathbf{xupp}\left[j-1\right]$

Basic and superbasic variables may be outside their bounds by as much as the optional argument $\mathbf{Minor\; Feasibility\; Tolerance}$. Note that if scaling is specified, the feasibility tolerance applies to the variables of the scaled problem. In this case, the variables of the original problem may be as much as $0.1$ outside their bounds, but this is unlikely unless the problem is very badly scaled. Check the value of Primal infeasibility output to the unit number associated with the optional argument $\mathbf{Print\; File}$.

Very occasionally some nonbasic variables may be outside their bounds by as much as the optional argument $\mathbf{Minor\; Feasibility\; Tolerance}$, and there may be some nonbasics for which $\mathbf{x}\left[j-1\right]$ lies strictly between its bounds.

If $\mathbf{ninf}>0$, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by sinf if scaling was not used).

Constraint: $0\le \mathbf{xstate}\left[j-1\right]\le 5\text{, for }j=1,2,\dots ,\mathbf{n}$.

27:   xmul[n] – doubleOutput

On exit: the vector of the dual variables (Lagrange multipliers) for the simple bounds $l_x\le x\le u_x$.

28:   f[nf] – doubleInput/Output

On entry: an initial value for the problem functions $F$. See the following description of fstate.

On exit: the final values for the problem functions $F$ (the values $F$ at the final point x).

29:   fstate[nf] – IntegerInput/Output

On entry: the initial state for the problem functions $F$.

If $\mathbf{start}=\mathrm{Nag\_Cold}$ or $\mathrm{Nag\_BasisFile}$ and no basis information is provided (the optional arguments $\mathbf{Old\; Basis\; File}$, $\mathbf{Insert\; File}$ and $\mathbf{Load\; File}$ are all set to $0$; the default, f and fstate must be defined.

If nothing special is known about the problem, or if there is no wish to provide special information, you may set $\mathbf{f}\left[i-1\right]=0.0$, $\mathbf{fstate}\left[i-1\right]=0$, for all $i=1,2,\dots ,\mathbf{nf}$. Less trivially, to say that the optimal value of function $\mathbf{f}\left[i-1\right]$ will probably be equal to one of its bounds, set $\mathbf{f}\left[i-1\right]=\mathbf{flow}\left[i-1\right]$ and $\mathbf{fstate}\left[i-1\right]=4$ or $\mathbf{f}\left[i-1\right]=\mathbf{fupp}\left[i-1\right]$ and $\mathbf{fstate}\left[i-1\right]=5$ as appropriate. In this case a Crash procedure is used to select an initial basis.

If $\mathbf{start}=\mathrm{Nag\_Cold}$ or $\mathrm{Nag\_BasisFile}$ and basis information is provided (at least one of the optional arguments $\mathbf{Old\; Basis\; File}$, $\mathbf{Insert\; File}$ and $\mathbf{Load\; File}$ is nonzero), f and fstate need not be set.

If $\mathbf{start}=\mathrm{Nag\_Warm}$, f and fstate must be set (probably from a previous call). In this case $\mathbf{fstate}\left[\mathit{i}-1\right]$ must be $0$, $1$, $2$ or $3$, for $\mathit{i}=1,2,\dots ,\mathbf{nf}$.

On exit: the final state of the variables. The elements of fstate have the following meaning:

$\mathbf{fstate}\left[i-1\right]$	State of the corresponding slack variable	Usual value of $\mathbf{f}\left[i-1\right]$
0	nonbasic	$\mathbf{flow}\left[i-1\right]$
1	nonbasic	$\mathbf{fupp}\left[i-1\right]$
2	superbasic	Between $\mathbf{flow}\left[i-1\right]$ and $\mathbf{fupp}\left[i-1\right]$
3	basic	Between $\mathbf{flow}\left[i-1\right]$ and $\mathbf{fupp}\left[i-1\right]$

Basic and superbasic slack variables may lead to the corresponding functions being outside their bounds by as much as the optional argument $\mathbf{Minor\; Feasibility\; Tolerance}$.

Very occasionally some functions may be outside their bounds by as much as the optional argument $\mathbf{Minor\; Feasibility\; Tolerance}$, and there may be some nonbasics for which $\mathbf{f}\left[i-1\right]$ lies strictly between its bounds.

If $\mathbf{ninf}>0$, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by sinf if scaling was not used).

Constraint: $0\le \mathbf{fstate}\left[i-1\right]\le 5\text{, for }i=1,2,\dots ,\mathbf{nf}$.

30:   fmul[nf] – doubleInput/Output

On entry: an estimate of $\gamma$, the vector of Lagrange multipliers (shadow prices) for the constraints $l_F\le F\left(x\right)\le u_F$. All nf components must be defined. If nothing is known about $\gamma$, set $\mathbf{fmul}\left[\mathit{i}-1\right]=0.0$, for $\mathit{i}=1,2,\dots ,\mathbf{nf}$. For warm start use the values from a previous call.

On exit: the vector of the dual variables (Lagrange multipliers) for the general constraints $l_F\le F\left(x\right)\le u_F$ 

31:   ns – Integer *Input/Output

On entry: the number of superbasic variables. ns need not be specified for cold starts, but should retain its value from a previous call when warm start is used.

On exit: the final number of superbasic variables.

32:   ninf – Integer *Output

33:   sinf – double *Output

On exit: are the number and the sum of the infeasibilities of constraints that lie outside one of their bounds by more than the optional argument $\mathbf{Minor\; Feasibility\; Tolerance}$ before the solution is unscaled.

If any linear constraints are infeasible, $x$ minimizes the sum of the infeasibilities of the linear constraints subject to the upper and lower bounds being satisfied. In this case ninf gives the number of variables and linear constraints lying outside their upper or lower bounds. The nonlinear constraints are not evaluated.

Otherwise, $x$ minimizes the sum of infeasibilities of the nonlinear constraints subject to the linear constraints and upper and lower bounds being satisfied. In this case ninf gives the number of components of $F\left(x\right)$ lying outside their bounds by more than the optional argument $\mathbf{Minor\; Feasibility\; Tolerance}$. Again this is before the solution is unscaled.

34:   state – Nag_E04State *Communication Structure

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

35:   comm – Nag_Comm *Communication Structure

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

36:   fail – NagError *Input/Output

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

nag_opt_sparse_nlp_solve (e04vhc) returns with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_NOERROR if the iterates have converged to a point $x$ that satisfies the first-order Kuhn–Tucker (see Section 13.2) conditions to the accuracy requested by the optional argument $\mathbf{Major\; Optimality\; Tolerance}$, i.e., the projected gradient and active constraint residuals are negligible at $x$.

You should check whether the following four conditions are satisfied:

(i)	the final value of rgNorm (see Section 13.2) is significantly less than that at the starting point;
(ii)	during the final major iterations, the values of Step and Minors (see Section 13.1) are both one;
(iii)	the last few values of both rgNorm and SumInf (see Section 13.2) become small at a fast linear rate; and
(iv)	condHz (see Section 13.1) is small.

If all these conditions hold, $x$ is almost certainly a local minimum of (1).

One caution about ‘Optimal solutions’. Some of the variables or slacks may lie outside their bounds more than desired, especially if scaling was requested. Max Primal infeas in the Print file (see Section 13) refers to the largest bound infeasibility and which variable is involved. If it is too large, consider restarting with a smaller $\mathbf{Minor\; Feasibility\; Tolerance}$ (say $10$ times smaller) and perhaps $\mathbf{Scale\; Option}=0$.

Similarly, Max Dual infeas in the Print file indicates which variable is most likely to be at a nonoptimal value. Broadly speaking, if

$$\mathtt{Max\; Dual\; infeas}/\mathtt{Max\; pi}={10}^{-d}\text{,}$$

then the objective function would probably change in the $d$th significant digit if optimization could be continued. If $d$ seems too large, consider restarting with a smaller $\mathbf{Major\; Optimality\; Tolerance}$.

Finally, Nonlinear constraint violn in the Print file shows the maximum infeasibility for nonlinear rows. If it seems too large, consider restarting with a smaller $\mathbf{Major\; Feasibility\; Tolerance}$.

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.

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_INPUT

Array element $\mathbf{igfun}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$ is out of range $1$ to $\mathbf{nf}=⟨\mathit{\text{value}}⟩$, or array element $\mathbf{jgvar}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$ is out of range $1$ to $\mathbf{n}=⟨\mathit{\text{value}}⟩$.

NE_BAD_PARAM

Basis file dimensions do not match this problem.

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_BASIS_FAILURE

An error has occurred in the basis package. Check that arrays iafun, javar, igfun and jgvar contain values in the appropriate ranges and do not define duplicate elements of a or g. Set the optional argument $\mathbf{Print\; File}$ and examine the output carefully for further information.

NE_DERIV_ERRORS

User-supplied function computes incorrect constraint derivatives.

User-supplied function computes incorrect objective derivatives.

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

On entry, $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{n}>0$.

On entry, $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{n}\ge 1$.

On entry, $\mathbf{nea}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nea}\ge 0$.

On entry, $\mathbf{neg}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{neg}\ge 0$.

On entry, $\mathbf{nf}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nf}>0$.

On entry, $\mathbf{nf}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nf}\ge 1$.

NE_INT_2

On entry, $\mathbf{nfname}=⟨\mathit{\text{value}}⟩$ and $\mathbf{nf}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nfname}=1\text{ or }\mathbf{nf}$.

On entry, $\mathbf{nxname}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nxname}=1\text{ or }\mathbf{n}$.

On entry, $\mathbf{objrow}=⟨\mathit{\text{value}}⟩$ and $\mathbf{nf}=⟨\mathit{\text{value}}⟩$.
Constraint: $0\le \mathbf{objrow}\le \mathbf{nf}$.

On entry, one but not both of nxname and nfname is equal to $1$. $\mathbf{nxname}=⟨\mathit{\text{value}}⟩$ and $\mathbf{nfname}=⟨\mathit{\text{value}}⟩$.

NE_INT_3

On entry, $\mathbf{nea}=⟨\mathit{\text{value}}⟩$, $\mathbf{n}=⟨\mathit{\text{value}}⟩$ and $\mathbf{nf}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nea}\le \mathbf{n}\times \mathbf{nf}$.

On entry, $\mathbf{neg}=⟨\mathit{\text{value}}⟩$, $\mathbf{n}=⟨\mathit{\text{value}}⟩$ and $\mathbf{nf}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{neg}\le \mathbf{n}\times \mathbf{nf}$.

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.

An unexpected error has occurred. Set the optional argument $\mathbf{Print\; File}$ and examine the output carefully for further information.

NE_NOT_REQUIRED_ACC

The requested accuracy could not be achieved.

NE_NUM_DIFFICULTIES

Numerical difficulties have been encountered and no further progress can be made.

NE_REAL_2

On entry, bounds flow and fupp for $⟨\mathit{\text{value}}⟩$ are equal and infinite. $\mathbf{flow}=\mathbf{fupp}=⟨\mathit{\text{value}}⟩$ and $\mathit{infbnd}=⟨\mathit{\text{value}}⟩$.

On entry, bounds flow and fupp for variable $⟨\mathit{\text{value}}⟩$ are equal and infinite. $\mathbf{flow}=\mathbf{fupp}=⟨\mathit{\text{value}}⟩$ and $\mathit{infbnd}=⟨\mathit{\text{value}}⟩$.

On entry, bounds for $⟨\mathit{\text{value}}⟩$ are inconsistent. $\mathbf{flow}=⟨\mathit{\text{value}}⟩$ and $\mathbf{fupp}=⟨\mathit{\text{value}}⟩$.

On entry, bounds for $⟨\mathit{\text{value}}⟩$ are inconsistent. $\mathbf{xlow}=⟨\mathit{\text{value}}⟩$ and $\mathbf{xupp}=⟨\mathit{\text{value}}⟩$.

On entry, bounds for variable $⟨\mathit{\text{value}}⟩$ are inconsistent. $\mathbf{flow}=⟨\mathit{\text{value}}⟩$ and $\mathbf{fupp}=⟨\mathit{\text{value}}⟩$.

On entry, bounds for variable $⟨\mathit{\text{value}}⟩$ are inconsistent. $\mathbf{xlow}=⟨\mathit{\text{value}}⟩$ and $\mathbf{xupp}=⟨\mathit{\text{value}}⟩$.

On entry, bounds xlow and xupp for $⟨\mathit{\text{value}}⟩$ are equal and infinite. $\mathbf{xlow}=\mathbf{xupp}=⟨\mathit{\text{value}}⟩$ and $\mathit{infbnd}=⟨\mathit{\text{value}}⟩$.

On entry, bounds xlow and xupp for variable $⟨\mathit{\text{value}}⟩$ are equal and infinite. $\mathbf{xlow}=\mathbf{xupp}=⟨\mathit{\text{value}}⟩$ and $\mathit{infbnd}=⟨\mathit{\text{value}}⟩$.

NE_UNBOUNDED

The problem appears to be unbounded. The constraint violation limit has been reached.

The problem appears to be unbounded. The objective function is unbounded.

NE_USER_STOP

User-supplied function requested termination.

NE_USRFUN_UNDEFINED

Unable to proceed into undefined region of user-supplied function.

User-supplied function is undefined at the first feasible point.

User-supplied function is undefined at the initial point.

NW_LIMIT_REACHED

Iteration limit reached.

Major iteration limit reached.

The value of the optional argument $\mathbf{Superbasics\; Limit}$ is too small.

NW_NOT_FEASIBLE

The linear constraints appear to be infeasible.

The problem appears to be infeasible. Infeasibilites have been minimized.

The problem appears to be infeasible. Nonlinear infeasibilites have been minimized.

The problem appears to be infeasible. The linear equality constraints could not be satisfied.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

9.1  The Final Output

9.1.1  The ROWS section

9.1.2  The COLUMNS section

10  Example

10.1  Program Text

Program Text (e04vhce.c)

10.2  Program Data

Program Data (e04vhce.d)

10.3  Program Results

Program Results (e04vhce.r)

11  Algorithmic Details

11.1  Constraints and Slack Variables

11.2  Major Iterations

11.3  Minor Iterations

11.4  The Merit Function

11.5  Treatment of Constraint Infeasibilities

12  Optional Arguments

• Backup Basis File
• Central Difference Interval
• Check Frequency
• Crash Option
• Crash Tolerance
• Defaults
• Derivative Linesearch
• Derivative Option
• Difference Interval
• Dump File
• Elastic Weight
• Expand Frequency
• Factorization Frequency
• Feasibility Tolerance
• Feasible Point
• Function Precision
• Hessian Frequency
• Hessian Full Memory
• Hessian Limited Memory
• Hessian Updates
• Infinite Bound Size
• Insert File
• Iterations Limit
• Linesearch Tolerance
• List
• Load File
• LU Complete Pivoting
• LU Density Tolerance
• LU Factor Tolerance
• LU Partial Pivoting
• LU Rook Pivoting
• LU Singularity Tolerance
• LU Update Tolerance
• Major Feasibility Tolerance
• Major Iterations Limit
• Major Optimality Tolerance
• Major Print Level
• Major Step Limit
• Maximize
• Minimize
• Minor Feasibility Tolerance
• Minor Iterations Limit
• Minor Print Level
• New Basis File
• New Superbasics Limit
• Nolist
• Nonderivative Linesearch
• Old Basis File
• Partial Price
• Pivot Tolerance
• Print File
• Print Frequency
• Proximal Point Method
• Punch File
• Save Frequency
• Scale Option
• Scale Print
• Scale Tolerance
• Solution File
• Summary File
• Summary Frequency
• Superbasics Limit
• Suppress Parameters
• System Information No
• System Information Yes
• Timing Level
• Unbounded Objective
• Unbounded Step Size
• Verify Level
• Violation Limit

Begin
   Print Level = 5
End

e04vkc (ioptns, &state, &fail);

e04vlc ("Print Level = 5", &state, &fail);

12.1  Description of the Optional Arguments

• the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
• a parameter value, where the letters $a$, $i\text{ and }r$ denote options that take character, integer and real values respectively;
• the default value, where the symbol $\epsilon$ is a generic notation for machine precision (see nag_machine_precision (X02AJC)), and ${\epsilon }_r$ denotes the relative precision of the objective function $\mathbf{Function\; Precision}$, and $\mathit{bigbnd}$ signifies the value of $\mathbf{Infinite\; Bound\; Size}$.