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:
- 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 alist
, 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, whereresult$objval[[i]]
stores the value formodel$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 whileobjboundc
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
andcbasis
named components into the corresponding named components for the next model. This vector contains one entry for each column ofA
.- 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 ofA
.
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, theobjval
andx
named components will be present.For linear and quadratic programs, if a solution is available, then the
pi
andrc
named components will also be present. For models with quadratic constraints, if the parameterqcpdual
is set to 1, the named componentqcpi
will be present. If the final solution is a basic solution (computed by simplex), thenvbasis
andcbasis
will be present. If the model is an unbounded linear program and the InfUnbdInfo parameter is set to 1, the named componentunbdray
will be present. Finally, if the model is an infeasible linear program and the InfUnbdInfo parameter is set to 1, the named componentsfarkasdual
andfarkasproof
will be set.For mixed integer problems, no dual information (i.e.
pi
,slack
,rc
,vbasis
,cbasis
,qcslack
,qcpi
,ubdray
orfarkasdual
) is ever available. When multiple solutions are found, thepool
andpoolobjbound
named components will be present. Depending on thestatus
named component value, the named componentsnodecount
,objbound
,objbundc
andmipgap
will be available.For continuous and mixed-integer models, under normal execution, the named components
runtime
,work
,itercount
andbaritercount
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:
- Example:
model <- gurobi_read('examples/data/klein1.mps') iis <- gurobi_iis(model)
- Returns:
The
gurobi_iis()
function returns alist
, 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 followingnamed 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 followingnamed 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 followingnamed 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 followingnamed 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 thepenalties
argument). These penalties are interpreted in different ways, depending on the value of therelaxobjtype
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 specifyrelaxobjtype=1
, the objective for the feasibility relaxation is to minimize the weighted sum of the squares of the bound and constraint violations. If you specifyrelaxobjtype=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 frompenalties$lb
,penalties$ub
andpenalties$rhs
. You can provide the special penalty valueInf
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. Ifminrelax=FALSE
, optimizing the returned model gives a solution that minimizes the cost of the violation. Ifminrelax=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 thatgurobi_feasrelax
must solve an optimization problem to find the minimum possible relaxation whenminrelax=TRUE
, which can be quite expensive.penalties –
The
penalties
argument is a list of lists, having the following optional named components (default: allInf
):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
valuep
is violated by 2.0, it would contribute2*p
to the feasibility relaxation objective forrelaxobjtype=0
,2*2*p
forrelaxobjtype=1
, andp
forrelaxobjtype=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. Ifminrelax==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:
- Returns:
A
model
list variable, as described in the model parameter section.- Example:
model <- gurobi_read('stein9.mps') relaxed <- gurobi_relax(model)