R API - Solving a Model

gurobi(model, params=NULL)

This function optimizes the given model. The algorithm used for the optimization depends on the model type (simplex or barrier for a continuous model; branch-and-cut for a MIP model). Upon successful completion it will return a list variable containing solution information.

Please consult Variables and Constraints section in the reference manual for a discussion of some of the practical issues associated with solving a precisely defined mathematical model using finite-precision floating-point arithmetic.

Parameters:

• model – The model list must contain a valid Gurobi model. See the model argument section for more information.

• params – The params list, when provided, contains a list of modified Gurobi parameters. See the params argument section for more information.

Example:

result <- gurobi(model, params)
if (result$status == 'OPTIMAL') {
  print(result$objval)
  print(result$x)
} else {
  cat('Optimization returned status:', formatC(result$status), '\n')
}

Returns:

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, the parameters used, and the status of the optimization. The following is a list of named components that might be available in the returned result. We will discuss the circumstances under which each will be available after presenting the list.

Model named components

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. Note that for multi-objective models result$objval will be a vector, where result$objval[[i]] stores the value for model$multiobj[[i]].

objbound

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

objboundc

The best unrounded bound on the optimal objective. In contrast to objbound, this attribute does not take advantage of objective integrality information to round to a tighter bound. For example, if the objective is known to take an integral value and the current best bound is 1.5, objbound will return 2.0 while objboundc will return 1.5.

mipgap

Current relative MIP optimality gap; computed as \(\vert ObjBound-ObjVal\vert/\vert ObjVal\vert\) (where \(ObjBound\) and \(ObjVal\) are the MIP objective bound and incumbent solution objective, respectively). Returns GRB_INFINITY when an incumbent solution has not yet been found, when no objective bound is available, or when the current incumbent objective is 0. This is only available for mixed-integer problems.

runtime

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

work

The work (in work units) spent on the optimization. As opposed to the runtime in seconds, the work is deterministic. This means that on the same hardware and with the same parameter and attribute settings, solving the same model twice will lead to exactly the same amount of work in each of the two solves. One work unit corresponds very roughly to one second, but this greatly depends on the hardware on which Gurobi is running and on the model that has been solved.

itercount

Number of simplex iterations performed.

baritercount

Number of barrier iterations performed.

nodecount

Number of branch-and-cut nodes explored.

maxvio

Value of the maximal (unscaled) violation of the returned solution.

farkasproof

Magnitude of infeasibility violation in Farkas infeasibility proof. Only available if the model was found to be infeasible. Please refer to Attribute section in the reference manual for details.

Variable named components

x

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

rc

Variable reduced costs for the computed solution. This vector 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 vector. If you wish to use an advanced start later, you would simply copy the vbasis and cbasis named components into the corresponding named components for the next model. This vector contains one entry for each column of A.

unbdray

Unbounded ray. Provides a vector that, when added to any feasible solution, yields a new solution that is also feasible but improves the objective. Only available if the model is found to be unbounded. This vector contains one entry for each column of A.

Linear constraint named components

slack

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

pi

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

cbasis

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

farkasdual

Farkas infeasibility proof. Only available if the model was found to be infeasible. Please refer to Attribute section in the reference manual for details.

Quadratic constraint named components

qcslack

The quadratic constraint slack in the current solution. This vector contains one entry for each quadratic constraint.

qcpi

The dual values associated with the quadratic constraints. This vector contains one entry for each quadratic constraint.

Solution Pool named components

pool

When multiple solutions are found during the optimization call, these solutions are returned in this named component. A list of lists. When present, each list has the following named components:

objval

Stores the objective value of the \(i\)-th solution in result$pool[[i]]$objval. Note that when the model is a multi-objective model, instead of a single value,result$pool[[i]]$objval[j] stores the value of the \(j\)-th objective function for the \(i\)-th solution.

xn

Stores the \(i\)-th solution in result$pool[[i]]$xn. This vector contains one entry for each column of A.

Note that to query the number of solutions stored, you can query the length of result$pool.

poolobjbound

