Solving models with the Gurobi R interface

The Gurobi R interface can be used to solve optimization problems of the following form:

minimize <span>$</span>x^TQx + c^Tx + \mathrm{alpha}<span>$</span>  
subject to <span>$</span>Ax = b<span>$</span> (linear constraints)
  <span>$</span>\ell \le x \le u<span>$</span> (bound constraints)
  some <span>$</span>x_j<span>$</span> integral (integrality constraints)
  some <span>$</span>x_k<span>$</span> lie within second order cones (cone constraints)
  <span>$</span>x^TQc  x + q^Tx \le \mathrm{beta}<span>$</span> (quadratic constraints)
  some <span>$</span>x_i<span>$</span> in SOS (special ordered set constraints)

Many of the model components listed here are optional. For example, integrality constraints may be omitted. We'll discuss the details of how models are represented shortly.

The function gurobi, described next, allows you to take a model represented using R data structures and solve it with the Gurobi Optimizer.

gurobi ( model, params=NULL )

The two arguments are R list variables, each consisting of multiple named components. The first argument contains the optimization model to be solved. The second contains an optional set of Gurobi parameters to be modified during the solution process. The return value of this function is a list, also consisting of multiple named components. It contains the result of performing the optimization on the specified model. We'll now discuss the details of each of these lists.

The optimization model

As we've mentioned, the model argument to the gurobi function is a list variable, containing multiple named components that represent the various parts of the optimization model. Several of these fields are optional. Note that you refer to a named component of a R list variable by adding a dollar sign to the end of the variable name, followed by the name of the named component. For example, model$A refers to named component A of variable model.

Note that all matrix named components within the model variable can be dense or sparse. Sparse matrices should be built using either sparseMatrix from the Matrix package, or simple_triplet_matrix from the slam package.

The following is an enumeration of all of the named components of the model argument that Gurobi will take into account when optimizing the model:

A
The linear constraint matrix.

obj
The linear objective vector (c vector in the problem statement). You must specify one value for each column of A.

sense
The senses of the linear constraints. Allowed values are '=', '<', or '>'. You must specify one value for each row of A, or a single value to specify that all constraints have the same sense. This must be a char array.

rhs
The right-hand side vector for the linear constraints (<span>$</span>b<span>$</span> in the problem statement). You must specify one value for each row of A.

lb (optional)
The lower bound vector. When present, you must specify one value for each column of A. When absent, each variable has a lower bound of 0.

ub (optional)
The upper bound vector. When present, you must specify one value for each column of A. When absent, the variables have infinite upper bounds.

vtype (optional)
The variable types. This char array is used to capture variable integrality constraints. Allowed values are 'C' (continuous), 'B' (binary), 'I' (integer), 'S' (semi-continuous), or 'N' (semi-integer). Binary variables must be either 0 or 1. Integer variables can take any integer value between the specified lower and upper bounds. Semi-continuous variables can take any value between the specified lower and upper bounds, or a value of zero. Semi-integer variables can take any integer value between the specified lower and upper bounds, or a value of zero. When present, you must specify one value for each column of A, or a single value to specify that all variables have the same type. When absent, each variable is treated as being continuous. Refer to this section for more information on variable types.

modelsense (optional)
The optimization sense. Allowed values are 'min' (minimize) or 'max' (maximize). When absent, the default optimization sense is minimization.

modelname (optional)
The name of the model. The name appears in the Gurobi log, and when writing a model to a file.

objcon (optional)
The constant offset in the objective function ( <span>$</span>\mathrm{alpha}<span>$</span> in the problem statement).

vbasis (optional)
The variable basis status vector. Used to provide an advanced starting point for the simplex algorithm. You would generally never concern yourself with the contents of this array, but would instead simply pass it from the result of a previous optimization run to the input of a subsequent run. When present, you must specify one value for each column of A.

cbasis (optional)
The constraint basis status vector. Used to provide an advanced starting point for the simplex algorithm. Consult the vbasis description for details. When present, you must specify one value for each row of A.

Q (optional)
The quadratic objective matrix. When present, Q must be a square matrix whose row and column counts are equal to the number of columns in A.

cones (optional)
Second-order cone constraints. A list of lists. When present, each element in cones defines a single cone constraint: <span>$</span>\sum x_{i}^{2} \le y^2<span>$</span>. The constraint is defined via model$cones[[i]]$index = [k idx], with the first entry in index corresponding to the index of the variable on the right-hand side of the constraint, and the remaining entries corresponding to the indices of the variables on the left-hand side of the constraint.

quadcon (optional)
The quadratic constraints. A list of lists. When present, each element in quadcon defines a single quadratic constraint: <span>$</span>x^TQc  x + q^Tx \le \mathrm{beta}<span>$</span>. The Qc matrix must be a square matrix whose row and column counts are equal to the number of columns of A. It is stored in model$quadcon[[i]]$Qc. The optional q vector defines the linear terms in the constraint. If present, you must specify a value for q for each column of A. It is stored in model$quadcon[[i]]$q. The scalar beta defines the right-hand side of the constraint. It is stored in model$quadcon[[i]]$rhs.

sos (optional)
The Special Ordered Set (SOS) constraints. A list of lists. When present, each entry in sos defines a single SOS constraint. A SOS constraint can be of type 1 or 2. The type of SOS constraint <span>$</span>i<span>$</span> is specified via model$sos[[i]]$type. A type 1 SOS constraint is a set of variables for which at most one variable in the set may take a value other than zero. A type 2 SOS constraint is an ordered set of variables where at most two variables in the set may take non-zero values. If two take non-zeros values, they must be contiguous in the ordered set. The members of an SOS constraint are specified by placing their indices in vector model$sos[[i]]$index. Weights associated with SOS members are provided in vector model$sos[[i]]$weight. Please refer to this section for details on SOS constraints.

