prioritizr: add_cbc_solver – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

add_cbc_solver

Add a CBC solver

Description

Specify that the CBC (COIN-OR branch and cut) software (Forrest & Lougee-Heimer 2005) 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 rcbc package to be installed (only available on GitHub, see below for installation instructions).

Usage

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

Arguments

`x`	`problem()` (i.e. `ConservationProblem`) object.
`gap`	`numeric` gap to optimality. This gap is relative and expresses the acceptable deviance from the optimal objective. 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` 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` attempt to simplify the problem before solving it? Defaults to `TRUE`.
`threads`	`integer` number of threads to use for the optimization algorithm. The default value is 1.
`first_feasible`	`logical` should the first feasible solution be be returned? If `first_feasible` is set to `TRUE`, the solver will return the first solution it encounters that meets all the constraints, regardless of solution quality. Note that the first feasible solution is not an arbitrary solution, rather it is derived from the relaxed solution, and is therefore often reasonably close to optimality. Defaults to `FALSE`.
`verbose`	`logical` should information be printed while solving optimization problems? Defaults to `TRUE`.

Details

CBC is an open-source mixed integer programming solver that is part of the Computational Infrastructure for Operations Research (COIN-OR) project. Although formal benchmarks examining the performance of this solver for conservation planning problems have yet to be completed, preliminary analyses suggest that it performs much faster than the other open-source solvers (i.e. add_rsymphony_solver(), add_rsymphony_solver()), and so we recommend using this solver if the Gurobi and IBM CPLEX solvers are unavailable.

Value

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

Installation

The rcbc package is required to use this solver. Since the rcbc package is not available on the the Comprehensive R Archive Network (CRAN), it must be installed from its GitHub repository. To install the rcbc package, please use the following code:

if (!require(remotes)) install.packages("remotes")
remotes::install_github("dirkschumacher/rcbc")

Note that you may also need to install several dependencies – such as the Rtools software or system libraries – prior to installing the rcbc package. For further details on installing this package, please consult official installation instructions for the package.

References

Forrest J and Lougee-Heimer R (2005) CBC User Guide. In Emerging theory, Methods, and Applications (pp. 257–277). INFORMS, Catonsville, MD. doi: 10.1287/educ.1053.0020.

Examples

## 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() %>%
  add_cbc_solver(gap = 0.1, verbose = FALSE)

# generate solution %>%
s <- solve(p)

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

## End(Not run)

prioritizr

Systematic Conservation Prioritization in R

v7.0.1

GPL-3

Authors

Jeffrey O Hanson [aut] (<https://orcid.org/0000-0002-4716-6134>), Richard Schuster [aut, cre] (<https://orcid.org/0000-0003-3191-7869>), Nina Morrell [aut], Matthew Strimas-Mackey [aut] (<https://orcid.org/0000-0001-8929-7776>), Matthew E Watts [aut], Peter Arcese [aut] (<https://orcid.org/0000-0002-8097-482X>), Joseph Bennett [aut] (<https://orcid.org/0000-0002-3901-9513>), Hugh P Possingham [aut] (<https://orcid.org/0000-0001-7755-996X>)

Initial release