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. On MacOS, make sure the R version being used is for Apple silicon processors.
Installation¶
The installation steps are as follows:
Set a
KNITRODIRenvironment variable pointing to the absolute path of the installation folder of Knitro.Set the
ARTELYS_LICENSEenvironment 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 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[1] * x[2], x0 = c(1, 1))
at the R command prompt. If your installation was successful, KnitroR
returns the following message:
=======================================
Commercial License
Artelys Knitro 15.1.0
=======================================
Knitro performing finite-difference gradient computation with 1 thread.
Knitro presolve eliminated 0 variables and 0 constraints.
concurrent_evals: 0
feastol 1e-06
feastol_abs 0.001
opttol 1e-06
opttol_abs 0.001
Problem Characteristics | Presolved
-----------------------
Problem type: NLP (unconstrained)
Objective: minimize / general
Number of variables: 2 | 2
bounds: lower upper range | lower upper range
0 0 0 | 0 0 0
free fixed | free fixed
2 0 | 2 0
Number of constraints: 0 | 0
eq. ineq. range | eq. ineq. range
linear: 0 0 0 | 0 0 0
quadratic: 0 0 0 | 0 0 0
nonlinear: 0 0 0 | 0 0 0
Number of nonzeros:
objective Jacobian Hessian | objective Jacobian Hessian
linear: 0 0 | 0 0
quadratic: 0 0 0 | 0 0 0
nonlinear: 2 0 0 | 2 0 0
total: 2 0 0 | 2 0 3
Coefficient range:
linear objective: [0e+00, 0e+00] | [0e+00, 0e+00]
linear constraints: [0e+00, 0e+00] | [0e+00, 0e+00]
quadratic objective: [0e+00, 0e+00] | [0e+00, 0e+00]
quadratic constraints: [0e+00, 0e+00] | [0e+00, 0e+00]
variable bounds: [0e+00, 0e+00] | [0e+00, 0e+00]
constraint bounds: [0e+00, 0e+00] | [0e+00, 0e+00]
Knitro using the Interior-Point/Barrier Direct algorithm.
Iter Objective FeasError OptError ||Step|| Time
-------- -------------- --------- --------- --------- --------
0 1.000000e+00 0.00e+00
1 0.000000e+00 0.00e+00 0.00e+00 1.41e+00 0.06
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 = 16
# of gradient evaluations = 0
Total program time (secs) = 0.05727 ( 0.051 CPU time)
Time spent in evaluations (secs) = 0.00016
===============================================================================
$status
[1] 0
$obj
[1] 0
$x
[1] 0 0
$lambda
[1] 0 0
$objGrad
[1] 0 0
$objGradIndexVars
[1] 0 1
$c
NULL
$r
NULL
$jac
NULL
$jacIndexCons
NULL
$jacIndexVars
NULL
$rsdJac
NULL
$rsdJacIndexRsds
NULL
$rsdJacIndexVars
NULL
$numFCevals
[1] 16
$numGAevals
[1] 0
$numHevals
[1] 0
$numHVevals
[1] 0
$numIters
[1] 1
$numCGiters
[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:
res <- knitro(nvar=..., ncon=..., x0=...,
objective=..., objGoal=..., gradient=..., gradientIndexVars=...,
constraints=..., constraintsIndexCons,
jacobian=..., jacIndexCons=..., jacIndexVars=...,
hessianLag=..., hessIndexVars1=..., hessIndexVars2=...,
callbackEvalFCGA=...,
objLinearStruct=..., objLinearStructIndexVars=...,
conLinearStruct=..., conLinearStructIndexCons=..., conLinearStructIndexVars=...,
objQuadraticStruct=..., objQuadraticStructIndexVars1=..., objQuadraticStructIndexVars2=...,
conQuadraticStruct=..., conQuadraticStructIndexCons=...,
conQuadraticStructIndexVars1=..., conQuadraticStructIndexVars2=...,
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[2] - x[1] * x[1])^2 + (1 - x[1])^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:
=======================================
Commercial License
Artelys Knitro 15.1.0
=======================================
Knitro performing finite-difference gradient computation with 1 thread.
Knitro presolve eliminated 0 variables and 0 constraints.
concurrent_evals: 0
feastol 1e-06
feastol_abs 0.001
opttol 1e-06
opttol_abs 0.001
Problem Characteristics | Presolved
-----------------------
Problem type: NLP (unconstrained)
Objective: minimize / general
Number of variables: 2 | 2
bounds: lower upper range | lower upper range
0 0 0 | 0 0 0
free fixed | free fixed
2 0 | 2 0
Number of constraints: 0 | 0
eq. ineq. range | eq. ineq. range
linear: 0 0 0 | 0 0 0
quadratic: 0 0 0 | 0 0 0
nonlinear: 0 0 0 | 0 0 0
Number of nonzeros:
objective Jacobian Hessian | objective Jacobian Hessian
linear: 0 0 | 0 0
quadratic: 0 0 0 | 0 0 0
nonlinear: 2 0 0 | 2 0 0
total: 2 0 0 | 2 0 3
Coefficient range:
linear objective: [0e+00, 0e+00] | [0e+00, 0e+00]
linear constraints: [0e+00, 0e+00] | [0e+00, 0e+00]
quadratic objective: [0e+00, 0e+00] | [0e+00, 0e+00]
quadratic constraints: [0e+00, 0e+00] | [0e+00, 0e+00]
variable bounds: [0e+00, 0e+00] | [0e+00, 0e+00]
constraint bounds: [0e+00, 0e+00] | [0e+00, 0e+00]
Knitro using the Interior-Point/Barrier Direct algorithm.
Iter Objective FeasError OptError ||Step|| Time
-------- -------------- --------- --------- --------- --------
0 2.420000e+01 0.00e+00
10 1.257347e+00 0.00e+00 2.98e+00 8.33e-02 0.04
20 1.397804e-01 0.00e+00 1.11e+00 3.64e-02 0.04
30 8.501737e-07 0.00e+00 1.34e-03 1.71e-03 0.04
33 2.006083e-11 0.00e+00 2.50e-08 2.66e-07 0.04
EXIT: Locally optimal solution found.
Final Statistics
----------------
Final objective value = 2.00608298511050e-11
Final feasibility error (abs / rel) = 0.00e+00 / 0.00e+00
Final optimality error (abs / rel) = 2.50e-08 / 2.50e-08
# of iterations = 33
# of CG iterations = 4
# of function evaluations = 171
# of gradient evaluations = 0
Total program time (secs) = 0.04293 ( 0.037 CPU time)
Time spent in evaluations (secs) = 0.00207
===============================================================================
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[1] - 2 + 400 * x[1]^3 - 400 * x[1] * x[2],
200 * (x[2] - x[1]^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:
=======================================
Commercial License
Artelys Knitro 15.1.0
=======================================
Knitro presolve eliminated 0 variables and 0 constraints.
concurrent_evals: 0
feastol 1e-06
feastol_abs 0.001
opttol 1e-06
opttol_abs 0.001
Problem Characteristics | Presolved
-----------------------
Problem type: NLP (unconstrained)
Objective: minimize / general
Number of variables: 2 | 2
bounds: lower upper range | lower upper range
0 0 0 | 0 0 0
free fixed | free fixed
2 0 | 2 0
Number of constraints: 0 | 0
eq. ineq. range | eq. ineq. range
linear: 0 0 0 | 0 0 0
quadratic: 0 0 0 | 0 0 0
nonlinear: 0 0 0 | 0 0 0
Number of nonzeros:
objective Jacobian Hessian | objective Jacobian Hessian
linear: 0 0 | 0 0
quadratic: 0 0 0 | 0 0 0
nonlinear: 2 0 0 | 2 0 0
total: 2 0 0 | 2 0 3
Coefficient range:
linear objective: [0e+00, 0e+00] | [0e+00, 0e+00]
linear constraints: [0e+00, 0e+00] | [0e+00, 0e+00]
quadratic objective: [0e+00, 0e+00] | [0e+00, 0e+00]
quadratic constraints: [0e+00, 0e+00] | [0e+00, 0e+00]
variable bounds: [0e+00, 0e+00] | [0e+00, 0e+00]
constraint bounds: [0e+00, 0e+00] | [0e+00, 0e+00]
Knitro using the Interior-Point/Barrier Direct algorithm.
Iter Objective FeasError OptError ||Step|| Time
-------- -------------- --------- --------- --------- --------
0 2.420000e+01 0.00e+00
10 1.257345e+00 0.00e+00 2.98e+00 8.33e-02 0.05
20 9.336057e-02 0.00e+00 3.58e-01 1.87e-02 0.05
30 3.729542e-08 0.00e+00 1.33e-03 1.38e-03 0.06
33 9.540253e-19 0.00e+00 1.81e-08 4.96e-08 0.06
EXIT: Locally optimal solution found.
Final Statistics
----------------
Final objective value = 9.54025265803981e-19
Final feasibility error (abs / rel) = 0.00e+00 / 0.00e+00
Final optimality error (abs / rel) = 1.81e-08 / 1.81e-08
# of iterations = 33
# of CG iterations = 4
# of function evaluations = 65
# of gradient evaluations = 36
Total program time (secs) = 0.05774 ( 0.055 CPU time)
Time spent in evaluations (secs) = 0.03707
===============================================================================
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.
Additional examples¶
More examples using the R interface are provided in
the examples/R directory of the Knitro distribution.