« Previous « Start » Next »

4  TOMLAB /KNITRO Solver Reference

A detailed description of the TOMLAB /KNITRO  solver interface is given below. Also see the M-file help for knitroTL.m .

4.1  knitroTL

Purpose
Solve nonlinear constrained optimization problems.

TOMLAB /KNITRO solves problems of the form where x,x_L,x_U Rⁿ,  A R^{m₁ × n},  b_L,b_U R^m₁ and c(x), c_L, c_U R^m₂.
Calling Syntax
Prob = *Assign( ... );
Result = tomRun('knitro',Prob,...)
Description of Inputs

Prob	Problem description structure. The following fields are used:
Prob	Problem description structure. The following fields are used:, continued
x_0	Starting point.
x_L	Lower bounds on variables.
x_U	Upper bounds on variables.
A	Linear constraints matrix.
b_L	Lower bounds for linear constraints.
b_U	Upper bounds for linear constraints.
c_L	Lower bounds for nonlinear constraints.
c_U	Upper bounds for nonlinear constraints.
LargeScale	If 1, indicates that the problem should be treated as sparse. This makes knitroTL send a sparse version of Prob.A to the solver. To avoid poor performance, sparse ConsPattern and d2LPattern should be given. (Default 1).
ConsPattern	The sparse m2 × n 0-1 pattern indicating nonzero elements in the nonlinear constraint Jacobian matrix.
d2LPattern	The sparse n× n 0-1 pattern indicating nonzero elements in the Hessian of the Lagrangian function f(x)+λ c(x).
f_Low	A lower bound on the objective function value. KNITRO will stop if it finds an x for which f(x)<=fLow.
PriLevOpt	Print level in solver. TOMLAB /KNITRO supports solver progress information being printed to the MATLAB command window as well as to a file.
	For output only to the command window: set PriLevOpt to a positive value (1-6) and set:
	Prob.KNITRO.PrintFile = ”;
	If PrintFile is set to a valid filename, the same information will be written to the file (if PriLevOpt is nonzero).
	or printing only to the PrintFile, set a name (or knitro.txt will be used) and a negative PriLevOpt value. For example:
	Prob.KNITRO.PrintFile = 'myprob.txt';
	Prob.PriLevOpt = -2;
	To run TOMLAB /KNITRO silently, set PriLevOpt=0;
0:	Printing of all output is suppressed (default).
1:	Only summary information is printed.
2:	Information every 10 major iterations is printed where a major iteration is defined by a new solution estimate.
3:	Information at each major iteration is printed.
4:	Information is printed at each major and minor iteration where a minor iteration is defined by a trial iterate.
5:	In addition, the values of the solution vector x are printed.
6:	In addition, the values of the constraints c and Lagrange multipliers lambda are printed.
KNITRO	Structure with special fields for KNITRO parameters. Fields used are:
PrintFile	Name of file to print solver progress and status information to. Please see PriLevOpt parameter described above.
options	Structure with KNITRO options. Any element not given is replaced by a default value, in some cases fetched from standard Tomlab parameters.
ALG	Indicates which optimization algorithm to use to solve the problem. Default 0.
	0: automatic algorithm selection.
	1: Interior/Direct algorithm.
	2: Interior/CG algorithm.
	3: Active algorithm, SLQP.
BAR_INITMU	Specifies the initial barrier parameter value for the interior-point algorithms. This option has no effect on the Active Set algorithm. Default 1.0e−1.
BAR_INITPT	Indicates whether an initial point strategy is used with barrier algorithms. If the “honorbnds” or “feasible” options are enabled, then a request to shift may be ignored. This option has no effect on the Active Set algorithm. Default 0.
0 (auto):	Let Knitro automatically choose the strategy.
1 (yes):	Shift the initial point to improve barrier algorithm performance.
2 (no):	Do no alter the initial point supplied by the user.
BAR_MAXBACKTRACK	Indicates the maximum allowable number of backtracks during the linesearch of the Interior/Direct algorithm before reverting to a CG step. Increasing this value will make the Interior/Direct algorithm less likely to take CG steps. If the Interior/Direct algorithm is taking a large number of CG steps (as indicated by a positive value for “CG its” in the output), this may improve performance. This option has no effect on the Active Set algorithm. Default value: 3.
BAR_MAXREFACTOR	Indicates the maximum number of refactorizations of the KKT system per iteration of the Interior/Direct algorithm before reverting to a CG step. These refactorizations are performed if negative curvature is detected in the model.
	Rather than reverting to a CG step, the Hessian matrix is modified in an attempt to make the subproblem convex and then the KKT system is refactorized. Increasing this value will make the Interior/Direct algorithm less likely to take CG steps. If the Interior/Direct algorithm is taking a large number of CG steps (as indicated by a positive value for “CG its” in the output), this may improve performance. This option has no effect on the Active Set algorithm. Default value: 0.
