Documentation Center |
On this page… |
---|
ktrlink calls Ziena Optimization's KNITRO^{®} libraries in order to perform an optimization. ktrlink can address constrained and unconstrained problems. To use ktrlink, you must purchase a copy of KNITRO libraries from Ziena Optimization, Inc. (http://www.ziena.com/).
Use ktrlink the same as any other Optimization Toolbox™ function.
ktrlink's syntax is similar to fmincon's. The main differences are:
ktrlink has additional options input for KNITRO libraries so you can access its options.
ktrlink has no provision for obtaining a returned Hessian or gradient, since KNITRO software doesn't return them.
Sparse matrix representations differ between KNITRO software and MATLAB^{®}.
Furthermore, many returned flags and messages differ from fmincon's, because they are returned directly from KNITRO libraries.
The system requirements for MATLAB and KNITRO software may differ. Check the system requirements for both products before attempting to use ktrlink. For recent and planned MATLAB platform support, see
http://www.mathworks.com/support/sysreq/roadmap.html
Optimization Toolbox software version 6 works with versions 6, 7, and 8 of KNITRO libraries. Contact Ziena Optimization, Inc. (http://www.ziena.com/) if you have questions regarding other versions of the KNITRO libraries.
Perform the following steps to configure your system to use ktrlink:
Install MATLAB and the KNITRO libraries on your system.
Set the system path to include the KNITRO libraries (see Setting the System Path to Include KNITRO Libraries). Make sure to perform this step before starting MATLAB.
Start MATLAB.
In order to use ktrlink, you need to tell MATLAB where the KNITRO binary file (libknitro.so, libknitro.dylib, knitro.dll, or a similar file) resides. You do this by setting a system-wide environment variable. Enter the following system-level commands. Replace <file_absolute_path> with the full path to your KNITRO libraries:
Linux:
setenv LD_LIBRARY_PATH <file_absolute_path>:$LD_LIBRARY_PATH
Macintosh:
Launch Terminal, available in Applications > Utilities.
Determine the shell:
echo $SHELL
Set the path:
If shell is bash:
export DYLD_LIBRARY_PATH=<file_absolute_path>:$DYLD_LIBRARY_PATH
If shell is csh or tcsh:
setenv DYLD_LIBRARY_PATH=<file_absolute_path>:$DYLD_LIBRARY_PATH
Launch MATLAB by entering matlab in Terminal. (Launching MATLAB by clicking an icon can lose the path to the KNITRO binary file.)
Optional: to set the path permanently:
In bash, add the export line in step 3 to $HOME/.profile.
In csh or tcsh, add the setenv line in step 3 to $HOME/.cshrc.
Windows:
At the Windows desktop, right-click My Computer (Windows XP) or Computer (Vista or Windows 7).
Select Properties.
Click the Advanced tab (Windows XP) or Advanced System Settings (Vista or Windows 7).
Click Environment Variables.
Under System variables, edit the Path variable to add the KNITRO library folder.
Check if the installation was successful by starting MATLAB and running the following command:
[x fval] = ktrlink(@(x)cos(x),1)
If you receive an error message, check your system path, and make sure the KNITRO libraries are on the path. When installed correctly, ktrlink returns a long message, ending with x = 3.1416, fval = -1.
This example uses the same constraint function as the example in Nonlinear Constraints. The constraint function is the intersection of the interior of an ellipse with the region above a parabola:
function [c ceq gradc gradceq]=ellipseparabola(x) % Inside the ellipse bounded by (-3<x<3),(-2<y<2) % Above the line y=x^2-1 c(1) = x(1)^2/9 + x(2)^2/4 - 1;% ellipse c(2) = x(1)^2 - x(2) - 1;% parabola ceq = []; if nargout > 2 gradc = [2*x(1)/9, 2*x(1);... x(2)/2, -1]; gradceq = []; end
The objective function is a tilted sinh:
function [f gradf]=sinhtilt(x) A=[2,1;1,2]; m=[1,1]; f=sinh(x'*A*x/100) + sinh(m*A*x/10); if nargout > 1 gradf=cosh(x'*A*x/100)*(A*x)/50; gradf=gradf+cosh(m*A*x/10)*[3;3]/10; end
Set the options so that ktrlink has iterative display and uses the gradients included in the objective and constraint functions:
ktropts = optimoptions('ktrlink','Display','iter',... 'GradConstr','on','GradObj','on');
Run the optimization starting at [0;0], using the ktropts options:
[x fval flag] = ktrlink(@sinhtilt,[0;0],... [],[],[],[],[],[],@ellipseparabola,ktropts)
KNITRO software returns the following output:
====================================== Trial Ziena License (NOT FOR COMMERCIAL USE) KNITRO 8.1.0 Ziena Optimization ====================================== KNITRO presolve eliminated 0 variables and 0 constraints. algorithm: 1 hessopt: 2 honorbnds: 1 maxit: 10000 outlev: 4 KNITRO changing bar_switchrule from AUTO to 2. KNITRO changing bar_murule from AUTO to 4. KNITRO changing bar_initpt from AUTO to 2. KNITRO changing bar_penaltyrule from AUTO to 2. KNITRO changing bar_penaltycons from AUTO to 1. KNITRO changing linsolver from AUTO to 2. Problem Characteristics ----------------------- Objective goal: Minimize Number of variables: 2 bounded below: 0 bounded above: 0 bounded below and above: 0 fixed: 0 free: 2 Number of constraints: 2 linear equalities: 0 nonlinear equalities: 0 linear inequalities: 0 nonlinear inequalities: 2 range: 0 Number of nonzeros in Jacobian: 4 Number of nonzeros in Hessian: 3 Iter fCount Objective FeasError OptError ||Step|| CGits -------- -------- -------------- ---------- ---------- ---------- ------- 0 1 0.000000e+000 0.000e+000 1 2 -1.701203e-001 0.000e+000 1.969e-001 4.111e-001 0 2 3 -4.135676e-001 2.440e-001 1.356e-001 6.054e-001 0 3 4 -3.631949e-001 2.037e-002 4.434e-002 1.423e-001 0 4 5 -3.608513e-001 3.776e-003 1.680e-002 8.094e-002 0 5 6 -3.604610e-001 1.216e-003 1.494e-003 4.870e-002 0 6 7 -3.601203e-001 2.694e-006 1.630e-004 3.329e-003 0 7 8 -3.601196e-001 0.000e+000 4.840e-007 1.241e-005 0 EXIT: Locally optimal solution found. Final Statistics ---------------- Final objective value = -3.60119566305939e-001 Final feasibility error (abs / rel) = 0.00e+000 / 0.00e+000 Final optimality error (abs / rel) = 4.84e-007 / 4.84e-007 # of iterations = 7 # of CG iterations = 0 # of function evaluations = 8 # of gradient evaluations = 8 Total program time (secs) = 0.097 ( 0.218 CPU time) Time spent in evaluations (secs) = 0.067 =============================================================================== x = -0.5083 -0.7416 fval = -0.3601 flag = 0
Note: Exit flags have different meanings for ktrlink and fmincon. Flag 0 for KNITRO libraries means the first-order optimality condition was satisfied; for fmincon, the corresponding flag is 1. For more information about the output, see the KNITRO documentation at http://www.ziena.com/. |
ktrlink takes up to two options inputs: one in fmincon format, and another in KNITRO format. You can use either or both types of options. If you use both types of options, MATLAB reads only four fmincon-format options: HessFcn, HessMult, HessPattern, and JacobPattern. KNITRO options override fmincon-format options.
To use KNITRO options, create an options text file, whose format can be found in the KNITRO documentation. For example, if you have a KNITRO options file named knitropts, and an fmincon-format options structure named ktropts, you can pass them both by calling ktrlink like this:
[x fval] = ktrlink(@bigtoleft,[-1,-1,-1],... [],[],[],[],[],[],@twocone,ktropts,'knitropts')
If knitropts resides in a different folder, pass the path to the file. For example:
[x fval] = ktrlink(@bigtoleft,[-1,-1,-1],... [],[],[],[],[],[],@twocone,ktropts,... 'C:\Documents\Knitro\knitropts')
The following shows how fmincon-format options are mapped to KNITRO options.
fmincon Option | KNITRO Option | Default Value |
---|---|---|
Algorithm | algorithm | 'interior-point' |
AlwaysHonorConstraints | honorbounds | 'bounds' |
Display | outlev | 'none' |
FinDiffType | gradopt | 'forward' |
GradConstr | gradopt | 'off' |
GradObj | gradopt | 'off' |
HessFcn | hessopt | [ ] |
MaxIter | maxit | 10000 |
TolFun | opttol | 1.00E–06 |
TolX | xtol | 1.00E–15 |
Hessian, LBFGS pairs | hessopt, lmsize | 'bfgs' |
HessMult | hessopt | [ ] |
HessPattern | [ ] | |
InitBarrierParam | bar_initmu | 0.1 |
InitTrustRegionRadius | delta | sqrt(numberOfVariables) |
JacobPattern | [ ] | |
MaxProjCGIter | maxcgit | 2*(numberOfVariables–numberOfEqualities) |
ObjectiveLimit | objrange | –1.0E20 |
ScaleProblem | scale | 'obj-and-constr' |
SubProblemAlgorithm | algorithm | 'ldl-factorization' |
TolCon | feastol | 1.00E-06 |
Note: KNITRO libraries allow you to pass simultaneously either the gradients of the objective function and all nonlinear constraints, or no gradients. Therefore, setting GradObj = 'on' and GradConstr = 'off' is inconsistent. If you attempt to pass inconsistent options, ktrlink warns you, and treats all gradients as if they had not been passed. |
When the Hessian of the Lagrangian is sparse, or the Jacobian of the nonlinear constraints is sparse, ktrlink makes use of the sparsity structure to speed the optimization and use less memory doing so.
ktrlink handles sparse matrices differently than other MATLAB functions. If you choose to use sparse matrices, ktrlink requires a sparsity pattern for nonlinear constraint Jacobians and for Hessians. The next two sections give the details of the sparsity patterns for nonlinear constraint Jacobians and for Hessians.
The sparsity pattern for constraint Jacobians is a matrix. You pass the matrix as the JacobPattern option. The structure of the matrix follows.
Let c denote the vector of m nonlinear inequality constraints, and let ceq denote the vector of m_{2} nonlinear equality constraints. If there are n dimensions, the Jacobian is an (m + m_{2})-by-n matrix. The Jacobian pattern J is
In other words, the ith row of the Jacobian pattern corresponds to the gradient of c_{i}. Inequality gradients lie above equality gradients (they have lower row numbers).
All that matters for the Jacobian pattern is whether or not the entries are zero. You can pass single-precision numbers, doubles, or logical true or false. You can pass the sparsity pattern as a MATLAB sparse matrix. If you have a large sparse matrix of constraints, it is more efficient to pass the pattern as a sparse matrix. Linear constraint matrices are automatically passed as sparse matrices.
The gradient of the constraints, calculated in the constraint function, has the transpose of the Jacobian pattern. For more information about the form of constraint gradients, see Nonlinear Constraints.
The Hessian is the matrix of second derivatives of the Lagrangian:
Give the matrix H as a full or sparse matrix of zero and nonzero elements. The elements can be single-precision numbers, doubles, or logical true or false.
The Hessian is a symmetric matrix. You can pass just the upper triangular pattern, or pass the whole matrix pattern.