For single-objective MIP optimization problems, this value gives a bound on the best possible objective of an undiscovered solution. The difference between this value and objbound is that the former gives an objective bound for undiscovered solutions, while the latter gives a bound for any solution.

What is Available When

The status named 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 and x named components will be present.

For linear and quadratic programs, if a solution is available, then the pi and rc named components will also be present. For models with quadratic constraints, if the parameter qcpdual is set to 1, the named component qcpi will be present. If the final solution is a basic solution (computed by simplex), then vbasis and cbasis will be present. If the model is an unbounded linear program and the InfUnbdInfo parameter is set to 1, the named component unbdray will be present. Finally, if the model is an infeasible linear program and the InfUnbdInfo parameter is set to 1, the named components farkasdual and farkasproof will be set.

For mixed integer problems, no dual information (i.e. pi, slack, rc, vbasis, cbasis, qcslack, qcpi, ubdray or farkasdual) is ever available. When multiple solutions are found, the pool and poolobjbound named components will be present. Depending on the status named component value, the named components nodecount, objbound, objbundc and mipgap will be available.

For continuous and mixed-integer models, under normal execution, the named components runtime, work, itercount and baritercount will be available.

gurobi_iis(model, params=NULL)

Compute an Irreducible Inconsistent Subsystem (IIS).

An IIS is a subset of the constraints and variable bounds with the following properties:

• It is still infeasible, and

• If a single constraint or bound is removed, the subsystem becomes feasible.

Note that an infeasible model may have multiple IISs. The one returned by Gurobi is not necessarily the smallest one; there may exist others with fewer constraints or bounds.

You can obtain information about the outcome of the IIS computation from the returned IIS result (described below). Note that this method can be used to compute IISs for both continuous and MIP models.

Parameters:

• model – The model list must contain a valid Gurobi model. See the model argument section for more information.

• params – The params list, when provided, contains a list of modified Gurobi parameters. See the params argument section for more information.

Example:

model <- gurobi_read('examples/data/klein1.mps')
iis <- gurobi_iis(model)

Returns:

The gurobi_iis() function returns a list, with various results stored in its named components. The specific results that are available depend on the type of model.

The returned list will always contain the following named components:

minimal

A logical scalar that indicates whether the computed IIS is minimal. It will normally be true, but it may be false if the IIS computation was stopped early (due to a time limit or a user interrupt).

Arows

A logical vector that indicates whether a linear constraint appears in the computed IIS.

lb

A logical vector that indicates whether a lower bound appears in the computed IIS.

ub

A logical vector that indicates whether a upper bound appears in the computed IIS.

If your model contains general constraints, the returned list will also contain the following named components:

genconmax

A logical vector that indicates whether a general MAX constraint appears in the computed IIS.

genconmin

A logical vector that indicates whether a general MIN constraint appears in the computed IIS.

genconand

A logical vector that indicates whether a general AND constraint appears in the computed IIS.

genconor

A logical vector that indicates whether a general OR constraint appears in the computed IIS.

genconabs

A logical vector that indicates whether a general ABS constraint appears in the computed IIS.

genconind

A logical vector that indicates whether a general INDICATOR constraint appears in the computed IIS.

genconpwl

A logical vector that indicates whether a general piecewise-linear function constraint appears in the computed IIS.

genconpoly

A logical vector that indicates whether a polynomial function constraint appears in the computed IIS.

genconexp

A logical vector that indicates whether a natural exponential function constraint appears in the computed IIS.

genconexpa

A logical vector that indicates whether a exponential function constraint appears in the computed IIS.

genconlog

A logical vector that indicates whether a natural logarithmic function constraint appears in the computed IIS.

genconloga

A logical vector that indicates whether a logarithmic function constraint appears in the computed IIS.

genconlogistic

A logical vector that indicates whether a logistic function constraint appears in the computed IIS.

genconpow

A logical vector that indicates whether a power function constraint appears in the computed IIS.

genconsin

A logical vector that indicates whether a SIN function constraint appears in the computed IIS.

genconcos

A logical vector that indicates whether a COS function constraint appears in the computed IIS.

gencontan

