# Getting started with MATLAB

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

```
[x fval] = knitromatlab(@(x)cos(x),1)
```

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

```
x = 3.1416, fval = -1.
```

If you do not get this output but an error stating that *knitromatlab* 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 *knitromatlab* interface

The Knitro/MATLAB interface function is very similar to
MATLAB’s built-in *fmincon* function; the most elaborate
form is:

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

but the simplest function call reduces to:

```
x = knitromatlab(fun,x0)
```

The *knitromatlab* function was designed to provide a similar user experience to MATLAB’s
*fmincon* optimization function. See Knitro / MATLAB reference for a more extensive
description of *knitromatlab* interface.

The *ktrlink* interface previously provided with the MATLAB Optimization Toolbox is
no longer supported. See the reference manual on using *knitrolink* instead.

## 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 = knitromatlab(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 11.0.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 structure in the model, then Knitro would callback to AMPL to get these evaluations as well as the evaluations of their derivatives. The MATLAB interface does not currently provide quadratic structure to Knitro, so 32 function evaluations are needed in the MATLAB example (extra function evaluations were needed to approximate the first derivatives). On a large problem, this could have made a very significant difference in performance.

## Additional examples

More examples are provided in the `knitromatlab`

directory of the
Knitro distribution.