add_cplex_solver: Add a CPLEX solver

Description

Specify that the IBM CPLEX software should be used to solve a conservation planning problem. This function can also be used to customize the behavior of the solver. It requires the cplexAPI package.

Usage

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

Arguments

problem() (i.e. '>ConservationProblem) object.

gap

numeric gap to optimality. This gap is relative when solving problems using Gurobi or CPLEX, and will cause the optimizer to terminate when the difference between the upper and lower objective function bounds is less than the gap times the upper bound. For example, a value of 0.01 will result in the optimizer stopping when the difference between the bounds is 1 percent of the upper bound.

time_limit

numeric time limit in seconds to run the optimizer. The solver will return the current best solution when this time limit is exceeded.

presolve

logical should the presolver be used to simplify the problem before solving it? The default value is TRUE.

threads

integer number of threads to use for the optimization algorithm. The default value of 1 will result in only one thread being used.

verbose

logical should information be printed while solving optimization problems?

Value

Object (i.e. '>ConservationProblem) with the solver added to it.

Details

IBM CPLEX is a commercial optimization software. Although this software is faster than the available open source solvers (i.e add_lpsymphony_solver() and add_rsymphony_solver(), it is slower than the Gurobi solver (add_gurobi_solver()). Licenses are available for the IBM CPLEX software to academics at no cost (see https://www.ibm.com/products/ilog-cplex-optimization-studio).

The pkgcplexAPI package is used to interface with IBM CPLEX. To install this package, the CPLEX_BIN variable must be set (similar to the GUROBI_HOME variable for the Gurobi software) to specify the file path for the CPLEX software. For example, on a Linux system, this variable can be specified by adding export CPLEX_BIN="/opt/ibm/ILOG/CPLEX_Studio128/cplex/bin/x86-64_linux/cplex" to the ~/.bashrc file. Note that you may need to change the version number in the file parth (i.e. "CPLEX_Studio128"). For more information on installing the pkgcplexAPI package, please see the official installation instructions for the package.

Examples

Run this code

# NOT RUN {
# load data
data(sim_pu_raster, sim_features)

# create problem
p <- problem(sim_pu_raster, sim_features) %>%
  add_min_set_objective() %>%
  add_relative_targets(0.1) %>%
  add_binary_decisions()
# }
# NOT RUN {
# if the package is installed then add solver and generate solution
if (require("cplexAPI")) {
  # specify solver and generate solution
  s <- p %>% add_cplex_solver(gap = 0.1, time_limit = 5) %>%
             solve()

  # plot solutions
  plot(stack(sim_pu_raster, s), main = c("planning units", "solution"),
       axes = FALSE, box = FALSE)
}
# }