A logical vector that indicates whether a TAN function constraint appears in the computed IIS.

If your model contains SOS constraints, the returned list will also contain the following named component:

sos

A logical vector that indicates whether an SOS constraint appears in the computed IIS

If your model contains quadratic constraints, the returned list will also contain the following named component:

quadcon

A logical vector that indicates whether a quadratic constraint appears in the computed IIS.

To write the result of the IIS computation into an .ilp file format, set the ResultFile parameter before calling the gurobi function.

Example:

params$resultfile <- 'infeas_submodel.ilp'
result <- gurobi(model, params)

gurobi_feasrelax(model, relaxobjtype, minrelax, penalties, params=NULL)

This function computes a feasibility relaxation for the input model argument. The feasibility relaxation is a model that, when solved, minimizes the amount by which the solution violates the bounds and linear constraints of the original model. You must provide a penalty to associate with relaxing each individual bound or constraint (through the penalties argument). These penalties are interpreted in different ways, depending on the value of the relaxobjtype argument.

For an example of how this function transforms a model, and more details about the variables and constraints created, please see this section.

Parameters:

• model – The model list must contain a valid Gurobi model. See the model argument section for more information.

• relaxobjtype – The approach used to impose penalties on violations. If you specify relaxobjtype=0, the objective for the feasibility relaxation is to minimize the sum of the weighted magnitudes of the bound and constraint violations. If you specify relaxobjtype=1, the objective for the feasibility relaxation is to minimize the weighted sum of the squares of the bound and constraint violations. If you specify relaxobjtype=2, the objective for the feasibility relaxation is to minimize the weighted count of bound and constraint violations. In all cases, the weights are taken from penalties$lb, penalties$ub and penalties$rhs. You can provide the special penalty value Inf to indicate that the corresponding bound or constraint cannot be relaxed.

• minrelax – The minrelax argument is a boolean that controls the type of feasibility relaxation that is created. If minrelax=FALSE, optimizing the returned model gives a solution that minimizes the cost of the violation. If minrelax=TRUE, optimizing the returned model finds a solution that minimizes the original objective, but only from among those solutions that minimize the cost of the violation. Note that gurobi_feasrelax must solve an optimization problem to find the minimum possible relaxation when minrelax=TRUE, which can be quite expensive.

• penalties –

  The penalties argument is a list of lists, having the following optional named components (default: all Inf):

  • lb Penalty for violating each lower bound. There should be as many values as variables into the model. Note that artificial variables may have been created automatically by Gurobi for range constraints.

  • ub Penalty for violating each upper bound. There should be as many values as variables into the model. Note that artificial variables may have been created automatically by Gurobi for range constraints.

  • rhs Penalty for violating each constraint. There should be as many values as constraints into the model.

  To give an example, if a constraint with penalties.rhs value p is violated by 2.0, it would contribute 2*p to the feasibility relaxation objective for relaxobjtype=0, 2*2*p for relaxobjtype=1, and p for relaxobjtype=2.

• params – The params list, when provided, contains a list of modified Gurobi parameters. See the params argument section for more information.

Returns:

A list containing two named components: result$model, a list variable, as described in the model argument section. result$feasobj, a scalar. If minrelax==TRUE this is the relaxation problem objective value, 0.0 otherwise.

Example:

penalties <- list()
model <- gurobi_read('stein9.mps')
penalties$lb <- rep(1,length(model$lb))
penalties$ub <- rep(1,length(model$ub))
penalties$rhs <- rep(1,length(model$rhs))
feasrelaxresult <- gurobi_feasrelax(model, 0, FALSE, penalties)

gurobi_relax(model, params=NULL)

Create the relaxation of a MIP model. Transforms integer variables into continuous variables, and removes SOS and general constraints.

Parameters:

• model – The model list must contain a valid Gurobi model. See the model argument section for more information.

• params – The params list, when provided, contains a list of modified Gurobi parameters. See the params argument section for more information.

Returns:

A model list variable, as described in the model parameter section.

Example:

model <- gurobi_read('stein9.mps')
relaxed <- gurobi_relax(model)