BAR_MURULE	Indicates which strategy to use for modifying the barrier parameter in the interior point code. Some strategies are only available for the Interior/Direct algorithm. (see Section 7). Default 0.
	0: automatically choose the rule for updating the barrier parameter.
	1: monotonically decrease the barrier parameter.
	2: an adaptive rule based on the complementarity gap to determine the value of the barrier parameter at every iteration.
	3: uses a probing (affine-scaling) step to dynamically determine the barrier parameter value at each iteration.
	4: uses a Mehrotra predictor-corrector type rule to determine the barrier parameter with safeguards on the corrector step.
	5: uses a Mehrotra predictor-corrector type rule to determine the barrier parameter without safeguards on the corrector step.
	6: minimizes a quality function at each iteration to determine the barrier parameter.
	NOTE: Only strategies 0-2 are available for the Interior/CG algorithm. All strategies are available for the Interior/Direct algorithm. Strategies 4 and 5 are typically recommended for linear programs or convex quadratic programs. Many problems benefit from a non-default setting of this option and it is recommended to experiment with all settings. In particular we recommend trying strategy 6 when using the Interior/Direct algorithm. This parameter is not applicable to the Active algorithm.
BLASOPTION	Specifies the BLAS/LAPACK function library to use for basic vector and matrix computations. Default 0.
	0: Use KNITRO builtin functions.
	1: Use Intel MKL functions.
	NOTE: BLAS and LAPACK functions from the Intel Math Kernel Library (MKL) 8.1 are provided with the Knitro distribution. The MKL is available for Windows, Linux (32-bit and 64-bit), and Mac OS X (32-bit x86); it is not available for Solaris or Mac OS X PowerPC.
	BLAS (Basic Linear Algebra Subroutines) and LAPACK (Linear Algebra PACKage) functions are used throughout Knitro for fundamental vector and matrix calculations. The CPU time spent in these operations can be measured by setting option “debug=1” and examining the output file kdbg summ*.txt. Some optimization problems are observed to spend less than 1CPU time in BLAS/LAPACK operations, while others spend more than 50the different function implementations can return slightly different answers due to roundoff errors in double precision arithmetic. Thus, changing the value of “blasoption” sometimes alters the iterates generated by Knitro, or even the final solution point.
	The Knitro built-in functions are based on standard netlib routines (www.netlib.org). The Intel MKL functions are written especially for x86 processor architectures. On a machine running an Intel processor (e.g., Pentium 4), testing indicates that the MKL functions can reduce the CPU time in BLAS/LAPACK operations by 20-30%.
	If your machine uses security enhanced Linux (SELinux), you may see errors when loading the Intel MKL.
DEBUG	Controls the level of debugging output. Debugging output can slow execution of Knitro and should not be used in a production setting. All debugging output is suppressed if option “PriLevOpt” equals zero. Default value: 0.
	0: No debugging output.
	1: Print algorithm information to kdbg*.log output files.
	2: Print program execution information.
DELTA	Specifies the initial trust region radius scaling factor used to determine the initial trust region size. Default value: 1.0e0.
FEASIBLE	Indicates whether or not to use the feasible version of TOMLAB /KNITRO.
	0: Iterates may be infeasible.
	1: Given an initial point which sufficiently satisfies all inequality constraints as defined by, cl + tol ≤ c(x) ≤ cu − tol     (2) (for cl cu), the feasible version of TOMLAB /KNITRO ensures that all subsequent solution estimates strictly satisfy the inequality constraints. However, the iterates may not be feasible with respect to the equality constraints. The tolerance tol>0 in 2 for determining when the feasible mode is active is determined by the double precision parameter FEASMODETOL described below. This tolerance (i.e. FEASMODETOL) must be strictly positive. That is, in order to enter feasible mode, the point given to TOMLAB /KNITRO must be strictly feasible with respect to the inequality constraints.
	If the initial point is infeasible (or not sufficiently feasible according to 2) with respect to the inequality constraints, then TOMLAB /KNITRO will run the infeasible version until a point is obtained which sufficiently satisfies all the inequality constraints. At this point it will switch to feasible mode.
	NOTE: This option can be used only when ALG=2. See Section 8.3 for more details.
