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 14.2.0
=======================================
Knitro presolve eliminated 0 variables and 0 constraints.
concurrent_evals: 0
gradopt: 4
Problem Characteristics ( Presolved)
-----------------------
Objective goal: Minimize
Objective type: general
Number of variables: 3 ( 3)
bounded below only: 3 ( 3)
bounded above only: 0 ( 0)
bounded below and above: 0 ( 0)
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: 0 ( 6)
Knitro using the Interior-Point/Barrier Direct algorithm.
Iter Objective FeasError OptError ||Step|| CGits
-------- -------------- ---------- ---------- ---------- -------
0 9.760000e+02 1.300e+01
9 9.360000e+02 0.000e+00 1.999e-09 1.976e-09 0
EXIT: Locally optimal solution found.
Final Statistics
----------------
Final objective value = 9.36000000000340e+02
Final feasibility error (abs / rel) = 0.00e+00 / 0.00e+00
Final optimality error (abs / rel) = 2.00e-09 / 1.25e-10
# of iterations = 9
# of CG iterations = 0
# of function evaluations = 40
# of gradient evaluations = 0
Total program time (secs) = 0.01589 ( 0.033 CPU time)
Time spent in evaluations (secs) = 0.00545
===============================================================================
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). Using the 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.
The Knitro/MATLAB interface also provides a generic knitro_solve function
that can be used to solve any model defined using the MATLAB “problem-based”
optimization setup, which provides automatic differentiation. See
for example, exampleNLP1Problem.m provided with the Knitro distribution
for an example using this interface.
Additional examples
More examples are provided in the knitromatlab directory of the
Knitro distribution.