# Getting started with R

The Knitro interface for R, called `KnitroR`, is provided with your Knitro distribution.

In order to install it, you need R 3.0 or later.

The installation steps are as follows:

1. Set a `KNITRODIR` environment variable pointing to the absolute path of the installation folder of Knitro.

2. Set the `ARTELYS_LICENSE` environment variable to point to the absolute path of the license file of Knitro.

3. Open a terminal in the directory containing the KnitroR folder (this folder is generally \$KNITRODIR/examples/R) and type the following command:

```R CMD INSTALL KnitroR
```

The pdf documentation of KnitroR can be built using:

```R CMD Rd2pdf KnitroR
```

To test whether your installation is correct, type in the expression:

```library('KnitroR')
knitro(objective = function(x) x * x, x0 = c(1, 1))
```

at the R command prompt. If your installation was successful, `KnitroR` returns the following message:

```=======================================
Artelys Knitro 13.2.0
=======================================

Knitro presolve eliminated 0 variables and 0 constraints.

concurrent_evals:        0
The problem is identified as unconstrained.

Problem Characteristics                                 (   Presolved)
-----------------------
Objective goal:  Minimize
Objective type:  general
Number of variables:                                  2 (           2)
bounded below only:                               0 (           0)
bounded above only:                               0 (           0)
bounded below and above:                          0 (           0)
fixed:                                            0 (           0)
free:                                             2 (           2)
Number of constraints:                                0 (           0)
linear 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:            0 (           0)
linear two-sided inequalities:                    0 (           0)
quadratic two-sided inequalities:                 0 (           0)
gen. nonlinear two-sided inequalities:            0 (           0)
Number of nonzeros in Jacobian:                       0 (           0)
Number of nonzeros in Hessian:                        0 (           3)

Knitro using the Interior-Point/Barrier Direct algorithm.

Iter      Objective      FeasError   OptError    ||Step||    CGits
--------  --------------  ----------  ----------  ----------  -------
0    1.000000e+00   0.000e+00
1    0.000000e+00   0.000e+00   0.000e+00   1.414e+00        0

EXIT: Locally optimal solution found.

Final Statistics
----------------
Final objective value               =   0.00000000000000e+00
Final feasibility error (abs / rel) =   0.00e+00 / 0.00e+00
Final optimality error  (abs / rel) =   0.00e+00 / 0.00e+00
# of iterations                     =          1
# of CG iterations                  =          0
# of function evaluations           =          8
# of gradient evaluations           =          0
Total program time (secs)           =       0.04607 (     0.047 CPU time)
Time spent in evaluations (secs)    =       0.00001

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

\$status
 0

\$obj
 0

\$x
 0 0

\$lambda
 0 0

 0 0

 0 1

\$c
NULL

\$r
NULL

\$jac
NULL

\$jacIndexCons
NULL

\$jacIndexVars
NULL

\$rsdJac
NULL

\$rsdJacIndexRsds
NULL

\$rsdJacIndexVars
NULL

\$numFCevals
 8

\$numGAevals
 0

\$numHevals
 0

\$numHVevals
 0

\$numIters
 1

\$numCGiters
 8
```

## Troubleshooting `KnitroR`

If running the above example does not work, it may be the case that either the `KNITRODIR` or `ARTELYS_LICENSE` environment variable was not set correctly, or was not recognized from within your R session. In particular IDEs used with R, especially, RStudio, do not inherit environment variable settings from your terminal (e.g. variables set in `.bashrc` on Linux-based systems) but instead, inherit system wide environment variables.

This could cause issues such as “license not found” or “KNITRODIR undefined” messages. In order to prevent these issues, you should define `KNITRODIR` and `ARTELYS_LICENSE` system wide. How to do this depends on your operating system.

Another way to circumvent this issue is to directly set these environment variables at the R command prompt (or in your R script) from the IDE before calling KnitroR. For instance, in order to set these variables and then run the example above, you would issue the following sequence of commands in an R session:

```> Sys.setenv(ARTELYS_LICENSE = 'my/absolute/path/to/license')
> Sys.setenv(KNITRODIR = 'my/absolute/path/to/knitro')
> library('KnitroR')
> knitro(objective = function(x) x * x, x0 = c(1,1))
```

Setting environment variables directly in R such as in the example above, will work on all platforms. For more general Knitro installation troubleshooting help, please see Troubleshooting.

## The `KnitroR` interface

The Knitro solver can be called via the following optimization function:

```res <- knitro(nvar=..., ncon=..., x0=...,
constraints=..., constraintsIndexCons,
jacobian=..., jacIndexCons=..., jacIndexVars=...,
hessianLag=..., hessIndexVars1=..., hessIndexVars2=...,
objLinearStruct=..., objLinearStructIndexVars=...,
conLinearStruct=..., conLinearStructIndexCons=..., conLinearStructIndexVars=...,
xL=..., xU=..., cL=..., cU=...,
xTypes=..., xTypesIndexVars=...,
xStrategies=..., xStrategiesIndexVars=...,
xPriorities=..., xPrioritiesIndexVars=...,
xHonorBnds=..., xHonorBndsIndexVars=...,
ccTypes=..., ccIdxList1=..., ccIdxList2=...,
objScaleFactor=..., xScaleFactors=..., xScaleCenters=...,
cScaleFactors=..., ccScaleFactors=...,
newptCallback=...,
options=..., optionsFile=...,)
```

but the simplest function call reduces to:

```res <- knitro(objective=..., x0=...)
res <- knitro(objective=..., xL=...)
res <- knitro(objective=..., xU=...)
res <- knitro(nvar=..., objective=...)
```

## First R example