FEASMODETOL	Specifies the tolerance in 2 by which the iterate must be feasible with respect to the inequality constraints before the feasible mode becomes active. This option is only relevant when FEASIBLE=1. Default 1e−4.
FEASTOL	Specifies the final relative stopping tolerance for the feasibility error. Smaller values of FEASTOL result in a higher degree of accuracy in the solution with respect to feasibility. Default 1e−6.
FEASTOL_ABS	Specifies the final absolute stopping tolerance for the feasibility error. Smaller values of FEASTOLABS result in a higher degree of accuracy in the solution with respect to feasibility. Default 0.
	NOTE: For more information on the stopping test used in TOMLAB /KNITRO see Section 5.
GRADOPT	Specifies how to calculate first derivatives. In addition to the available numeric differentiation methods available in TOMLAB, KNITRO can internally estimate forward or centered numerical derivatives.
	The following settings are available:
1:	KNITRO expects the user to provide exact first derivatives (default).
	However, note that this can imply numerical derivatives calculated by any of the available methods in TOMLAB. See the TOMLAB User's Guide for more information on numerical derivatives.
2:	KNITRO will estimate forward finite differential derivatives.
3:	KNITRO will estimate centered finite differential derivatives.
4:	KNITRO expects exact first derivatives and performs gradient checking by internally calculating forward finite differences.
5:	KNITRO expects exact first derivatives and performs gradient checking by internally calculating centered finite differences.
	NOTE: It is highly recommended to provide exact gradients if at all possible as this greatly impacts the performance of the code. For more information on these options see Section 8.1.
HESSOPT	Specifies how to calculate the Hessian (Hessian-vector) of the Lagrangian function.
1:	KNITRO expects the user to provide the exact Hessian (default).
2:	KNITRO will compute a (dense) quasi-Newton BFGS Hessian approximation.
3:	KNITRO will compute a (dense) quasi-Newton SR1 Hessian approximation.
4:	KNITRO will compute Hessian-vector products using finite differences.
5:	KNITRO expects the user to provide a routine to compute the Hessian-vector products. If this option is selected, the calculation is handled by the TOMLAB function nlp_d2Lv.m .
6:	KNITRO will compute a limited-memory quasi-Newton BFGS.
	NOTE: If exact Hessians (or exact Hessian-vector products) cannot be provided by the user but exact gradients are provided and are not too expensive to compute, option 4 above is typically recommended. The finite-difference Hessian-vector option is comparable in terms of robustness to the exact Hessian option (assuming exact gradients are provided) and typically not too much slower in terms of time if gradient evaluations are not the dominant cost.
	However, if exact gradients cannot be provided (i.e. finite-differences are used for the first derivatives), or gradient evaluations are expensive, it is recommended to use one of the quasi-Newton options, in the event that the exact Hessian is not available. Options 2 and 3 are only recommended for small problems (n < 1000) since they require working with a dense Hessian approximation. Option 6 should be used in the large-scale case.
	NOTE: Options HESSOPT=4 and HESSOPT=5 are not available when ALG=1. See Section 8.2 for more detail on second derivative options.
HONORBNDS	Indicates whether or not to enforce satisfaction of the simple bounds 1 throughout the optimization (see Section 8.4). Default 2.
0:	TOMLAB /KNITRO does not enforce that the bounds on the variables are satisfied at intermediate iterates.
1:	TOMLAB /KNITRO enforces that the initial point and all subsequent solution estimates satisfy the bounds on the variables 1.
2:	TOMLAB /KNITRO enforces that the initial point satisfies the bounds on the variables.
LMSIZE	Specifies the number of limited memory pairs stored when approximating the Hessian using the limited-memory quasi-Newton BFGS option. The value must be between 1 and 100 and is only used when HESSOPT=6. Larger values may give a more accurate, but more expensive, Hessian approximation. Smaller values may give a less accurate, but faster, Hessian approximation. When using the limited memory BFGS approach it is recommended to experiment with different values of this parameter. See Section 8 for more details. Default value: 10
MAXCGIT	Determines the maximum allowable number of inner conjugate gradient (CG) iterations per Knitro minor iteration. Default 0.
0:	TOMLAB /KNITRO automatically determines an upper bound on the number of allowable CG iterations based on the problem size.
n:	At most n CG iterations may be performed during one Knitro minor iteration, where n>0.
MAXCROSSIT	Specifies the maximum number of crossover iterations before termination. When running one of the interior-point algorithms in KNITRO, if this value is positive, it will switch to the Active algorithm near the solution, and perform at most MAXCROSSIT iterations of the Active algorithm to try to get a more exact solution. If this value is 0 or negative, no Active crossover iterations will be performed.
	If crossover is unable to improve the approximate interior-point solution, then it will restore the interior-point solution. In some cases (especially on large-scale problems or difficult degenerate problems) the cost of the crossover procedure may be significant – for this reason, the crossover procedure is disabled by default. However, in many cases the additional cost of performing crossover is not significant and you may wish to enable this feature to obtain a more accurate solution. See Section 8 for more details on the crossover procedure. Default 0.
