This section will work through a simple example in order to illustrate the use of the Gurobi R API. The example builds a simple Mixed Integer Programming model, optimizes it, and outputs the optimal objective value.
We have special instructions on how to set up Gurobi for use with R. See How do I install Gurobi for R? for more information.
This example builds a trivial MIP model, solves it, and prints the solution.
The example
Our example optimizes the following model:
| maximize | x | + | y | + | 2 z | ||
| subject to | x | + | 2 y | + | 3 z | <= | 4 |
| x | + | y | >= | 1 | |||
| x, y, z binary | |||||||
In the following sections, we will walk through the example, line by line, to understand how it achieves the desired result of optimizing the above model .
The complete source code for our example can be found in:
- Online: Example mip.R
- Distribution: <installdir>/examples/R/mip.R
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.
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 simple_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 component 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.
One important note about default variable bounds: the convention in math programming is that a variable will by default have a lower bound of 0 and an infinite upper bound. If you'd like your variables to have different bounds, you'll need to provide them explicitly.
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.
Optimizing 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.
Reporting the results
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 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. For a list of all possible fields and details about when you will find them populated, refer to the documentation for the gurobi function in the reference manual.
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.