The following introductory examples shows how to solve the Rosenbrock banana function.

```library('KnitroR')

# Rosenbrock Banana function
eval_f <- function(x)
{
return( 100 * (x - x * x)^2 + (1 - x)^2 )
}

# initial values
x0 <- c(-1.2, 1)

res <- knitro(x0 = x0, objective = eval_f)
```

We can save this code in a file ‘example.R’ and run it from the R command prompt via the following command:

```source('example.R')
```

`KnitroR` returns the following output:

```=======================================
Artelys Knitro 13.2.0
=======================================

Knitro presolve eliminated 0 variables and 0 constraints.

concurrent_evals:        0
The problem is identified as unconstrained.

Problem Characteristics                                 (   Presolved)
-----------------------
Objective goal:  Minimize
Objective type:  general
Number of variables:                                  2 (           2)
bounded below only:                               0 (           0)
bounded above only:                               0 (           0)
bounded below and above:                          0 (           0)
fixed:                                            0 (           0)
free:                                             2 (           2)
Number of constraints:                                0 (           0)
linear 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:            0 (           0)
linear two-sided inequalities:                    0 (           0)
quadratic two-sided inequalities:                 0 (           0)
gen. nonlinear two-sided inequalities:            0 (           0)
Number of nonzeros in Jacobian:                       0 (           0)
Number of nonzeros in Hessian:                        0 (           3)

Knitro using the Interior-Point/Barrier Direct algorithm.

Iter      Objective      FeasError   OptError    ||Step||    CGits
--------  --------------  ----------  ----------  ----------  -------
0    2.420000e+01   0.000e+00
10    1.041827e+00   0.000e+00   3.760e+00   1.537e-01        0
20    6.142193e-02   0.000e+00   9.571e-01   4.461e-02        0
30    5.418836e-08   0.000e+00   3.747e-03   2.290e-03        0
37    1.866328e-11   0.000e+00   1.666e-06   5.990e-11        0

EXIT: Primal feasible solution; terminate because the relative change in
the objective function < 1.000000e-15 for 5 consecutive feasible iterations.
Decrease ftol or increase ftol_iters to try for more accuracy.

Final Statistics
----------------
Final objective value               =   1.86632757150284e-11
Final feasibility error (abs / rel) =   0.00e+00 / 0.00e+00
Final optimality error  (abs / rel) =   1.67e-06 / 1.67e-06
# of iterations                     =         37
# of CG iterations                  =          4
# of function evaluations           =        191
# of gradient evaluations           =          0
Total program time (secs)           =       0.01465 (     0.031 CPU time)
Time spent in evaluations (secs)    =       0.00018

===============================================================================
```

Note in the example above that Knitro approximated the gradient of the objective function using finite-differences. However, Knitro will typically converge much faster if the first derivatives can be provided. This can be done by defining a function to evaluate the gradient of the objective:

```eval_grad_f <- function(x)
{
return (c(2 * x - 2 + 400 * x^3 - 400 * x * x,
200 * (x - x^2)))
}
```

and then passing this in the call to knitro:

```res <- knitro(x0 = x0, objective = eval_f, gradient = eval_grad_f)
```

In this case, `KnitroR` returns the following output:

```=======================================
Artelys Knitro 13.2.0
=======================================

Knitro presolve eliminated 0 variables and 0 constraints.

concurrent_evals:        0
The problem is identified as unconstrained.

Problem Characteristics                                 (   Presolved)
-----------------------
Objective goal:  Minimize
Objective type:  general
Number of variables:                                  2 (           2)
bounded below only:                               0 (           0)
bounded above only:                               0 (           0)
bounded below and above:                          0 (           0)
fixed:                                            0 (           0)
free:                                             2 (           2)
Number of constraints:                                0 (           0)
linear 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:            0 (           0)
linear two-sided inequalities:                    0 (           0)
quadratic two-sided inequalities:                 0 (           0)
gen. nonlinear two-sided inequalities:            0 (           0)
Number of nonzeros in Jacobian:                       0 (           0)
Number of nonzeros in Hessian:                        0 (           3)

Knitro using the Interior-Point/Barrier Direct algorithm.

Iter      Objective      FeasError   OptError    ||Step||    CGits
--------  --------------  ----------  ----------  ----------  -------
0    2.420000e+01   0.000e+00
10    1.041833e+00   0.000e+00   3.760e+00   1.537e-01        0
20    6.136281e-02   0.000e+00   9.652e-01   4.395e-02        0
30    5.772274e-08   0.000e+00   3.907e-03   2.378e-03        0
33    2.708220e-22   0.000e+00   2.992e-10   2.089e-07        0

EXIT: Locally optimal solution found.

Final Statistics
----------------
Final objective value               =   2.70821957121458e-22
Final feasibility error (abs / rel) =   0.00e+00 / 0.00e+00
Final optimality error  (abs / rel) =   2.99e-10 / 2.99e-10
# of iterations                     =         33
# of CG iterations                  =          4
# of function evaluations           =         58
# of gradient evaluations           =         34
Total program time (secs)           =       0.01170 (     0.016 CPU time)
Time spent in evaluations (secs)    =       0.00448

===============================================================================
```

## Further information

The `knitro` function can be used to solve mixed-integer models by defining integer variables using the parameter `xTypes`. `KnitroR` also includes a function `knitrolsq` dedicated to solving least square problems. Another chapter of this documentation is dedicated to the R interface (Knitro / R reference) and provides exhaustive references.

Any Knitro option can also be provided to the R interface. A comprehensive documentation of Knitro options is available in the section Knitro user options.

More examples using the R interface are provided in the `examples/R` directory of the Knitro distribution.