MAXIT	Specifies the maximum number of major iterations before termination. Default 10000.
MAXTIMECPU	Specifies, in seconds, the maximum allowable CPU time before termination. Default 1e8.
	NOTE: For more information on the stopping test used in TOMLAB /KNITRO see Section 5.
MAXTIMEREAL	Specifies, in seconds, the maximum allowable real time before termination. Default 1e8.
	NOTE: For more information on the stopping test used in TOMLAB /KNITRO see Section 5.
MSENABLE	Indicates whether KNITRO will solve from multiple start points to find a better local minimum. See Section 8 for details. Default 0.
0:	TOMLAB /KNITRO solves from a single initial point.
1:	TOMLAB /KNITRO solves using multiple start points.
MSMAXBNDRANGE	Specifies the maximum range that each variable can take when determining new start points. If a variable has upper and lower bounds and the difference between them is less than MSMAXBNDRANGE, then new start point values for the variable can be any number between its upper and lower bounds. If the variable is unbounded in one or both directions, or the difference between bounds is greater than MSMAXBNDRANGE, then new start point values are restricted by the option. If xi is such a variable, then all initial values satisfy:
	xi0 − mxmaxbndrange/2 <= xi <= xi0 + msmaxbndrange/2
	where xi0 is is the initial value of xi provided by the user. This option has no effect unless msenable=1. Default value: 1000.0.
MSMAXSOLVES	Specifies how many start points to try in multistart. This option is only valid if MULTISTART=1. Default 1.
0:	TOMLAB /KNITRO solves from a single initial point.
MSMAXTIMECPU	Specifies, in seconds, the maximum allowable CPU time before termination. The limit applies to the operation of Knitro since multi-start began; in contrast, the value of “maxtime cpu” limits how long Knitro iterates from a single start point. Therefore, MSMAXTIMECPU should be greater than MAXTIMECPU. This option has no effect unless MSENABLE=1. Default value: 1.0e8.
MSMAXTIMEREAL	Specifies, in seconds, the maximum allowable real time before termination. The limit applies to the operation of Knitro since multi-start began; in contrast, the value of MAXTIMEREAL limits how long Knitro iterates from a single start point. Therefore, MSMAXTIMEREAL should be greater than MAXTIMEREAL. This option has no effect unless MSENABLE=1. Default value: 1.0e8.
OBJRANGE	Determines the allowable range of values for the objective function for determining unboundedness. If the magnitude of the objective function is greater than OBJRANGE and the iterate is feasible, then the problem is determined to be unbounded. Default 1.0e20.
OPTTOL	specifies the final relative stopping tolerance for the KKT (optimality) error. Smaller values of OPTTOL result in a higher degree of accuracy in the solution with respect to optimality. Default 1.0e−6.
OPTTOL_ABS	Specifies the final absolute stopping tolerance for the KKT (optimality) error. Smaller values of OPTTOLABS result in a higher degree of accuracy in the solution with respect to optimality. Default 0.0e0.
	NOTE: For more information on the stopping test used in TOMLAB /KNITRO see Section 5.
