A package to Model (Mixed) Integer Programs

Description

A package to model (mixed) integer programs. It provides an algebraic way to model mixed integer linear optimization problems directly in R. The model is solver-independent and thus offers the possibility to solve a model with different solvers. See the ompr website <https://dirkschumacher.github.io/ompr/> for more information, documentation and examples.

Author(s)

Maintainer: Dirk Schumacher mail@dirk-schumacher.net

See Also

Useful links:

• https://github.com/dirkschumacher/ompr

• Report bugs at https://github.com/dirkschumacher/ompr/issues

An S4 class that represents a collection of variables

Description

It will multiply the numeric vector with both the constant and the variable in 'LinearVariableSum'

It will multiply the numeric vector with both the constant and the variable in 'LinearVariableSum'

Equivalent to 'e1 + -1 * e2'

Equivalent to '(-1 * e2) - (-1 * e1)'

Add two object of 'LinearVariableSum'. I.e. variables + constants

Equivalent to 'e1 + (-1) * e2'

Adds the variables in the rhs to the variables in the lhs and returns another 'LinearVariableSum'.

Equivalent to 'e2 + e1'

Equivalent to '-1 * (e2 - e1)'

Equivalent to 'e1 + -1 * e2'

Adds a constant (rhs) to constant slot of the lhs object.

Equivalent to 'e2 + e1'

Equivalent to 'e1 * (-1)'

Equivalent to 'e1 * (-1)'

Equivalent to 'e1'

Equivalent to 'e1'

Adds a constant numeric vector to a variable. The constant needs to be a vector of length 1.

Equivalent to 'e2 + e1'

Equivalent to 'e1 + -1 * e2'

Equivalent to '(-1 * e2) - (-1 * e1)'

Equivalent to 'e1 * (1 / e2)'

Equivalent to 'e1 * (1 / e2)'

Adds two variables together. Same values for variable, row and col will be added. Everything else merged.

Equivalent to 'e1 + -1 * e2'

Multiplies the coefficients rowwise with a given numeric vector. If the numeric vector is a 'linear_transposed_vector', it will multiply the vector with each variable per row.

Equivalent to 'e2 * e1'

This creates a new variable collection as a subset of the previously defined indexed variable. A variable collection essentially is a data frame having values for rows and columns of the final model matrix.

Usage

## S4 method for signature 'LinearVariableSum,numeric'
e1 * e2

## S4 method for signature 'numeric,LinearVariableSum'
e1 * e2

## S4 method for signature 'LinearVariableSum,numeric'
e1 - e2

## S4 method for signature 'numeric,LinearVariableSum'
e1 - e2

## S4 method for signature 'LinearVariableSum,LinearVariableSum'
e1 + e2

## S4 method for signature 'LinearVariableSum,LinearVariableSum'
e1 - e2

## S4 method for signature 'LinearVariableSum,LinearVariableCollection'
e1 + e2

## S4 method for signature 'LinearVariableCollection,LinearVariableSum'
e1 + e2

## S4 method for signature 'LinearVariableCollection,LinearVariableSum'
e1 - e2

## S4 method for signature 'LinearVariableSum,LinearVariableCollection'
e1 - e2

## S4 method for signature 'LinearVariableSum,numeric'
e1 + e2

## S4 method for signature 'numeric,LinearVariableSum'
e1 + e2

## S4 method for signature 'LinearVariableSum,missing'
e1 - e2

## S4 method for signature 'LinearVariableCollection,missing'
e1 - e2

## S4 method for signature 'LinearVariableSum,missing'
e1 + e2

## S4 method for signature 'LinearVariableCollection,missing'
e1 + e2

## S4 method for signature 'LinearVariableCollection,numeric'
e1 + e2

## S4 method for signature 'numeric,LinearVariableCollection'
e1 + e2

## S4 method for signature 'LinearVariableCollection,numeric'
e1 - e2

## S4 method for signature 'numeric,LinearVariableCollection'
e1 - e2

## S4 method for signature 'LinearVariableCollection,numeric'
e1 / e2

## S4 method for signature 'LinearVariableSum,numeric'
e1 / e2

## S4 method for signature 'LinearVariableCollection,LinearVariableCollection'
e1 + e2

## S4 method for signature 'LinearVariableCollection,LinearVariableCollection'
e1 - e2

## S4 method for signature 'LinearVariableCollection,numeric'
e1 * e2

