#' @include Solver-class.R
NULL
#' Add solvers
#'
#' Specify the software and configuration 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 Schuster _et al._ (2020) for benchmarks comparing the
#' run time and solution quality of some of these solvers when applied to
#' different sized datasets.
#'
#' @details The following solvers can be used to find solutions for a
#' conservation planning [problem()]:
#'
#' \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.
#' Unlike other solvers, the \pkg{Rsymphony} package can be installed
#' directly from the Comprehensive R Archive Network (CRAN).
#' It is also the slowest of the available solvers.}
#'
#' }
#'
#' @name solvers
#'
#' @family overviews
#'
#' @references
#' 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
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.