PIVOT	Specifies the initial pivot threshold used in the factorization routine. The value should be in the range [0 0.5] with higher values resulting in more pivoting (more stable factorization). Values less than 0 will be set to 0 and values larger than 0.5 will be set to 0.5. If pivot is non-positive initially no pivoting will be performed. Smaller values may improve the speed of the code but higher values are recommended for more stability (for example, if the problem appears to be very ill-conditioned). Default 1.0e−8.
SCALE	Performs a scaling of the objective and constraint functions based on their values at the initial point. If scaling is performed, all internal computations, including the stopping tests, are based on the scaled values. Default 1.
0:	No scaling is performed.
1:	The objective function and constraints may be scaled.
SOC	Indicates whether or not to use the second order correction (SOC) option. A second order correction may be beneficial for problems with highly nonlinear constraints. Default 1.
0:	No second order correction steps are attempted.
1:	Second order correction steps may be attempted on some iterations.
2:	Second order correction steps are always attempted if the original step is rejected and there are nonlinear constraints.
XTOL	The optimization will terminate when the relative change in the solution estimate is less than XTOL. If using an interior-point algorithm and the barrier parameter is still large, TOMLAB /KNITRO will first try decreasing the barrier parameter before terminating. Default 1.0e−15.

Description of Outputs

Result	Structure with result from optimization. The following fields are set:
Result	Structure with result from optimization. The following fields are set:, continued
	x_k	Optimal point.
	f_k	Function value at optimum.
	g_k	Gradient value at optimu.
	c_k	Nonlinear constraint values at optimum.
	H_k	The Hessian of the Lagrangian function at optimum.
	v_k	Lagrange multipliers.
	x_0	Starting point.
	f_0	Function value at start.
	xState	State of each variable: 0/1/2/3: free / on lower bnd / on upper bnd / fixed.
	bState	State of each linear constraint, values as xState .
	cState	State of each nonlinear constraint, values as xState .
	Iter	Number of iterations.
	FuncEv	Number of function evaluations.
	GradEv	Number of gradient evaluations.
	HessEv	Number of Hessian evaluations.
	ConstrEv	Number of constraint evaluations.
	ConJacEv	Number of constraint Jacobian evaluations.
	ConHessEv	Number of constraint Hessian evaluations.
	ExitFlag	Exit status. The following values are used:
	0:	Optimal solution found or current point cannot be improved.
		See Result.Inform  for more information.
	1:	Maximum number of iterations reached.
	2:	(Possibly) unbounded problem.
	4:	(Possibly) infeasible problem.
	Inform	Status value returned from KNITRO solver.
	0:	Locally optimal solution found.
		TOMLAB /KNITRO found a locally optimal point which satisfies the stopping criterion (see Section 5 for more detail on how this is defined). If the problem is convex (for example, a linear program), then this point corresponds to a globally optimal solution.
	-1:	Iteration limit reached.
		The iteration limit was reached before being able to satisfy the required stopping criteria.
	-2:	Convergence to an infeasible point. Problem may be locally infeasible.
		The algorithm has converged to an infeasible point from which it cannot further decrease the infeasibility measure. This happens when the problem is infeasible, but may also occur on occasion for feasible problems with nonlinear constraints or badly scaled problems. It is recommended to try various initial points. If this occurs for a variety of initial points, it is likely the problem is infeasible.
	-3:	Problem appears to be unbounded.
		The objective function appears to be decreasing without bound, while satisfying the constraints.
	-4:	Current point cannot be improved.
		No more progress can be made. If the current point is feasible it is likely it may be optimal, however the stopping tests cannot be satisfied (perhaps because of degeneracy, ill-conditioning or bad scaling).
	-5:	Current point cannot be improved. Point appears to be optimal, but desired accuracy could not be achieved.
		No more progress can be made, but the stopping tests are close to being satisfied (within a factor of 100) and so the current approximate solution is believed to be optimal.
	-6:	Time limit reached.
		The time limit was reached before being able to satisfy the required stopping criteria.
	-50 to -60:	Termination values in this range imply some input error.
		If OUTLEV>0 or PriLevOpt>0 details of this error will be printed to the screen or the file knitro.out depending on the value of outmode.
	-90:	Callback function error.
		This termination value indicates that an error (i.e., negative return value) occurred in a user provided callback routine.
	-97:	LP solver error.
		This termination value indicates that an unrecoverable error occurred in the LP solver used in the active-set algorithm preventing the optimization from continuing.
	-98:	Evaluation error.
		This termination value indicates that an evaluation error occurred (e.g., divide by 0, taking the square root of a negative number), preventing the optimization from continuing.
	-99:	Not enough memory available to solve problem.
		This termination value indicates that there was not enough memory available to solve the problem.
	Solver	Solver used ('KNITRO').
	SolverAlgorithm	Solver algorithm used.
	Prob	Problem structure used.

« Previous « Start » Next »