## S4 method for signature 'numeric,LinearVariableCollection'
e1 * e2

## S4 method for signature 'LinearVariableCollection,ANY,ANY,missing'
x[i, j, ..., drop = TRUE]

Arguments

Value

Returns an object of type 'LinearVariableSum'

Returns an object of type 'LinearVariableSum'

Returns an object of type 'LinearVariableSum'

an object of type 'LinearVariableSum'

a new object of type 'LinearVariableCollection'

Slots

variables

a data frame hold the variable coefficients. One line for reach variable, row and column.

index_mapping

a function that takes a variable name as character and returns a mapping table that maps column ids to variable indexes.

variable

a linear variable collection with just one index '1'

constant

a numeric vector

variables

a variable collection

Examples

## Not run: 
# vectors create matrix rows
# x[1, 1]
# x[2, 1]
# x[3, 1]
x[1:3, 1]

# colwise() creates columns per row
# 1 * x[1, 1] + 2 * x[1, 2] + 3 * x[1, 3]
colwise(1, 2, 3) * x[1, colwise(1, 2, 3)]

# you can also combine the two
# x[1, 1]
# x[2, 1] + x[2, 2]
# x[3, 1] + x[3, 2] + x[3, 2]
x[1:3, colwise(1, 1:2, 1:3)]

## End(Not run)

Experimental: Create a new MILP Model

Description

Create an an empty mixed-integer linear programming model that is about 1000 times faster than 'MIPModel'.

Usage

MILPModel()

Details

Please only use it if you can deal with potential API changes in the future. When you use 'MILPModel' make sure to always model your problem with 'MIPModel' as well, just to make sure you get the same results.

It is also always a good idea to test your model with very small input sizes and examine the coefficients and rows of the constraint matrix.

Create a new MIP Model

Description

Create a new MIP Model

Usage

MIPModel()

Add a constraint

Description

Add one or more constraints to the model using quantifiers.

Usage

add_constraint(.model, .constraint_expr, ..., .show_progress_bar = TRUE)

add_constraint_(
  .model,
  .constraint_expr,
  ...,
  .dots,
  .show_progress_bar = TRUE
)

Arguments

Value

a Model with new constraints added

Examples

library(magrittr)
MIPModel() %>%
  add_variable(x[i], i = 1:5) %>%
  # creates 5 constraints
  add_constraint(x[i] >= 1, i = 1:5) %>%
  # you can also use filter expressions
  add_constraint(x[i] >= 1, i = 1:5, i %% 2 == 0) %>%
  # and depent on other indexes
  add_constraint(x[j] >= 1, i = 1:10, j = 1:i, j <= 5)

Add a variable to the model

Description

A variable can either be a name or an indexed name. See examples.

Usage

add_variable(.model, .variable, ..., type = "continuous", lb = -Inf, ub = Inf)

add_variable_(
  .model,
  .variable,
  ...,
  type = "continuous",
  lb = -Inf,
  ub = Inf,
  .dots
)

Arguments

Examples

library(magrittr)
MIPModel() %>%
  add_variable(x) %>% # creates 1 variable named x
  add_variable(y[i],
    i = 1:10, i %% 2 == 0,
    type = "binary"
  ) # creates 4 variables

Retrieve additional solver specific output

Description

Retrieve additional solver specific output

Usage

additional_solver_output(solution)

Arguments

Value

A list of named entries. What is in that list is determined by the solver function. For ompr.roi this is usually a solver specific message and status information.

As_colwise

Description

Convert lists or vectors to colwise semantic.

Usage

as_colwise(x)

Arguments

Format variables colwise

Description

This function should be used if you to expand a variable across columns and not rows. When passing a vector of indexes to MILPModel variable, it creates a new row for each vector element. With colwise you can create columns instead. Please see the examples below.

Usage

colwise(...)

Arguments

Details

'colwise' is probably the concept that is likely to change in the future.

Examples

## Not run: 
# vectors create matrix rows
# x[1, 1]
# x[2, 1]
# x[3, 1]
x[1:3, 1]

# colwise() creates columns per row
# 1 * x[1, 1] + 2 * x[1, 2] + 3 * x[1, 3]
colwise(1, 2, 3) * x[1, colwise(1, 2, 3)]

