Knitro / R reference

Usage of KnitroR is described here.

What is KnitroR?

KnitroR is the interface used to call Knitro from the R environment (requires R 3.0 or later).

KnitroR offers several routines to call Knitro from R:

  • knitro, which is an interface for the standard Knitro nonlinear optimizer

  • knitrolsq, which solves bound constrained nonlinear least-squares problems in vectorial format, that is

    \min_p \; 0.5\cdot\|F(X, p) - Y\|_2^2 \\
 p_L \leq p \leq p_U.

    This type of fitting problems is ubiquitous in statistics and data analytics. This function is based on the internal Knitro implementation of nonlinear least-squares.

  • knitromip, which is tailored to solve mixed-integer nonlinear programs

  • An important point when passing sparse matrices (jacobian of the nonlinear constraints or hessian of Lagrangian) to Knitro is that indices of the sparse matrix vectors must start from 0.

Syntax

The most elaborate form for general nonlinear programs is

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

but the simplest function calls reduce to:

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

You must provide an objective function and the number of variables or a vector that is used to compute the number of variables. All other parameters are optional. For instance any of the following other forms may be used (note that this list is not exhaustive):

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

When the functions jacobian or hessianLag are provided but the corresponding sparsity vectors jacIndexCons, jacIndexVars, jacBitMap, hessIndexRows, hessIndexCols or hessBitMap are not, KnitroR computes dense sparsity patterns internally.

An API for MPECs is also available via the R function Knitro. It takes the following form :

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

The API for bound constrained nonlinear least-squares problems has the following form :

sol <- knitrolsq(dimp=..., par0=..., dataFrameX=..., dataFrameY=...,
             residual=..., jacobian=...,
             parL=..., parU=...,
             xScaleFactors=..., xScaleCenters=...,
             objScaleFactor=....,
             jacIndexRows=..., jacIndexCols=...,
             options=..., optionsFile=...)

The API for mixed-integer NLPs is

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

The following other forms may be used:

sol <- knitromip(nvar=..., ncon=..., x0=...,
                 objective=..., gradient=..., constraints=...,
                 jacobian=..., jacBitMap=...,
                 hessianLag=..., hessBitMap=...,
                 xL=..., xU=..., cL=..., cU=...,
                 xType=..., cFnType=..., objfntype=...,
                 options=...)
sol <- knitromip(nvar=..., ncon=..., x0=...,
                 objective=..., gradient=..., constraints=...,
                 jacobian=..., hessianLag=...,
                 xL=..., xU=..., cL=..., cU=...,
                 xType=..., cFnType=..., objfntype=...,
                 options=...)

Input Arguments of knitro

Below is a description of the input arguments of the knitro function of KnitroR.

Input Argument Description
objective

Objective function to be minimized or maximized.

objective accepts a vector x and returns a scalar f, the objective function evaluated at x.

gradient

Gradient of the objective function.

gradient accepts a vector x and returns a vector g (using the R function c(…))

constraints

Nonlinear constraints function.

constraints accepts a vector x and returns a vector c (using the R function c(…))

jacobian

Jacobian of nonlinear constraints function, as a sparse matrix.

jacobian accepts a vector x and returns a vector containing the nonzero elements of the jacobian. Via R function c(…)

