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

Set a

`KNITRODIR`

environment variable pointing to the absolute path of the installation folder of Knitro.Set the

`ARTELYS_LICENSE`

environment variable to point to the absolute path of the license file of Knitro.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 --build KnitroR

This will generate a .zip or .tar.gz package which you will be able to install from R using the command:

install.packages('<path to KnitroR package>', repos=NULL)

The pdf documentation of KnitroR can be built using:

```
R CMD Rd2pdf KnitroR
```

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

```
knitro(objective=function(x) x[1]*x[2], x0=c(1,1))
```

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

```
$statusMessage
[1] "Optimal solution found !"
$x
[1] 0 0
$lambda
[1] 0 0
$objective
[1] 0
$constraints
numeric(0)
$iter
[1] 1
$objEval
[1] 9
$gradEval
[1] 0
```

## 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[1]*x[2], 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:

```
sol <- knitro(nvar=..., ncon=..., x0=...,
objective=..., gradient=..., constraints=...,
jacobian=..., jacIndexCons=..., jacIndexVars=...,
hessianLag=..., hessIndexRows=..., hessIndexCols=...,
xL=..., xU=..., cL=..., cU=...,
options=...)
```

but the simplest function call reduces to:

```
sol <- knitro(objective=..., x0=...)
sol <- knitro(objective=..., xL=...)
sol <- knitro(objective=..., xU=...)
sol <- 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[2] - x[1] * x[1])^2 + (1 - x[1])^2 )
}
# initial values
x0 <- c( -1.2, 1 )
sol <- 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:

```
=======================================
Commercial License
Artelys Knitro 12.2.0
=======================================
Knitro performing finite-difference gradient computation with 1 thread.
Knitro presolve eliminated 0 variables and 0 constraints.
gradopt: 2
hessopt: 2
outlev: 1
par_concurrent_evals: 0
The problem is identified as unconstrained.
Knitro changing algorithm from AUTO to 1.
Knitro changing bar_initpt from AUTO to 3.
Knitro changing bar_murule from AUTO to 4.
Knitro changing bar_penaltycons from AUTO to 0.
Knitro changing bar_penaltyrule from AUTO to 2.
Knitro changing bar_switchrule from AUTO to 0.
Knitro changing linesearch from AUTO to 2.
Knitro changing linsolver from AUTO to 2.
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)
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: 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: 3 ( 3)
EXIT: Locally optimal solution found.
Final Statistics
----------------
Final objective value = 1.86566398862799e-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 = 34
# of CG iterations = 5
# of function evaluations = 137
# of gradient evaluations = 0
Total program time (secs) = 0.01034 ( 0.010 CPU time)
Time spent in evaluations (secs) = 0.00031
===============================================================================
```

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) {
grad_f <-rep(0, length(x))
grad_f[1] <- 2*x[1]-2+400*x[1]^3-400*x[1]*x[2]
grad_f[2] <- 200*(x[2]-x[1]^2)
return( grad_f )
}
```

and then passing this in the call to *knitro*:

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

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

```
=======================================
Commercial License
Artelys Knitro 12.2.0
=======================================
Knitro presolve eliminated 0 variables and 0 constraints.
hessopt: 2
outlev: 1
par_concurrent_evals: 0
The problem is identified as unconstrained.
Knitro changing algorithm from AUTO to 1.
Knitro changing bar_initpt from AUTO to 3.
Knitro changing bar_murule from AUTO to 4.
Knitro changing bar_penaltycons from AUTO to 0.
Knitro changing bar_penaltyrule from AUTO to 2.
Knitro changing bar_switchrule from AUTO to 0.
Knitro changing linesearch from AUTO to 2.
Knitro changing linsolver from AUTO to 2.
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)
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: 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: 3 ( 3)
EXIT: Locally optimal solution found.
Final Statistics
----------------
Final objective value = 2.70685058249270e-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 = 5
# of function evaluations = 58
# of gradient evaluations = 34
Total program time (secs) = 0.00972 ( 0.010 CPU time)
Time spent in evaluations (secs) = 0.00024
===============================================================================
```

## Further information

More functions are availables and R interface can be used to solve MINLP and least squares problems as well. 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.

## Additional examples

More examples using the R interface are provided in
the `examples/R`

directory of the Knitro distribution.