NAG FL Interface
e04kff (handle_​solve_​bounds_​foas)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{handle}$ – Type (c_ptr) Input

On entry: the handle to the problem. It needs to be initialized (e.g., by e04raf) and to hold a problem formulation compatible with e04kff. It must not be changed between calls to the NAG optimization modelling suite.

2: $\mathbf{objfun}$ – Subroutine, supplied by the NAG Library or the user. External Procedure

objfun must calculate the value of the nonlinear objective function $f\left(x\right)$ at a specified point $x$. If there is no nonlinear objective (e.g., e04ref or e04rff was called to define a linear or quadratic objective function), objfun will never be called by e04kff and may be the dummy routine e04kfv (included in the NAG Library.)

The specification of objfun is:

Fortran Interface copy

Subroutine objfun ( nvar, x, fx, inform, iuser, ruser, cpuser) Integer, Intent (In) :: nvar Integer, Intent (Inout) :: inform, iuser(*) Real (Kind=nag_wp), Intent (In) :: x(nvar) Real (Kind=nag_wp), Intent (Inout) :: ruser(*) Real (Kind=nag_wp), Intent (Out) :: fx Type (c_ptr), Intent (In) :: cpuser

C Header Interface copy

void  objfun (const Integer *nvar, const double x[], double *fx, Integer *inform, Integer iuser[], double ruser[], void **cpuser)

C++ Header Interface copy

#include <nag.h> extern "C" { void  objfun (const Integer &nvar, const double x[], double &fx, Integer &inform, Integer iuser[], double ruser[], void *&cpuser) }

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

On entry: $n$, the current number of decision variables $x$ in the model.

2: $\mathbf{x}\left(\mathbf{nvar}\right)$ – Real (Kind=nag_wp) array Input

On entry: the vector $x$ of variable values at which the objective function is to be evaluated.

3: $\mathbf{fx}$ – Real (Kind=nag_wp) Output

On exit: the value of the objective function at $x$.

4: $\mathbf{inform}$ – Integer Input/Output

On entry: a non-negative value.

In some cases, it is known beforehand that the evaluations of the objective function and its gradient are required at the same point $x$, in such cases, $\mathbf{inform}=1$. This may help to optimize your code in order to avoid recalculations of common quantities when evaluating both the objective function and gradient; the objective function is always evaluated before the objective gradient. This notification parameter may be safely ignored if such optimization is not required.

On exit: may be used to indicate that the function cannot be evaluated at the requested point $x$ by setting $\mathbf{inform}<0$. Returning NaN or $\pm \infty$ in fx has the same effect. The algorithm will try to recover if the objective cannot be evaluated; if recovery is not possible it will stop with $\mathbf{ifail}=\mathbf{25}$.

5: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

6: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

7: $\mathbf{cpuser}$ – Type (c_ptr) User Workspace

objfun is called with the arguments iuser, ruser and cpuser as supplied to e04kff. You should use the arrays iuser and ruser, and the data handle cpuser to supply information to objfun.

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

3: $\mathbf{objgrd}$ – Subroutine, supplied by the NAG Library or the user. External Procedure

objgrd must calculate the values of the nonlinear objective function gradient $\frac{\partial f}{\partial x}$ at a specified point $x$. Every call to objgrd is preceded by a call to objfun at the same point, if this is known in advance, both functions will be notified via $\mathbf{inform}=1$. If there is no nonlinear objective (e.g., e04ref or e04rff was called to define a linear or quadratic objective function), objgrd will never be called by e04kff and objgrd may be the dummy subroutine e04kfw (included in the NAG Library.)

If the optional parameter $\mathbf{FOAS\; Estimate\; Derivatives}=\mathrm{YES}$, then after returning from objgrd the gradient vector is checked for missing entries which you have not supplied. Missing entries are estimated using the finite difference method, see optional parameter FOAS Estimate Derivatives description for more details.

The specification of objgrd is:

Fortran Interface copy