jacIndexCons Vector containing the row indices of the nonzero elements of the jacobian Via R function c(…)
jacIndexVars Vector containing the column indices of the nonzero elements of the jacobian Via R function c(…)
jacBitMap Vector containing 1 or 0 depending on whether jacobian element is non-zero or not. Vector elements are supposed to be given in row major. Via R function c(…)
hessianLag Hessian of Lagrangian, as a sparse matrix. Vector of nonzero elements, via R function c(…)
hessIndexRows Row indices of nonzero elements of hessian of Lagrangian. Via R function c(…)
hessIndexCols Column indices of nonzero elements of hessian of Lagrangian. Via R function c(…)
hessBitMap Vector containing 1 or 0 depending on whether hessian element is non-zero or not. Vector elements are supposed to be given in row major. Via R function c(…)
printPrimal User-defined function to print primal iterate after every Knitro iteration. Activated by setting option newpoint=3.
printDual User-defined function to print dual iterate after every Knitro iteration. Activated by setting option newpoint=3.
printObjective User-defined function to print objective after every Knitro iteration. Activated by setting option newpoint=3.
printGradient User-defined function to display gradient after every Knitro iteration. Activated by setting option newpoint=3.
printConstraints User-defined function to display constraints after every Knitro iteration. Activated by setting option newpoint=3.
printJacobian User-defined function to display jacobian after every Knitro iteration. Activated by setting option newpoint=3.
xL Vector of lower bounds on variables.
xU Vector of upper bounds on variables.
cL Vector of lower bounds on constraints.
cU Vector of upper bounds on constraints.
xScaleFactors Vector of scaling factors on variables.
xScaleCenters Vector of scaling centers on variables.
cScaleFactors Vector of scaling factors on nonlinear constraints.
ccScaleFactors Vector of scaling factors on complementarity constraints.
objScaleFactor Scaling factor on objective function.
constraintTypes Constraint types (general, linear or quadratic).
options Options stored as an R list. They can also be set in a file named ktrOptions.opt via the field optionsFile.
optionsFile Options file. The user can specify all basic KNITRO options via a file with extension .opt.

Input Arguments for MPECS in knitro

Below is a description of the input arguments, which are specific to MPECs in the knitro function of KnitroR.

Input Argument Description
numCompConstraints Number of complementarity constraints among nonlinear constraints.
ccIdxList1 List of indices of first variables in complementarity constraints. Via R function c(…)
ccIdxList2 List of indices of second variables in complementarity constraints. Via R function c(…)

Input Arguments for knitromip

Below is a description of the input arguments, which are specific to MINLPs in the knitromip function of KnitroR.

Input Argument Description
xType R vector indicating variable types: 0 (continuous), 1 (integer) or 2 (binary).
cFnType R vector indicating constraint types: 0 (convex), 1 (nonconvex) or 2 (uncertain)
objFnType Type of objective function: 0 (convex), 1 (nonconvex) or 2 (uncertain)
options List of options which are specific to MINLPs. xPriorities: branching priorities for integer variables mipBranchRule: branching rule in Branch-and-Bound algorithm mipHeuristic: heuristic to find initial integer feasible solution mipMethod: 0 (automatic choice), 1 (Branch-and-Bound), 2 (Quesada-Grossmann) mipLPalg: algorithm for LP subproblem.

Input Arguments for knitrolsq

Below is a descriptions of the API of the R function knitrolsq in KnitroR. The function knitrolsq is based on Knitro’s internal implementation of bound-constrained nonlinear least-squares.

Input Argument Description
dimp Dimension of fitting parameter.
par0 Initial guess on fitting parameter.
dataFrameX Data frame containing samples x_i.
dataFrameY Data frame containing samples y_i.
residual Vector of nonlinear least-squares residuals (R function returning c(…)).
jacobian Jacobian of nonlinear least-squares residuals residual (R function returning c(…)).
parL Vector of lower bounds on fitting parameter (R vector).
parU Vector of upper bounds on fitting parameter (R vector).
xScaleCenters Vector of scaling centers on fitting parameter. (R vector).
xScaleFactors Vector of scaling factors on fitting parameter. (R vector).
objScaleFactor Scaling factor on nonlienar least-squares objective function.

Output Arguments of knitro and knitromip

Output Argument Description
statusMessage Knitro’s status message.
x Locally optimal primal solution.
lambda Locally optimal dual solution.
objective Objective value at the optimal solution x.
constraints Constraints value at the optimal solution x.
objEval Number of objective evaluations.
gradEval Number of gradient evaluations.

Output Arguments of knitrolsq

Output Argument Description
statusMessage Knitro’s status message.
paramFit Locally optimal solution for fitting parameter.
objective Least-squares objective value at the optimal solution paramFit.
iter Number of iterations.
objEval Number of objective evaluations.
gradEval Number of gradient evaluations.