R/solvers.R

In prioritizr: Systematic Conservation Prioritization in R

#' @include Solver-class.R
NULL

#' Add solvers
#'
#' Specify the software and settings used to solve a conservation planning
#' problem. By default, the best available
#' software currently installed on the system will be used.
#' For information on the performance of different solvers,
#' please see Hanson _et al._ (2025) and Schuster _et al._ (2020) for
#' benchmarks comparing run time and solution quality of these solvers.
#'
#' @details
#' The following functions can be used to add a solver to a
#' conservation planning [problem()]. Note that if multiple
#' of these functions are added to a [problem()], then only the last
#' function added will be used.
#'
#' \describe{
#'
#' \item{[add_default_solver()]}{
#' This solver uses the best software currently installed on the system.
#' }
#'
#' \item{[add_gurobi_solver()]}{
#' [*Gurobi*](https://www.gurobi.com/)
#' is a state-of-the-art commercial optimization software with an R package
#' interface. We recommend using this solver if at all possible.
#' It is by far the fastest of the solvers available for
#' generating prioritizations, however, it is not freely available. That
#' said, licenses are available to academics at no cost. The
#' \pkg{gurobi} package is distributed with the *Gurobi* software
#' suite. This solver uses the \pkg{gurobi} package to solve problems.
#' }
#'
#' \item{[add_cplex_solver()]}{
#' [*IBM CPLEX*](https://www.ibm.com/products/ilog-cplex-optimization-studio/cplex-optimizer)
#' is a commercial optimization software. It is faster than the open
#' source solvers available for generating prioritizations, however, it
#' is not freely available.
#' Similar to the [*Gurobi*](https://www.gurobi.com/)
#' software, licenses are available to academics at no cost.
#' This solver uses the \pkg{cplexAPI} package to solve problems using
#' *IBM CPLEX*.
#' }
#'
#' \item{[add_cbc_solver()]}{
#' [*CBC*](https://github.com/coin-or/Cbc) is an
#' open-source mixed integer programming solver that is part of the
#' Computational Infrastructure for Operations Research (COIN-OR) project.
#' Preliminary benchmarks indicate that it is the fastest open source
#' solver currently supported.
#' We recommend using this solver if both *Gurobi* and *IBM CPLEX* are
#' unavailable.
#' It requires the \pkg{rcbc} package, which is currently only available on
#' [GitHub](https://github.com/dirkschumacher/rcbc).
#' }
#'
#' \item{[add_highs_solver()]}{
#' [*HiGHS*](https://highs.dev/) is an open
#' source optimization software. Although this solver can have
#' comparable performance to the *CBC* solver for particular problems and is
#' generally faster than the *SYMPHONY* based solvers (see below), it
#' sometimes can take much longer than the *CBC* solver for particular
#' problems.
#' }
#'
#' \item{[add_lpsymphony_solver()]}{
#' [*SYMPHONY*](https://github.com/coin-or/SYMPHONY) is an
#' open-source mixed integer programming solver that is also part of the
#' COIN-OR project. Although both *SYMPHONY* and *CBC* are part of
#' the COIN-OR project, they are different software.
#' The \pkg{lpsymphony} package provides an interface to the *SYMPHONY*
#' software, and is distributed through
#' [Bioconductor](https://doi.org/doi:10.18129/B9.bioc.lpsymphony).
#' We recommend using this solver if the *CBC* and *HiGHS* solvers cannot
#' be installed.
#' This solver can use parallel processing to solve problems, so it is
#' faster than \pkg{Rsymphony} package interface (see below).
#' }
#'
#' \item{[add_rsymphony_solver()]}{
#' This solver provides an alternative interface to the
#' [*SYMPHONY*](https://github.com/coin-or/SYMPHONY) solver using
#' the \pkg{Rsymphony} package.
#' It is not recommended to use this solver because it has the slowest
#' performance.
#' }
#'
#' }
#'
#' @name solvers
#'
#' @family overviews
#'
#' @references
#' Hanson JO, Schuster R, Strimas-Mackey M, Morrell N, Edwards BPM, Arcese P,
#' Bennett JR, and Possingham HP (2025). Systematic conservation prioritization
#' with the prioritizr R package. *Conservation Biology*, 39: e14376.
#'
#' Schuster R, Hanson JO, Strimas-Mackey M, and Bennett JR (2020). Exact
#' integer linear programming solvers outperform simulated annealing for
#' solving conservation planning problems. *PeerJ*, 8: e9258.
#'
#' @examples
#' \dontrun{
#' # load data
#' sim_pu_raster <- get_sim_pu_raster()
#' sim_features <- get_sim_features()
#'
#' # create basic problem
#' p <-
#'   problem(sim_pu_raster, sim_features) %>%
#'   add_min_set_objective() %>%
#'   add_relative_targets(0.1) %>%
#'   add_proportion_decisions()
#'
#' # create vector to store plot names
#' n <- c()
#'
#' # create empty list to store solutions
#' s <- c()
#'
#' # if gurobi is installed: create problem with added gurobi solver
#' if (require("gurobi")) {
#'   p1 <- p %>% add_gurobi_solver(verbose = FALSE)
#'   n <- c(n, "gurobi")
#'   s <- c(s, solve(p1))
#' }
#'
#' # if cplexAPI is installed: create problem with added CPLEX solver
#' if (require("cplexAPI")) {
#'   p2 <- p %>% add_cplex_solver(verbose = FALSE)
#'   n <- c(n, "CPLEX")
#'   s <- c(s, solve(p2))
#' }
#'
#' # if rcbc is installed: create problem with added CBC solver
#' if (require("rcbc")) {
#'   p3 <- p %>% add_cbc_solver(verbose = FALSE)
#'   n <- c(n, "CBC")
#'   s <- c(s, solve(p3))
#' }
#'
#' # if highs is installed: create problem with added HiGHs solver
#' if (require("highs")) {
#'   p4 <- p %>% add_highs_solver(verbose = FALSE)
#'   n <- c(n, "HiGHS")
#'   s <- c(s, solve(p4))
#' }
#'
#' # create problem with added rsymphony solver
#' if (require("Rsymphony")) {
#'   p5 <- p %>% add_rsymphony_solver(verbose = FALSE)
#'   n <- c(n, "Rsymphony")
#'   s <- c(s, solve(p5))
#' }
#'
#' # if lpsymphony is installed: create problem with added lpsymphony solver
#' if (require("lpsymphony")) {
#'   p6 <- p %>% add_lpsymphony_solver(verbose = FALSE)
#'   n <- c(n, "lpsymphony")
#'   s <- c(s, solve(p6))
#' }
#'
#' # plot solutions
#' names(s) <- n
#' plot(terra::rast(s), axes = FALSE)
#' }
#'
NULL