Getting started with MATLAB

The Knitro interface for MATLAB is provided with your Knitro distribution. To test whether your installation is correct, type in the expression:

[x fval] = knitro_nlp(@(x)cos(x),1)

at the MATLAB command prompt. If your installation was successful, knitro_nlp returns:

x = 3.1416, fval = -1.

If you do not get this output but an error stating that knitro_nlp was not found, it probably means that the path has not been added to MATLAB. If Knitro is found and called but returns an error, it probably means that no license was found. In any of these situations, please see Troubleshooting.

The Knitro/MATLAB interface

The Knitro/MATLAB interface provides functions for most of the functions available in MATLAB’s Optimization Toolbox, including functions for linear programming (LP), quadratic programming (QP), nonlinear programming (NLP), mixed-integer linear programming (MILP), nonlinear least-squares and nonlinear equations. It also provides specialized functions for quadratically constrained quadratic programs (QCQP) and mixed-integer nonlinear programs (MINLPs). The APIs for the Knitro functions are very similar to the corresponding Optimization Toolbox functions, but with extra parameters for passing Knitro-specific options and extended modeling features. For example, the interface for the NLP function knitro_nlp is very similar to MATLAB’s built-in fmincon function; the most elaborate form is:

[x,fval,exitflag,output,lambda,grad,hessian] = ...
        knitro_nlp(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon, ...
        extendedFeatures,options,KnitroOptions)

but the simplest function call reduces to:

x = knitro_nlp(fun,x0)

The Knitro MATLAB functions were designed to provide a similar user experience to MATLAB’s optimization functions. See Knitro / MATLAB reference for a more extensive description of this interface.

First MATLAB example

Let’s consider the same example as before (in section Getting started with AMPL), converted into MATLAB.

% objective to minimize
obj = @(x) 1000 - x(1)^2 - 2*x(2)^2 - x(3)^2 - x(1)*x(2) - x(1)*x(3);

% No nonlinear equality constraints.
ceq  = [];

% Specify nonlinear inequality constraint to be nonnegative
c2 =  @(x) x(1)^2 + x(2)^2 + x(3)^2 - 25;

% "nlcon" should return [c, ceq] with c(x) <= 0 and ceq(x) = 0
% so we need to negate the inequality constraint above
nlcon = @(x)deal(-c2(x), ceq);

% Initial point
x0  = [2; 2; 2];

% No linear inequality contraint ("A*x <= b")
A = [];
b = [];

% Since the equality constraint "c1" is linear, specify it here  ("Aeq*x = beq")
Aeq = [8 14 7];
beq = [56];

% lower and upper bounds
lb = zeros(3,1);
ub = [];

% solver call
x = knitro_nlp(obj, x0, A, b, Aeq, beq, lb, ub, nlcon);

Saving this code in a file example.m in the current folder and issuing example at the MATLAB prompt produces the following output.

=======================================
          Commercial License
         Artelys Knitro 12.2.0
=======================================

Knitro presolve eliminated 0 variables and 0 constraints.

algorithm:            1
gradopt:              4
hessopt:              2
honorbnds:            1
maxit:                10000
outlev:               1
par_concurrent_evals: 0
Knitro changing bar_initpt from AUTO to 3.
Knitro changing bar_murule from AUTO to 4.
Knitro changing bar_penaltycons from AUTO to 1.
Knitro changing bar_penaltyrule from AUTO to 2.
Knitro changing bar_switchrule from AUTO to 2.
Knitro changing linesearch from AUTO to 1.
Knitro changing linsolver from AUTO to 2.

Problem Characteristics                                 (   Presolved)
-----------------------
Objective goal:  Minimize
Objective type:  general
Number of variables:                                  3 (           3)
    bounded below only:                               0 (           0)
    bounded above only:                               0 (           0)
    bounded below and above:                          3 (           3)
    fixed:                                            0 (           0)
    free:                                             0 (           0)
Number of constraints:                                2 (           2)
    linear equalities:                                1 (           1)
    quadratic equalities:                             0 (           0)
    gen. nonlinear equalities:                        0 (           0)
    linear one-sided inequalities:                    0 (           0)
    quadratic one-sided inequalities:                 0 (           0)
    gen. nonlinear one-sided inequalities:            1 (           1)
    linear two-sided inequalities:                    0 (           0)
    quadratic two-sided inequalities:                 0 (           0)
    gen. nonlinear two-sided inequalities:            0 (           0)
Number of nonzeros in Jacobian:                       6 (           6)
Number of nonzeros in Hessian:                        6 (           6)

EXIT: Locally optimal solution found.

Final Statistics
----------------
Final objective value               =   9.36000000000049e+02
Final feasibility error (abs / rel) =   7.11e-15 / 5.47e-16
Final optimality error  (abs / rel) =   1.21e-07 / 7.56e-09
# of iterations                     =          7
# of CG iterations                  =          0
# of function evaluations           =         32
# of gradient evaluations           =          0
Total program time (secs)           =       0.01931 (     0.019 CPU time)
Time spent in evaluations (secs)    =       0.01341

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

The objective function value is the same (about 936.0) as in the AMPL example. However, even though we solved the same problem, things went quite differently behind the scenes in these two examples; as we will see in Section Derivatives, AMPL provides derivatives to Knitro automatically, whereas in MATLAB the user must do it manually. Since we did not provide these derivatives, Knitro had to approximate them. Note that with AMPL, there were 0 function evaluations. This is because the model only has linear and quadratic structure and AMPL is able to provide all this structural information directly to Knitro so that Knitro does not callback to AMPL for any evaluations. If there were more general nonlinear structures in the model, then Knitro would callback to AMPL to get these evaluations as well as the evaluations of their derivatives.

Since the objective function and constraint functions are all linear or quadratic, this is referred to as a quadratically constrained quadratic program (QCQP). Knitro 12.1 introduced a new function knitro_qcqp for solving this class of problem. Using the new knitro_qcqp function we can load the whole model without having to specify any callbacks, and then the Knitro performance through MATLAB is more similar to the performance through AMPL. See the example exampleQCQP.m provided with the Knitro distribution and the Knitro/MATLAB reference section Knitro / MATLAB reference for more details.

Additional examples

More examples are provided in the knitromatlab directory of the Knitro distribution.