# or you have multiple rows and columns and different coefficients
# 1 * x[1, 1] + 2 * x[1, 2] + 3 * x[1, 3]
# 4 * x[2, 1] + 5 * x[2, 2] + 6 * x[1, 3]
colwise(1:6) * x[1:2, colwise(1:3)]
# in the example above, the colwise vector multiplied with the variable
# has an element per row and column
# in general, it can be a multiple of number of columns

# you can also combine the two
# x[1, 1]
# x[2, 1] + x[2, 2]
# x[3, 1] + x[3, 2] + x[3, 2]
x[1:3, colwise(1, 1:2, 1:3)]

## End(Not run)

Extract the constraint matrix, the right hand side and the sense from a model

Description

Extract the constraint matrix, the right hand side and the sense from a model

Usage

extract_constraints(model)

Arguments

Value

a list with three named elements. 'matrix' the (sparse) constraint matrix from the Matrix package. 'rhs' is the right hand side vector in the order of the matrix. 'sense' is a vector of the constraint senses

Examples

library(magrittr)
model <- MIPModel() %>%
  add_variable(x[i], i = 1:3) %>%
  add_variable(y[i], i = 1:3) %>%
  add_constraint(x[i] + y[i] <= 1, i = 1:3)
extract_constraints(model)

Gets the column duals of a solution

Description

Gets the column duals of a solution

Usage

get_column_duals(solution)

Arguments

Value

Either a numeric vector with one element per column or 'NA_real_'.

Examples

## Not run: 
result <- MIPModel() %>%
  add_variable(x[i], i = 1:5) %>%
  add_variable(y[i, j], i = 1:5, j = 1:5) %>%
  add_constraint(x[i] >= 1, i = 1:5) %>%
  set_bounds(x[i], lb = 3, i = 1:3) %>%
  set_objective(sum_over(i * x[i], i = 1:5)) %>%
  solve_model(with_ROI("glpk"))

get_column_duals(result)

## End(Not run)

Gets the row duals of a solution

Description

Gets the row duals of a solution

Usage

get_row_duals(solution)

Arguments

Value

Either a numeric vector with one element per row or 'NA_real_'.

Examples

## Not run: 
result <- MIPModel() %>%
  add_variable(x[i], i = 1:5) %>%
  add_variable(y[i, j], i = 1:5, j = 1:5) %>%
  add_constraint(x[i] >= 1, i = 1:5) %>%
  set_bounds(x[i], lb = 3, i = 1:3) %>%
  set_objective(sum_expr(i * x[i], i = 1:5)) %>%
  solve_model(with_ROI("glpk"))

get_row_duals(result)

## End(Not run)

Get variable values from a solution

Description

Get variable values from a solution

Usage

get_solution(solution, expr, type = "primal")

get_solution_(solution, expr, type = "primal")

Arguments

Value

a data.frame. One row for each variable instance and a column for each index. Unless it is a single variable, then it returns a single number. Please note that in case of a data.frame there is no guarantee about the ordering of the rows. This could change in future ompr versions. Please always use the indexes to retrieve the correct values.

Examples

## Not run: 
library(magrittr)
result <- MIPModel() %>%
  add_variable(x[i], i = 1:5) %>%
  add_variable(y[i, j], i = 1:5, j = 1:5) %>%
  add_constraint(x[i] >= 1, i = 1:5) %>%
  set_bounds(x[i], lb = 3, i = 1:3) %>%
  set_objective(0) %>%
  solve_model(with_ROI("glpk"))
solution <- get_solution(result, x[i])
solution2 <- get_solution(result, y[i, 1])
solution3 <- get_solution(result, y[i, j])
duals <- get_solution(result, x[i], type = "dual")

## End(Not run)

Number of variables (rows) of the model

Description

Number of variables (rows) of the model

Usage

nconstraints(model)

Arguments

Value

An integer equal to the number of variables. A variable is here a column in the resulting constraint matrix.

Examples

library(magrittr)
model <- MIPModel() %>%
  add_variable(x) %>%
  add_variable(y[i], i = 1:10)
nconstraints(model) # 11

Create a new solution

Description

This function/class should only be used if you develop your own solver.

Usage

new_solution(
  model,
  objective_value,
  status,
  solution,
  solution_column_duals = function() NA_real_,
  solution_row_duals = function() NA_real_,
  additional_solver_output = list()
)

Arguments

Number of variables of a model

Description

Number of variables of a model

Usage

nvars(model)

Arguments

Value

