R Interface

This section describes the Gurobi R interface. We begin with information on how to set up Gurobi for use within R. An example of how to use the R interface follows.

Installing the R Package

To begin, you'll need to install the Gurobi package in R. The R command for doing this is:

install.packages('<R-package-file>')
The Gurobi R package file can be found in the <installdir>/R directory of your Gurobi installation (e.g., /opt/gurobi500/linux64/R for the 64-bit Linux version of Gurobi 5.0). You should browse the <installdir>/R directory to find the exact name of the file for your platform (the 64-bit Linux package is in file gurobi_5.0-0_R_x86_64-pc-linux-gnu.tar.gz, while the Windows package is in file gurobi_5.0-0.zip).

You will need to be careful that the R binary and the Gurobi package you install both use the same instruction set. For example, if you are using the 64-bit version of R, you'll need to install the 64-bit version of Gurobi, and the 64-bit Gurobi R package. This is particularly important on Windows systems, where the error messages that result from instruction set mismatches can be quite cryptic.

Example

Let us now turn our attention to an example of using Gurobi to solve a simple MIP model. Our example optimizes the following model:

maximize x + y + 2 z    
subject to x + 2 y + 3 z $\leq$ 4
  x + y     $\geq$ 1
  x, y, z binary  
Note that this is the same model that was modeled and optimized in the C Interface section.

This is the complete source code for our example (also available in <installdir>/examples/R/mip.R)...

library('gurobi')

model <- list()

model$A          <- matrix(c(1,2,3,1,1,0), nrow=2, ncol=3, byrow=T)
model$obj        <- c(1,1,2)
model$modelsense <- "max"
model$rhs        <- c(4,1)
model$sense      <- c('<', '>')
model$vtype      <- 'B'

params <- list(OutputFlag=0)

result <- gurobi(model, params)

print('Solution:')
print(result$objval)
print(result$x)

Example details

Let us now walk through the example, line by line, to understand how it achieves the desired result of optimizing the indicated model.

The example begins by importing the Gurobi package (library('gurobi')). R programs that call Gurobi must include this line.

Building the model

The example now builds an optimization model. The data associated with an optimization model must be stored in a single list variable. Named components in this list contain the different parts of the model. A few components are mandatory: the constraint matrix (A), the objective vector (obj), the right-hand side vector (rhs), and the constraint sense vector (sense). A model variable can also include optional components (e.g., the objective sense modelsense).

In our example, we use the built-in R matrix function to build the constraint matrix A. A is stored as a dense matrix here. You can also store A as a sparse matrix, using either the sparse_triplet_matrix function from the slam package or the sparseMatrix class from the Matrix package. Sparse input matrices are illustrated in the lp2.R example.

Subsequent statements populate other components of the model variable, including the objective vector, the right-hand-side vector, and the constraint sense vector. In each case, we use the built-in c function to initialize the array arguments.

In addition to the mandatory components, this example also sets two optional components: modelsense and vtype. The former is used to indicate the sense of the objective function. The default is minimization, so we've set the components equal to 'max' to indicate that we would like to maximize the specified objective. The vtype component is used to indicate the types of the variables in the model. In our example, all variables are binary ('B'). Note that our interface allows you to specify a scalar value for any array argument. The Gurobi interface will expand that scalar to a constant array of the appropriate length. In this example, the scalar value 'B' will be expanded to an array of length 3, containing one 'B' value for each column of A.

Modifying Gurobi parameters

The next statement creates a list variable that will be used to modify a Gurobi parameter:

params <- list(OutputFlag=0)
In this example, we wish to set the Gurobi OutputFlag parameter to 0 in order to shut off Gurobi output. The Gurobi R interface allows you to pass a list of the Gurobi parameters you would like to change. Please consult the Parameters section of the Gurobi Reference Manual for a complete list of all Gurobi parameters.

Solving the model

The next statement is where the actual optimization occurs:

result <- gurobi(model, params)
We pass the model and the optional list of parameter changes to the gurobi() function. It computes an optimal solution to the specified model and returns the computed result.

Printing the solution

The gurobi() function returns a list as its result. This list contains a number of components, where each component contains information about the computed solution. The available components depend on the result of the optimization, the type of model that was solved (LP, QP, SOCP, or MIP), and the algorithm used to solve the model. This result list will always contain an integer status component, which indicates whether Gurobi was able to compute an optimal solution to the model. You should consult the Status Codes section of the Gurobi Reference Manual for a complete list of all possible status codes. If Gurobi was able to find a solution to the model, the return value will also include objval and x components. The former gives the objective value for the computed solution, and the latter is the computed solution vector (one entry per column of the constraint matrix). For continuous models, we will also return dual information (reduced costs and dual multipliers), and possibly an optimal basis.

In our example, we simply print the optimal objective value (result$objval) and the optimal solution vector (result$x).

Running the example

To run one of the R examples provided with the Gurobi distribution, you can use the source command in R. For example, if you are running R from the Gurobi R examples directory, you can say:

> source('mip.R')

If the Gurobi package was successfully installed, you should see the following output:

[1] "Solution:"
[1] 3
[1] 1 0 1

The R example directory <installdir>/examples/R contains a number of examples. We encourage you to browse and modify them in order to become more familiar with the Gurobi R interface.