Skip to contents

Add a CPLEX solver

Source: R/add_cplex_solver.R
add_cplex_solver.Rd

Specify that the IBM CPLEX software should be used to solve a conservation planning problem (IBM 2017) . This function can also be used to customize the behavior of the solver. It requires the cplexAPI package to be installed (see below for installation instructions).

Usage

add_cplex_solver(
  x,
  gap = 0.1,
  time_limit = .Machine$integer.max,
  presolve = TRUE,
  threads = 1,
  verbose = TRUE
)

Arguments

x

problem() or multi_problem() object.

gap

numeric value denoting the optimality gap. This gap is relative and expresses the acceptable deviance from optimality. For example, a value of 0.01 will result in the solver stopping when it has found a solution within 1% of optimality. Additionally, a value of 0 will result in the solver stopping when it has found an optimal solution. The default value is 0.1 (i.e., 10% from optimality).

time_limit

numeric value denoting the time limit (seconds) for generating solutions. The solver will return the current best solution when this time limit is exceeded. The default value is the largest integer value (i.e., .Machine$integer.max), effectively meaning that solver will keep running until a solution within the optimality gap is found.

presolve

logical value indicating if the optimization problem should be simplified before solving it? Defaults to TRUE.

threads

integer value denoting the number of threads to use during optimization. Broadly speaking, we recommend setting threads to be no higher than the number of computational cores minus one or two (e.g., threads = parallel::detectCores(TRUE) - 2). This is because setting threads to be equal to the number of computational cores means that the solver and is fighting for resources with other software (e.g., Dropbox, iCloud, OneDrive, software updates, antivirus software, internet browsers) and, in turn, can result in computational bottlenecks that slow run times. Additionally, when setting threads to be a value greater than 1, we recommend checking memory (RAM) usage during the optimization process to ensure that the solver does not use up the majority of available memory. This is because solving optimization problems with multiple threads can involve creating multiple copies of the problem (e.g., threads = 5 may mean 5 copies) and exhausting most of the available memory will drastically slow run times. Defaults to 1.

verbose

logical value indicating if information should be displayed during the optimization process. Defaults to TRUE.

Value

An updated problem() or multi_problem() object with the solver added to it.

Details

IBM CPLEX is a commercial optimization software. It is faster than the available open source solvers (e.g., add_lpsymphony_solver() and add_rsymphony_solver(). Although formal benchmarks examining the performance of this solver for conservation planning problems have yet to be completed, preliminary analyses suggest that it performs slightly slower than the Gurobi solver (i.e., add_gurobi_solver()). We recommend using this solver if the Gurobi solver is not available. Licenses are available for the IBM CPLEX software to academics at no cost (see https://www.ibm.com/products/ilog-cplex-optimization-studio/cplex-optimizer).

Installation

The cplexAPI package is used to interface with IBM CPLEX software. To install the package, the IBM CPLEX software must be installed (see https://www.ibm.com/products/ilog-cplex-optimization-studio/cplex-optimizer). Next, the CPLEX_BIN environmental variable must be set to specify the file path for the IBM CPLEX software. For example, on a Linux system, this variable can be specified by adding the following text to the ~/.bashrc file:

  export CPLEX_BIN="/opt/ibm/ILOG/CPLEX_Studio128/cplex/bin/x86-64_linux/cplex"

Please note that you may need to change the version number in the file path (i.e., "CPLEX_Studio128"). After specifying the CPLEX_BIN environmental variable, the cplexAPI package can be installed. Since the cplexAPI package is not available on the the Comprehensive R Archive Network (CRAN), it must be installed from its GitHub repository. To install the cplexAPI package, please use the following code:

if (!require(remotes)) install.packages("remotes")
remotes::install_github("cran/cplexAPI")

For further details on installing this package, please consult the installation instructions.

References

IBM (2017) IBM ILOG CPLEX Optimization Studio CPLEX User's Manual. Version 12 Release 8. IBM ILOG CPLEX Division, Incline Village, NV.

See also

Other functions for adding solvers: add_cbc_solver(), add_default_solver(), add_gurobi_solver(), add_highs_solver(), add_lsymphony_solver, add_rsymphony_solver()

Examples

# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()

# create problem
p <-
  problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1) %>%
  add_binary_decisions() %>%
  add_cplex_solver(gap = 0.1, time_limit = 5, verbose = FALSE)

# generate solution
s <- solve(p)

# plot solution
plot(s, main = "solution", axes = FALSE)