pwlobj (optional)
The piecewise-linear objective functions. A list of lists. When present, each entry in pwlobj defines a piecewise-linear objective function of a single variable. The index of the variable whose objective function is being defined is stored in model$pwlobj[[i]]$var. The <span>$</span>x<span>$</span> values for the points that define the piecewise-linear function are stored in
model$pwlobj[[i]]$x. The values in the <span>$</span>x<span>$</span> vector must be in non-decreasing order. The <span>$</span>y<span>$</span> values for the points that define the piecewise-linear function are stored in model$pwlobj[[i]]$y.

start (optional)
The MIP start vector. The MIP solver will attempt to build an initial solution from this vector. When present, you must specify a start value for each variable. Note that you can set the start value for a variable to NA, which instructs the MIP solver to try to fill in a value for that variable.
If any of the mandatory components listed above are missing, the gurobi() function will return an error.

Below is an example that demonstrates the construction of a simple optimization model:

model <- list()

model$A          <- matrix(c(1,1,0,0,1,1), nrow=2, byrow=T)
model$obj        <- c(1,1,2)
model$modelsense <- 'max'
model$rhs        <- c(1,1)
model$sense      <- c('<', '<')

You can also build A as a sparse matrix, using either sparseMatrix or simple_triplet_matrix:

model$A <- spMatrix(2, 3, c(1, 1, 2, 2), c(1, 2, 2, 3), c(1, 1, 1, 1))
model$A <- simple_triplet_matrix(c(1, 1, 2, 2), c(1, 2, 2, 3), c(1, 1, 1, 1))

Note that the Gurobi interface allows you to specify a scalar value for any of the array-valued components. The specified value will be expanded to an array of the appropriate size, with each component of the array equal to the scalar (e.g., model$rhs <- 1 would be equivalent to model$rhs <- c(1,1) in the example).

Parameters

The optional params argument to the gurobi() function is also a list of named components. The name of each named component must be the name of a Gurobi parameter, and the associated value should be the desired value of that parameter. Gurobi parameters allow users to modify the default behavior of the Gurobi optimization algorithms. You can find a complete list of the available Gurobi parameters here.

To create a list that would set the Gurobi Method parameter to 2 and the ResultFile parameter parameter to model.mps, you would do the following:

params <- list(Method=2, ResultFile='model.mps')

We should say a bit more about the ResultFile parameter. If this parameter is set, the optimization model that is eventually passed to Gurobi will also be output to the specified file. The filename suffix should be one of .mps, .lp, .rew, or .rlp, to indicate the desired file format (see the file formats section for details on Gurobi file formats).

The optimization result

The gurobi() function returns a list, with the various results of the optimization stored in its named components. The specific results that are available depend on the type of model that was solved, and the status of the optimization. The following is a list of fields that might be available in the returned result. We'll discuss the circumstances under which each will be available after presenting the list.

status
The status of the optimization, returned as a string. The desired result is 'OPTIMAL', which indicates that an optimal solution to the model was found. Other status are possible, for example if the model has no feasible solution or if you set a Gurobi parameter that leads to early solver termination. See the Status Code section for further information on the Gurobi status codes.

objval
The objective value of the computed solution.

runtime
The elapsed wall-clock time (in seconds) for the optimization.

x
The computed solution. This array contains one entry for each column of A.

slack
The constraint slack for the computed solution. This array contains one entry for each row of A.

pi
Dual values for the computed solution (also known as shadow prices). This array contains one entry for each row of A.

rc
Variable reduced costs for the computed solution. This array contains one entry for each column of A.

vbasis
Variable basis status values for the computed optimal basis. You generally should not concern yourself with the contents of this array. If you wish to use an advanced start later, you would simply copy the vbasis and cbasis arrays into the corresponding fields for the next model. This array contains one entry for each column of A.

cbasis
Constraint basis status values for the computed optimal basis. This array contains one entry for each row of A.

objbound
Best available bound on solution (lower bound for minimization, upper bound for maximization).

itercount
Number of simplex iterations performed.

baritercount
Number of barrier iterations performed.

nodecount
Number of branch-and-cut nodes explored.

The status component will be present in all cases. It indicates whether Gurobi was able to find a proven optimal solution to the model. In cases where a solution to the model was found, optimal or otherwise, the objval, x, and slack components will be present. For linear and quadratic programs, if a solution is available, then the pi and rc components will also be present. Finally, if the final solution is a basic solution (computed by simplex), then vbasis and cbasis will be present.

The following is an example of how the results of the gurobi() call might be extracted and output:

result <- gurobi(model, params)
print(result$objval)
print(result$x)

Please consult this section for a discussion of some of the practical issues associated with solving a precisely defined mathematical model using finite-precision floating-point arithmetic.

Try Gurobi for Free

Choose the evaluation license that fits you best, and start working with our Expert Team for technical guidance and support.

Evaluation License
Get a free, full-featured license of the Gurobi Optimizer to experience the performance, support, benchmarking and tuning services we provide as part of our product offering.
Academic License
Gurobi supports the teaching and use of optimization within academic institutions. We offer free, full-featured copies of Gurobi for use in class, and for research.
Cloud Trial

Request free trial hours, so you can see how quickly and easily a model can be solved on the cloud.

Search