Documentation Center

  • Trials
  • Product Updates

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.

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

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:

  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, 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:

    1. Launch Terminal, available in Applications > Utilities.

    2. Determine the shell:

      echo $SHELL
    3. 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
    4. 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:

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

    2. Select Properties.

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

    4. Click Environment Variables.

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

Using ktrlink to Optimize

  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 = optimoptions('ktrlink','Display','iter',...
              'GradConstr','on','GradObj','on');
  4. 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/.

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 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 OptionKNITRO OptionDefault Value
Algorithmalgorithm'interior-point'
AlwaysHonorConstraintshonorbounds'bounds'
Displayoutlev'none'
FinDiffTypegradopt'forward'
GradConstrgradopt'off'
GradObjgradopt'off'
HessFcnhessopt[ ]
MaxItermaxit10000
TolFunopttol1.00E–06
TolXxtol1.00E–15
Hessian, LBFGS pairshessopt, lmsize'bfgs'
HessMulthessopt[ ]
HessPattern [ ]
InitBarrierParambar_initmu0.1
InitTrustRegionRadiusdeltasqrt(numberOfVariables)
JacobPattern [ ]
MaxProjCGItermaxcgit2*(numberOfVariables–numberOfEqualities)
ObjectiveLimitobjrange–1.0E20
ScaleProblemscale'obj-and-constr'
SubProblemAlgorithmalgorithm'ldl-factorization'
TolConfeastol1.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.

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 m2 nonlinear equality constraints. If there are n dimensions, the Jacobian is an (m + m2)-by-n matrix. The Jacobian pattern J is

In other words, the ith row of the Jacobian pattern corresponds to the gradient of ci. 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.

Was this topic helpful?