a list with three named elements. 'binary' => number of binary variables, 'integer' => number of integer variables, 'continuous' => number of continuous variables.

Examples

library(magrittr)
model <- MIPModel() %>%
  add_variable(x[i], i = 1:10, type = "binary") %>%
  add_variable(y[i], i = 1:5, type = "continuous") %>%
  add_variable(z[i], i = 1:2, type = "integer")
nvars(model)

Extract the objective function from a model

Description

Extract the objective function from a model

Usage

objective_function(model)

Arguments

Value

a list with two named elements, 'solution' and 'constant'. 'solution' is a sparse vector from the Matrix package. 'constant' is a constant that needs to be added to get the final obj. value.

Examples

library(magrittr)
model <- MIPModel() %>%
  add_variable(x[i], i = 1:5) %>%
  set_objective(sum_over(i * x[i], i = 1:5) + 10)
objective_function(model)

Extract the numerical objective value from a solution

Description

Extract the numerical objective value from a solution

Usage

objective_value(solution)

Arguments

Value

numeric single item vector

Set the bounds of a variable

Description

Change the lower and upper bounds of a named variable, indexed variable or a group of variables.

Usage

set_bounds(.model, .variable, ..., lb = NULL, ub = NULL)

set_bounds_(.model, .variable, ..., lb = NULL, ub = NULL, .dots)

Arguments

Examples

library(magrittr)
MIPModel() %>%
  add_variable(x[i], i = 1:5) %>%
  add_constraint(x[i] >= 1, i = 1:5) %>% # creates 5 constraints
  set_bounds(x[i], lb = 3, i = 1:3) %>%
  variable_bounds()

MIPModel() %>%
  add_variable(x[i], i = 1:5) %>%
  set_bounds(x[i] <= i, i = 1:5) %>% # upper bound
  set_bounds(x[i] >= 0, i = 1:5) %>% # lower bound
  set_bounds(x[5] == 45) %>%
  variable_bounds()

Set the model objective

Description

Set the model objective

Usage

set_objective(model, expression, sense = c("max", "min"))

set_objective_(model, expression, sense = c("max", "min"))

Arguments

Value

a Model with a new objective function definition

Examples

library(magrittr)
MIPModel() %>%
  add_variable(x, lb = 2) %>%
  add_variable(y, lb = 40) %>%
  set_objective(x + y, sense = "min")

Solve a model

Description

Solve a model

Usage

solve_model(model, solver)

Arguments

Value

solver(model)

Get the solver status from a solution

Description

Get the solver status from a solution

Usage

solver_status(solution)

Arguments

Value

character vector being either "infeasible", "optimal", "unbounded", "userlimit" or "error

Sum over indexes

Description

This functions helps to create summations over indexes.

Usage

sum_over(.expr, ...)

sum_expr(.expr, ...)

Arguments

Value

the sum over all the indexes

See Also

add_constraint

set_objective

Please note that sum_expr is deprecated when used together with MIPModel.

Examples

if (FALSE) {
  # create a sum from x_1 to x_10
  sum_over(x[i], i = 1:10)
  # create a sum from x_2 to x_10 with even indexes
  sum_over(x[i], i = 1:10, i %% 2 == 0)
  sum_over(x[i, j], i = 1:10, j = 1:i)
}

Variable lower and upper bounds of a model

Description

Variable lower and upper bounds of a model

Usage

variable_bounds(model)

Arguments

Value

a list with two components 'lower' and 'upper' each having a numeric vector of bounds. One for each variable.

Examples

library(magrittr)
model <- MIPModel() %>%
  add_variable(x, type = "binary") %>%
  add_variable(y, type = "continuous", lb = 2) %>%
  add_variable(z, type = "integer", ub = 3)
variable_bounds(model)

Get all unique names of the model variables

Description

Get all unique names of the model variables

Usage

variable_keys(model)

Arguments

Value

a character vector ordered in the same way as the constraint matrix columns and objective vector

Examples

library(magrittr)
model <- MIPModel() %>%
  add_variable(x[i], i = 1:3)
variable_keys(model)

Variable types of a model

Description

One component for each variable in the correct order

Usage

variable_types(model)

Arguments

Value

a factor with levels binary, continuous, integer

Examples

library(magrittr)
model <- MIPModel() %>%
  add_variable(x, type = "binary") %>%
  add_variable(y, type = "continuous") %>%
  add_variable(z, type = "integer")
variable_types(model)