Subroutine objgrd ( nvar, x, nnzfd, fdx, inform, iuser, ruser, cpuser) Integer, Intent (In) :: nvar, nnzfd Integer, Intent (Inout) :: inform, iuser(*) Real (Kind=nag_wp), Intent (In) :: x(nvar) Real (Kind=nag_wp), Intent (Inout) :: fdx(nnzfd), ruser(*) Type (c_ptr), Intent (In) :: cpuser

C Header Interface copy

void  objgrd (const Integer *nvar, const double x[], const Integer *nnzfd, double fdx[], Integer *inform, Integer iuser[], double ruser[], void **cpuser)

C++ Header Interface copy

#include <nag.h> extern "C" { void  objgrd (const Integer &nvar, const double x[], const Integer &nnzfd, double fdx[], Integer &inform, Integer iuser[], double ruser[], void *&cpuser) }

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

On entry: $n$, the current number of decision variables $x$ in the model.

2: $\mathbf{x}\left(\mathbf{nvar}\right)$ – Real (Kind=nag_wp) array Input

On entry: the vector $x$ of variable values at which the objective function gradient is to be evaluated.

3: $\mathbf{nnzfd}$ – Integer Input

On entry: the number of nonzero elements in the sparse gradient vector of the objective function, as was set in a previous call to e04rgf.

