Optimization Toolbox™

ktrlink: An Interface to KNITRO^® Libraries

What Is ktrlink?

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.

Back to Top

Installation and Configuration

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

Note   ktrlink is not compatible with the Solaris™ 64-bit architecture.

Perform the following steps to configure your system to use ktrlink:

1. Install MATLAB and the KNITRO libraries on your system.

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

3. Start MATLAB.

Setting the System Path to Include KNITRO^® Libraries

In order to use ktrlink, you need to tell MATLAB where the KNITRO binary file (libknitro.so, libknitro.dylib, knitro520.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:

  1. In Terminal (available in the Utilities folder of the Applications folder) enter the following:

     edit /etc/profile

  2. Add the following line to the end of the file:

     export DYLD_LIBRARY_PATH=<file_absolute_path>:$DYLD_LIBRARY_PATH

• Windows:

  1. At the Windows desktop, right-click My Computer (Windows XP) or Computer (Vista).

  2. Select Properties.

  3. Click the Advanced tab (Windows XP) or Advanced System Settings (Vista).

  4. Click Environment Variables.

  5. Under System variables, edit the Path variable to add the KNITRO library directory.

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 x = 3.1416, fval = -1.

Back to Top

Example Using ktrlink

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

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

3. Set the options so that ktrlink has iterative display and uses the gradients included in the objective and constraint functions:

   ktropts = optimset('Display','iter',...
             'GradConstr','on','GradObj','on');

4. Run the optimization starting at [0;0], using the structure ktropts:

   [x fval flag] = ktrlink(@sinhtilt,[0;0],...
              [],[],[],[],[],[],@ellipseparabola,ktropts)

KNITRO software returns the following output:

======================================
             KNITRO 5.2
       Ziena Optimization, Inc.
       website:  www.ziena.com
       email:   info@ziena.com
======================================

algorithm:    1
hessopt:      2
honorbnds:    1
outlev:       4
KNITRO changing bar_murule from AUTO to 1.
KNITRO changing bar_initpt from AUTO to 2.
KNITRO changing honorbnds to 0 (because there are no bounds).

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(maj/min)  Res   Objective      Feas err    Opt err     ||Step||    CG its
--------------- ---  -------------  ----------  ----------  ----------  -------
      0/      0 ---  0.000000e+000  0.000e+000
      1/      1 Acc -1.371022e-001  0.000e+000  1.976e-001  3.432e-001        0
      2/      2 Acc -3.219187e-001  0.000e+000  1.003e-001  4.748e-001        0
      3/      3 Acc -3.442829e-001  0.000e+000  6.287e-002  8.198e-002        0
      4/      4 Acc -3.598395e-001  8.358e-003  2.989e-002  1.904e-001        0
      5/      5 Acc -3.619202e-001  6.453e-003  2.812e-003  1.481e-001        0
      6/      6 Acc -3.591357e-001  0.000e+000  9.999e-004  1.901e-002        0
      7/      7 Acc -3.599184e-001  0.000e+000  2.441e-004  3.406e-003        0
      8/      8 Acc -3.599195e-001  0.000e+000  2.000e-004  1.749e-004        0
      9/      9 Acc -3.601176e-001  0.000e+000  1.076e-005  6.823e-004        0
     10/     10 Acc -3.601176e-001  0.000e+000  2.000e-006  9.351e-007        0
     11/     11 Acc -3.601196e-001  0.000e+000  2.001e-008  7.893e-006        0

EXIT: LOCALLY OPTIMAL SOLUTION FOUND.

Final Statistics
----------------
Final objective value               = -3.60119556291455e-001
Final feasibility error (abs / rel) =   0.00e+000 / 0.00e+000
Final optimality error  (abs / rel) =   2.00e-008 / 2.00e-008
# of iterations (major / minor)     =         11 /       11
# of function evaluations           =         13
# of gradient evaluations           =         12
Total program time (secs)           =       0.081 (     0.156 CPU time)
Time spent in evaluations (secs)    =       0.079

=========================================================================

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

Back to Top

Setting Options

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 directory, 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.

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.

Back to Top

Sparse Matrix Considerations

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.

Sparsity Pattern for Nonlinear Constraints

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₂ nonlinear equality constraints. If there are n dimensions, the Jacobian is an (m + m₂)-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.

Sparsity Pattern for Hessians

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.

Back to Top

External Interface

Argument and Options Reference