Options Class for e04us

Syntax

C#
public class e04usOptions
Visual Basic
Public Class e04usOptions
Visual C++
public ref class e04usOptions
F#
type e04usOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • 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​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj), and εr denotes the relative precision of the objective function Function Precision.
Keywords and character values are case and white space insensitive.
Further details of other quantities not explicitly defined in this section may be found by consulting the document for e04uf.
Central Difference Interval
If the algorithm switches to central differences because the forward-difference approximation is not sufficiently accurate, the value of r is used as the difference interval for every element of x. The switch to central differences is indicated by C at the end of each line of intermediate printout produced by the major iterations (see [Description of the Printed Output]). The use of finite differences is discussed further under the optional parameter Difference Interval.
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Cold Start
Warm Start
This option controls the specification of the initial working set in both the procedure for finding a feasible point for the linear constraints and bounds, and in the first QP subproblem thereafter. With a Cold Start, the first working set is chosen by e04us based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within Crash Tolerance).
With a Warm Start, you must set the istate array and define clamda and r as discussed in [Parameters]. istate values associated with bounds and linear constraints determine the initial working set of the procedure to find a feasible point with respect to the bounds and linear constraints. istate values associated with nonlinear constraints determine the initial working set of the first QP subproblem after such a feasible point has been found. e04us will override your specification of istate if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of istate which are set to -2, -1​ or ​4 will be reset to zero, as will any elements which are set to 3 when the corresponding elements of bl and bu are not equal. A Warm Start will be advantageous if a good estimate of the initial working set is available – for example, when e04us is called repeatedly to solve related problems.
Crash Tolerance
This value is used in conjunction with the optional parameter Cold Start (the default value) when e04us selects an initial working set. If 0r1, the initial working set will include (if possible) bounds or general inequality constraints that lie within r of their bounds. In particular, a constraint of the form ajTxl will be included in the initial working set if ajTx-lr1+l. If r<0 or r>1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Derivative Level
This parameter indicates which derivatives are provided in user-supplied delegates objfun and confun. The possible choices for i are the following.
iMeaning
3All elements of the objective Jacobian and the constraint Jacobian are provided by you.
2All elements of the constraint Jacobian are provided, but some elements of the objective Jacobian are not specified by you.
1All elements of the objective Jacobian are provided, but some elements of the constraint Jacobian are not specified by you.
0Some elements of both the objective Jacobian and the constraint Jacobian are not specified by you.
The value i=3 should be used whenever possible, since e04us is more reliable (and will usually be more efficient) when all derivatives are exact.
If i=0​ or ​2, e04us will approximate unspecified elements of the objective Jacobian, using finite differences. The computation of finite difference approximations usually increases the total run-time, since a call to objfun is required for each unspecified element. Furthermore, less accuracy can be attained in the solution (see Chapter 8 of Gill et al. (1981), for a discussion of limiting accuracy).
If i=0​ or ​1, e04us will approximate unspecified elements of the constraint Jacobian. One call to confun is needed for each variable for which partial derivatives are not available. For example, if the constraint Jacobian has the form
*****??***?*****
where ‘*’ indicates an element provided by you and ‘?’ indicates an unspecified element, e04us will call confun twice: once to estimate the missing element in column 2, and again to estimate the two missing elements in column 3. (Since columns 1 and 4 are known, they require no calls to confun.)
At times, central differences are used rather than forward differences, in which case twice as many calls to objfun and confun are needed. (The switch to central differences is not under your control.)
If i<0 or i>3, the default value is used.
Difference Interval
This option defines an interval used to estimate derivatives by finite differences in the following circumstances:
(a) For verifying the objective and/or constraint gradients (see the description of the optional parameter Verify).
(b) For estimating unspecified elements of the objective and/or constraint Jacobian matrix.
In general, a derivative with respect to the jth variable is approximated using the interval δj, where δj=r1+x^j, with x^ the first point feasible with respect to the bounds and linear constraints. If the functions are well scaled, the resulting derivative approximation should be accurate to Or. See Gill et al. (1981) for a discussion of the accuracy in finite difference approximations.
If a difference interval is not specified, a finite difference interval will be computed automatically for each variable by a procedure that requires up to six calls of confun and objfun for each element. This option is recommended if the function is badly scaled or you wish to have e04us determine constant elements in the objective and constraint gradients (see the descriptions of confun and objfun in [Parameters]).
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Feasibility Tolerance
The scalar r defines the maximum acceptable absolute violations in linear and nonlinear constraints at a ‘feasible’ point; i.e., a constraint is considered satisfied if its violation does not exceed r. If r<ε or r1, the default value is used. Using this keyword sets both optional parameters Linear Feasibility Tolerance and Nonlinear Feasibility Tolerance to r, if εr<1. (Additional details are given under the descriptions of these optional parameters.)
Function Precision
This parameter defines εr, which is intended to be a measure of the accuracy with which the problem functions Fx and cx can be computed. If r<ε or r1, the default value is used.
The value of εr should reflect the relative precision of 1+Fx; i.e., εr acts as a relative precision when F is large and as an absolute precision when F is small. For example, if Fx is typically of order 1000 and the first six significant digits are known to be correct, an appropriate value for εr would be 10-6. In contrast, if Fx is typically of order 10-4 and the first six significant digits are known to be correct, an appropriate value for εr would be 10-10. The choice of εr can be quite complicated for badly scaled problems; see Chapter 8 of Gill et al. (1981) for a discussion of scaling techniques. The default value is appropriate for most simple functions that are computed with full accuracy. However, when the accuracy of the computed function values is known to be significantly worse than full precision, the value of εr should be large enough so that e04us will not attempt to distinguish between function values that differ by less than the error inherent in the calculation.
Hessian
This option controls the contents of the upper triangular matrix R (see [Parameters]). e04us works exclusively with the transformed and reordered Hessian HQ, and hence extra computation is required to form the Hessian itself. If Hessian=NO, r contains the Cholesky factor of the transformed and reordered Hessian. If Hessian=YES, the Cholesky factor of the approximate Hessian itself is formed and stored in r. You should select Hessian=YES if a Warm Start will be used for the next call to e04us.
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as + (and similarly any lower bound less than or equal to -bigbnd will be regarded as -). If r<0, the default value is used.
Infinite Step Size
If r>0, r specifies the magnitude of the change in variables that is treated as a step to an unbounded solution. If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r0, the default value is used.
JTJ Initial Hessian
Unit Initial Hessian
This option controls the initial value of the upper triangular matrix R. If J denotes the objective Jacobian matrix fx, then JTJ is often a good approximation to the objective Hessian matrix 2Fx (see also optional parameter Reset Frequency).
Line Search Tolerance
The value r (0r<1) controls the accuracy with which the step α taken during each iteration approximates a minimum of the merit function along the search direction (the smaller the value of r, the more accurate the linesearch). The default value r=0.9 requests an inaccurate search and is appropriate for most problems, particularly those with any nonlinear constraints.
If there are no nonlinear constraints, a more accurate search may be appropriate when it is desirable to reduce the number of major iterations – for example, if the objective function is cheap to evaluate, or if a substantial number of derivatives are unspecified. If r<0 or r1, the default value is used.
Linear Feasibility Tolerance
Nonlinear Feasibility Tolerance
The default value of r2 is ε0.33 if Derivative Level=0 or 1, and ε otherwise.
The scalars r1 and r2 define the maximum acceptable absolute violations in linear and nonlinear constraints at a ‘feasible’ point; i.e., a linear constraint is considered satisfied if its violation does not exceed r1, and similarly for a nonlinear constraint and r2. If rm<ε or rm1, the default value is used, for m=1,2.
On entry to e04us, an iterative procedure is executed in order to find a point that satisfies the linear constraints and bounds on the variables to within the tolerance r1. All subsequent iterates will satisfy the linear constraints to within the same tolerance (unless r1 is comparable to the finite difference interval).
For nonlinear constraints, the feasibility tolerance r2 defines the largest constraint violation that is acceptable at an optimal point. Since nonlinear constraints are generally not satisfied until the final iterate, the value of optional parameter Nonlinear Feasibility Tolerance acts as a partial termination criterion for the iterative sequence generated by e04us (see also optional parameter Optimality Tolerance).
These tolerances should reflect the precision of the corresponding constraints. For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about 6 decimal digits, it would be appropriate to specify r1 as 10-6.
List
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
Major Iteration Limit
Iteration Limit
Iters
Itns
The value of i specifies the maximum number of major iterations allowed before termination. Setting i=0 and Major Print Level>0 means that the workspace needed will be computed and printed, but no iterations will be performed. If i<0, the default value is used.
Major Print Level
Print Level
The value of i controls the amount of printout produced by the major iterations of e04us, as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each major iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each major iteration). (See also the description of the optional parameter Minor Print Level.)
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
iOutput
00No output.
01The final solution only.
05One line of summary output (<80 characters; see [Description of the Printed Output]) for each major iteration (no printout of the final solution).
10The final solution and one line of summary output for each major iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
iOutput
<5No output.
5One long line of output (>80 characters; see [Description of Monitoring Information]) for each major iteration (no printout of the final solution).
20At each major iteration, the objective function, the Euclidean norm of the nonlinear constraint violations, the values of the nonlinear constraints (the vector c), the values of the linear constraints (the vector ALx), and the current values of the variables (the vector x).
30At each major iteration, the diagonal elements of the matrix T associated with the TQ factorization (see (5) in e04uf) of the QP working set, and the diagonal elements of R, the triangular factor of the transformed and reordered Hessian (see (6) in e04uf).
If Major Print Level5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output for each major iteration is suppressed.
Minor Iteration Limit
The value of i specifies the maximum number of iterations for finding a feasible point with respect to the bounds and linear constraints (if any). The value of i also specifies the maximum number of minor iterations for the optimality phase of each QP subproblem. If i0, the default value is used.
Minor Print Level
The value of i controls the amount of printout produced by the minor iterations of e04us (i.e., the iterations of the quadratic programming algorithm), as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each minor iteration and the final QP solution) and [Description of Monitoring Information] (monitoring information at each minor iteration). (See also the description of the optional parameter Major Print Level.)
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
iOutput
00No output.
01The final QP solution only.
05One line of summary output (<80 characters; see [Description of the Printed Output]) for each minor iteration (no printout of the final QP solution).
10The final QP solution and one line of summary output for each minor iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
iOutput
<5No output.
5One long line of output (>80 characters; see [Description of Monitoring Information]) for each minor iteration (no printout of the final QP solution).
20At each minor iteration, the current estimates of the QP multipliers, the current estimate of the QP search direction, the QP constraint values, and the status of each QP constraint.
30At each minor iteration, the diagonal elements of the matrix T associated with the TQ factorization (see (5) in e04uf) of the QP working set, and the diagonal elements of the Cholesky factor R of the transformed Hessian (see (6) in e04uf).
If Minor Print Level5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output for each minor iteration is suppressed.
Monitoring File
If i0 and Major Print Level5 or i0 and Minor Print Level5, monitoring information produced by e04us at every iteration is sent to a file with logical unit number i. If i<0 and/or Major Print Level<5 and Minor Print Level<5, no monitoring information is produced.
Optimality Tolerance
The parameter r (εRr<1) specifies the accuracy to which you wish the final iterate to approximate a solution of the problem. Broadly speaking, r indicates the number of correct figures desired in the objective function at the solution. For example, if r is 10-6 and e04us terminates successfully, the final value of F should have approximately six correct figures. If r<εR or r1, the default value is used.
e04us will terminate successfully if the iterative sequence of x values is judged to have converged and the final point satisfies the first-order Kuhn–Tucker conditions (see [] in e04uf). The sequence of iterates is considered to have converged at x if
αpr1+x, (2)
where p is the search direction and α the step length. An iterate is considered to satisfy the first-order conditions for a minimum if
ZTgFRr1+max1+Fx,gFR (3)
and
resjftol  for all  j, (4)
where ZTgFR is the projected gradient, gFR is the gradient of Fx with respect to the free variables, resj is the violation of the jth active nonlinear constraint, and ftol is the Nonlinear Feasibility Tolerance.
Reset Frequency
If i>0, this parameter allows you to reset the approximate Hessian matrix to JTJ every i iterations, where J is the objective Jacobian matrix fx (see also the description of the optional parameter JTJ Initial Hessian).
At any point where there are no nonlinear constraints active and the values of f are small in magnitude compared to the norm of J, JTJ will be a good approximation to the objective Hessian 2Fx. Under these circumstances, frequent resetting can significantly improve the convergence rate of e04us.
Resetting is suppressed at any iteration during which there are nonlinear constraints active.
If i0, the default value is used.
Start Objective Check At Variable
Stop Objective Check At Variable
Start Constraint Check At Variable
Stop Constraint Check At Variable
These keywords take effect only if Verify Level>0. They may be used to control the verification of Jacobian elements computed by user-supplied delegates objfun and confun. For example, if the first 30 columns of the objective Jacobian appeared to be correct in an earlier run, so that only column 31 remains questionable, it is reasonable to specify Start Objective Check At Variable=31. If the first 30 variables appear linearly in the subfunctions, so that the corresponding Jacobian elements are constant, the above choice would also be appropriate.
If i2m-10 or i2m-1>minn,i2m, the default value is used, for m=1,2. If i2m0 or i2m>n, the default value is used, for m=1,2.
Step Limit
If r>0,r specifies the maximum change in variables at the first step of the linesearch. In some cases, such as Fx=aebx or Fx=axb, even a moderate change in the elements of x can lead to floating-point overflow. The parameter r is therefore used to encourage evaluation of the problem functions at meaningful points. Given any major iterate x, the first point x~ at which F and c are evaluated during the linesearch is restricted so that
x~-x2r1+x2.
The linesearch may go on and evaluate F and c at points further from x if this will result in a lower value of the merit function (indicated by L at the end of each line of output produced by the major iterations; see [Description of the Printed Output]). If L is printed for most of the iterations, r should be set to a larger value.
Wherever possible, upper and lower bounds on x should be used to prevent evaluation of nonlinear functions at wild values. The default value Step Limit=2.0 should not affect progress on well-behaved functions, but values such as 0.1​ or ​0.01 may be helpful when rapidly varying functions are present. If a small value of Step Limit is selected, a good starting point may be required. An important application is to the class of nonlinear least squares problems. If r0, the default value is used.
Verify Level
Verify
Verify Constraint Gradients
Verify Gradients
Verify Objective Gradients
These keywords refer to finite difference checks on the gradient elements computed by objfun and confun. (Unspecified gradient elements are not checked.) The possible choices for i are the following:
iMeaning
-1No checks are performed.
-0Only a ‘cheap’ test will be performed, requiring one call to objfun.
-1Individual gradient elements will also be checked using a reliable (but more expensive) test.
For example, the nonlinear objective gradient (if any) will be verified if either Verify Objective Gradients or Verify Level=1 is specified. Similarly, the objective and the constraint gradients will be verified if Verify=YES or Verify Level=3 or Verify is specified.
If i=-1, no checking will be performed.
If 0i3, gradients will be verified at the first point that satisfies the linear constraints and bounds. If i=0, only a ‘cheap’ test will be performed, requiring one call to objfun and (if appropriate) one call to confun. If 1i3, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the Start Objective Check At Variable and Stop Objective Check At Variable keywords. A result of the form OK or BAD? is printed by e04us to indicate whether or not each element appears to be correct.
If 10i13, the action is the same as for i-10, except that it will take place at the user-specified initial value of x.
If i<-1 or 4i9 or i>13, the default value is used.
We suggest that Verify Level=3 be used whenever a new function method is being developed.

Inheritance Hierarchy

System..::..Object
  NagLibrary..::..E04..::..e04usOptions

See Also