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