4: $\mathbf{fdx}\left(\mathbf{nnzfd}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: the elements should only be assigned and not referenced.

On exit: the values of the nonzero elements in the sparse gradient vector of the objective function, in the order specified by idxfd in a previous call to e04rgf. $\mathbf{fdx}\left(\mathit{i}\right)$ will store the gradient element $\frac{\partial f}{\partial x_{\mathbf{idxfd}\left(\mathit{i}\right)}}$.

5: $\mathbf{inform}$ – Integer Input/Output

On entry: a non-negative value.

If $\mathbf{inform}=1$, then the previous call to objfun was also made at the same point $x$ with $\mathbf{inform}=1$. This may help to optimize your code in order to avoid recalculations of common quantities when evaluating both the objective function and gradient. This notification parameter may be safely ignored if such optimization is not required.

On exit: may be used to inform that the gradient cannot be evaluated at the requested point $x$ by setting $\mathbf{inform}<0$. Returning NaN or $\pm \infty$ in any element of fdx has the same effect. The algorithm will try to recover if the gradient cannot be evaluated; if recovery is not possible it will stop with $\mathbf{ifail}=\mathbf{25}$.

6: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

7: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

8: $\mathbf{cpuser}$ – Type (c_ptr) User Workspace

objgrd is called with the arguments iuser, ruser and cpuser as supplied to e04kff. You should use the arrays iuser and ruser, and the data handle cpuser to supply information to objgrd.

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

4: $\mathbf{monit}$ – Subroutine, supplied by the NAG Library or the user. External Procedure

monit is provided to enable you to monitor the progress of the optimization and optionally to terminate the solver early if necessary. It is invoked at the end of every $i$th iteration where $i$ is given by the FOAS Monitor Frequency (the default is $0$, monit is not called).

monit may be the dummy subroutine e04kfu (included in the NAG Library).

The specification of monit is:

Fortran Interface copy

Subroutine monit ( nvar, x, inform, rinfo, stats, iuser, ruser, cpuser) Integer, Intent (In) :: nvar Integer, Intent (Inout) :: inform, iuser(*) Real (Kind=nag_wp), Intent (In) :: x(nvar), rinfo(100), stats(100) Real (Kind=nag_wp), Intent (Inout) :: ruser(*) Type (c_ptr), Intent (In) :: cpuser

C Header Interface copy

void  monit (const Integer *nvar, const double x[], Integer *inform, const double rinfo[], const double stats[], Integer iuser[], double ruser[], void **cpuser)

C++ Header Interface copy

#include <nag.h> extern "C" { void  monit (const Integer &nvar, const double x[], Integer &inform, const double rinfo[], const double stats[], Integer iuser[], double ruser[], void *&cpuser) }

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

On entry: $n$, the current number of decision variables $x$ in the model.

2: $\mathbf{x}\left(\mathbf{nvar}\right)$ – Real (Kind=nag_wp) array Input

On entry: the vector $x$ of decision variables at the current iteration.

3: $\mathbf{inform}$ – Integer Input/Output

On entry: a non-negative value.

On exit: may be used to request the solver to stop immediately. Specifically, if $\mathbf{inform}<0$ the solver will terminate immediately with $\mathbf{ifail}=\mathbf{20}$; otherwise, the solver will proceed normally.

4: $\mathbf{rinfo}\left(100\right)$ – Real (Kind=nag_wp) array Input

On entry: error measures and various indicators at the end of the current iteration as described in rinfo.

5: $\mathbf{stats}\left(100\right)$ – Real (Kind=nag_wp) array Input

On entry: solver statistics at the end of the current iteration as described in stats.

6: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

7: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

8: $\mathbf{cpuser}$ – Type (c_ptr) User Workspace

monit is called with the arguments iuser, ruser and cpuser as supplied to e04kff. You should use the arrays iuser and ruser, and the data handle cpuser to supply information to monit.

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

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

On entry: $n$, the current number of decision variables $x$ in the model.

6: $\mathbf{x}\left(\mathbf{nvar}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: $x_0$, the initial estimates of the variables, $x$.

On exit: the final values of the variables, $x$.

7: $\mathbf{rinfo}\left(100\right)$ – Real (Kind=nag_wp) array Output

On exit: error measures and various indicators at the end of the final iteration as given in the table below:

$1$	Objective function value $\mathrm{f}\left(x\right)$.
$2$	Norm of inactive gradient, the objective gradient over the current search space. If the problem is unconstrained, then elements $2$–$4$ coincide. See Section 11.4 for details.
$3$	Norm of projected direction, used in (3), see Section 11.2.
$4$	Norm of objective gradient.
$5$	Last step size (${\alpha }_k$) used in (2) and (5), see Section 11.2 and Section 11.3.
$6$	Progress score, a positive value that measures the progress of the solver. A low score close to zero indicates poor progress, see (8) in Section 11.4.
$7$–$100$	Reserved for future use.

8: $\mathbf{stats}\left(100\right)$ – Real (Kind=nag_wp) array Output

On exit: solver statistics at the end of the final iteration as given in the table below:

$1$	Number of function evaluations performed by NPG, see Section 11.2.
$2$	Number of gradient evaluations performed by NPG.
$3$	Number of function evaluations performed by CG, see Section 11.3.
$4$	Number of gradient evaluations performed by CG.
$5$	Number of function evaluations performed by LCG.
$6$	Number of gradient evaluations performed by LCG.
$7$	Number of function evaluations used by the finite difference method to estimate missing components of the gradient.
$8$	Number of iterations.
$9$	Total time spent in the solver (including user-supplied function calls).
$10$	Total time spent in user-supplied objective function.
$11$	Total time spent in user-supplied objective gradient.
$12$–$100$	Reserved for future use.

9: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

10: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

11: $\mathbf{cpuser}$ – Type (c_ptr) User Workspace

iuser, ruser and cpuser are not used by e04kff, but are passed directly to objfun, objgrd and monit and may be used to pass information to these routines. If you do not need to reference cpuser, it should be initialized to c_null_ptr.

12: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $-1$ is recommended since useful values can be provided in some output arguments even when $\mathbf{ifail}\ne \mathbf{0}$ on exit. When the value $-\mathbf{1}$ 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 supplied handle does not define a valid handle to the data structure for the NAG optimization modelling suite. It has not been properly initialized or it has been corrupted.

$\mathbf{ifail}=2$

The problem is already being solved.

This solver does not support the model defined in the handle.

$\mathbf{ifail}=4$

On entry, $\mathbf{nvar}=⟨\mathit{\text{value}}⟩$, expected $\mathrm{value}=⟨\mathit{\text{value}}⟩$.
Constraint: nvar must match the current number of variables of the model in the handle.

$\mathbf{ifail}=7$

The dummy objfun routine was called but the problem requires these values. Please provide a proper objfun routine.

The dummy objgrd routine was called but the problem requires these derivatives. Please provide a proper objgrd routine.

$\mathbf{ifail}=20$

User requested termination during a monitoring step. inform was set to a negative value in monit.

$\mathbf{ifail}=21$

The current starting point is unusable.

Either inform was set to a negative value within the user-supplied functions objfun, objgrd, or an Infinity or NaN was detected in values returned from them.

$\mathbf{ifail}=22$

Maximum number of iterations reached.

$\mathbf{ifail}=23$

The solver terminated after the maximum time allowed was exhausted.

Maximum number of seconds exceeded. Use optional parameter Time Limit to change the limit.

$\mathbf{ifail}=24$

The solver was terminated because no further progress could be achieved.

This can indicate that the solver is calculating very small step sizes and is making very little progress. It could also indicate that the problem has been solved to the best numerical accuracy possible given the current scaling.

$\mathbf{ifail}=25$

Invalid number detected in user-supplied function and recovery failed.

Either inform was set to a negative value within the user-supplied function objfun, or an Infinity or NaN was detected in values returned from them. Recovery attempts failed.

Invalid number detected in user-supplied gradient and recovery failed.

Either inform was set to a negative value within the user-supplied function objgrd, or an Infinity or NaN was detected in values returned from them. Recovery attempts failed.

$\mathbf{ifail}=26$

User-provided gradient is likely to be incorrect.

This error indicates that the user-supplied gradient vector fdx has entries that do not match with a finite-differences approximation of it.

$\mathbf{ifail}=50$

Problem was solved to an acceptable level; full accuracy was not achieved.

This indicates that the algorithm detected a sequence of very small reductions in the objective function value and is unable to reach a point satisfying the requested optimality tolerance. This may happen if the desired tolerances are too small for the current problem, or if the objective function is badly scaled.

$\mathbf{ifail}=54$

The problem seems to be unbounded and the algorithm was stopped.

This indicates that the solver found a direction where the objective function decreases arbitrarily. In the case of maximizing, the direction found increases arbitrarily the objective value. Cases where this happens are when a linear objective is provided with no constraints, or when the constraints defined do not bound the search direction.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

9.1 Description of the Printed Output

-------------------------------------------------------------------------------
 E04KF, First-order method for bound-constrained problems
-------------------------------------------------------------------------------

Begin of Options
    Print File                    =                   6     * d
    Print Level                   =                   2     * U
    Print Options                 =                 Yes     * d
    Print Solution                =                 All     * U
    Monitoring File               =                   9     * U
    Monitoring Level              =                   3     * U
    Foas Monitor Frequency        =                   0     * d
    Foas Print Frequency          =                   5     * U
End of Options

 Problem Statistics
   No of variables                  8 (+1 disabled, +2 fixed)
     free (unconstrained)           3
     bounded                        2
   Objective function       Nonlinear

 Derivative checker
     idx test        fdx     approx  rel error
       3 Fail   3.56E+02   3.57E+02   2.80E-03
       4  Ok    1.80E+02   1.80E+02   6.05E-09
       5  Ok    0.00E+00   0.00E+00   0.00E+00

 Derivative checker
     idx test        fdx     approx  rel error
       3 Fail   3.56E+02   3.57E+02   2.80E-03
       4  Ok    1.80E+02   1.80E+02   6.05E-09
       5  Ok    0.00E+00   0.00E+00   0.00E+00
       7 Skip         FD         --         --
       2 Skip    BLX=BUX         --         --
       6 Skip    BLX=BUX         --         --
       1 Skip   disabled         --         --

-------------------------------------------------------------------------------
  iters |  objective |  optim  |   dir
-------------------------------------------------------------------------------
      20  7.71339E-01  1.22E-01  1.70E+00
      25  7.06709E-01  1.75E+00  1.54E+00
      30  7.06709E-01  1.75E+00  1.54E+00
      35  6.82989E-01  1.35E+00  1.35E+00
      30  6.55834E-01  3.26E+00  1.67E+00

-------------------------------------------------------------------------------
  iters |  objective |  optim  |   dir   | progrss | it|   step  |    nf|    ng
-------------------------------------------------------------------------------
       0  1.10354E+02  0.00E+00  6.81E+01  1.00E+00       Start        1      1
       1  3.29016E+01  1.45E+01  1.45E+01  5.36E+00 NPG  1.39E-02      8      2
       2  3.29016E+01  1.45E+01  1.45E+01  5.36E+00     Switch CG      8      2
       3  1.84090E+01  2.48E+01  2.48E+01  2.85E+00  CG  2.42E-02     11      4
       4  1.84090E+01  2.48E+01  2.48E+01  2.85E+00      Restart      11      4
       5  9.48087E+00  1.25E+01  1.25E+01  1.45E+00  CG  1.49E-02     13      5
       6  4.20527E+00  8.28E+00  8.22E-01  2.51E+00  CG  3.61E-02     15      6
       7  7.20453E-01  3.08E+00  1.62E+00  9.70E+00 LCG  7.21E-01     17      7

-----  Iteration details (CG)  ---------
Size of gradient                2.64E+01
Size of subspace gradient       2.64E+01
Eigenvalues R range   6.80E-01  6.80E-01
Orthogonal property                 lost
Action                     Switch to LCG
----------------------------------------
-----  LCG solver details  -------------
Search space has            2 element(s)
Memory vectors                   2 (  2)
----------------------------------------

-------------------------------------------------------------------------------
Status: converged, an optimal solution was found
-------------------------------------------------------------------------------
Value of the objective             3.55353E-14
Norm of inactive gradient          2.53812E-07
Norm of projected direction        1.68481E-07
Iterations                                  32
Function evaluations                        80
FD func. evaluations                         5
Gradient evaluations                        48
  NPG function calls                         0
  NPG gradient calls                         0
  CG function calls                         11
  CG gradient calls                          9
  LCG function calls                        69
  LCG gradient calls                        39
-------------------------------------------------------------------------------

Timing
  Total time spent                       12.54 sec
  Total time in obj function              3.01 sec ( 24.0%)
  Total time in obj gradient              5.28 sec ( 42.1%)

 Primal variables:
   idx   Lower bound       Value       Upper bound
     1     Disabled         NaN          Disabled
     2   5.00000E+00    5.00000E+00    5.00000E+00
     3  -1.00000E+00    8.00000E-01    8.00000E-01
     4  -2.00000E+00    6.40000E-01    2.00000E+00
     5   2.00000E+00    2.00000E+00    9.00000E+00
     6  -1.00000E+00   -1.00000E+00   -1.00000E+00
     7   0.00000E+00    0.00000E+00    1.00000E+00
 
 Box bounds dual variables:
   idx   Lower bound       Value       Upper bound       Value
     1     Disabled         NaN          Disabled         NaN
     2   5.00000E+00    0.00000E+00    5.00000E+00    0.00000E+00
     3  -1.00000E+00    0.00000E+00    8.00000E-01    4.00000E-01
     4  -2.00000E+00    0.00000E+00    2.00000E+00    0.00000E+00
     5   2.00000E+00    0.00000E+00    9.00000E+00    0.00000E+00
     6  -1.00000E+00    0.00000E+00   -1.00000E+00    0.00000E+00
     7   0.00000E+00    0.00000E+00    1.00000E+00    0.00000E+00

10 Example

10.1 Program Text

10.2 Program Results

11 Algorithmic Details

11.1 Active-Set Method and Algorithm Outline

11.2 Constrained Subproblem (NPG)

11.3 Unconstrained Subproblem (CG)

11.4 Stopping Criteria

11.5 A Note About Lagrangian Multipliers

12 Optional Parameters

• Defaults
• FOAS Estimate Derivatives
• FOAS Finite Diff Interval
• FOAS Iteration Limit
• FOAS Memory
• FOAS Monitor Frequency
• FOAS Print Frequency
• FOAS Progress Tolerance
• FOAS Rel Stop Tolerance
• FOAS Restart Factor
• FOAS Slow Tolerance
• FOAS Stop Tolerance
• FOAS Tolerance Norm
• Infinite Bound Size
• Monitoring File
• Monitoring Level
• Print File
• Print Level
• Print Options
• Print Solution
• Stats Time
• Task
• Time Limit
• Verify Derivatives

12.1 Description of the Optional Parameters

• the keywords;
• a parameter value, where the letters $a$, $i$ 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 x02ajf).