add_cbc_solver {prioritizr} | R Documentation |
Add a CBC solver
Description
Specify that the CBC (COIN-OR branch and cut) software should be used to solve a conservation planning problem (Forrest & Lougee-Heimer 2005). 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,
start_solution = NULL,
verbose = TRUE
)
Arguments
x |
|
gap |
|
time_limit |
|
presolve |
|
threads |
|
first_feasible |
|
start_solution |
|
verbose |
|
Details
CBC is an
open-source mixed integer programming solver that is part of the
Computational Infrastructure for Operations Research (COIN-OR) project.
This solver seems to have much better performance than the other open-source
solvers (i.e., add_highs_solver()
, add_rsymphony_solver()
,
add_lpsymphony_solver()
)
(see the Solver benchmarks vignette for details).
As such, it is strongly recommended to use this solver if the Gurobi and
IBM CPLEX solvers are not available.
Value
An updated problem()
object 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 the online package documentation.
Start solution format
Broadly speaking, the argument to start_solution
must be in the same
format as the planning unit data in the argument to x
.
Further details on the correct format are listed separately
for each of the different planning unit data formats:
x
hasnumeric
planning unitsThe argument to
start_solution
must be anumeric
vector with each element corresponding to a different planning unit. It should have the same number of planning units as those in the argument tox
. Additionally, any planning units missing cost (NA
) values should also have missing (NA
) values in the argument tostart_solution
.x
hasmatrix
planning unitsThe argument to
start_solution
must be amatrix
vector with each row corresponding to a different planning unit, and each column correspond to a different management zone. It should have the same number of planning units and zones as those in the argument tox
. Additionally, any planning units missing cost (NA
) values for a particular zone should also have a missing (NA
) values in the argument tostart_solution
.x
hasterra::rast()
planning unitsThe argument to
start_solution
be aterra::rast()
object where different grid cells (pixels) correspond to different planning units and layers correspond to a different management zones. It should have the same dimensionality (rows, columns, layers), resolution, extent, and coordinate reference system as the planning units in the argument tox
. Additionally, any planning units missing cost (NA
) values for a particular zone should also have missing (NA
) values in the argument tostart_solution
.x
hasdata.frame
planning unitsThe argument to
start_solution
must be adata.frame
with each column corresponding to a different zone, each row corresponding to a different planning unit, and cell values corresponding to the solution value. This means that if adata.frame
object containing the solution also contains additional columns, then these columns will need to be subsetted prior to using this function (see below for example withsf::sf()
data). Additionally, any planning units missing cost (NA
) values for a particular zone should also have missing (NA
) values in the argument tostart_solution
.x
hassf::sf()
planning unitsThe argument to
start_solution
must be asf::sf()
object with each column corresponding to a different zone, each row corresponding to a different planning unit, and cell values corresponding to the solution value. This means that if thesf::sf()
object containing the solution also contains additional columns, then these columns will need to be subsetted prior to using this function (see below for example). Additionally, the argument tostart_solution
must also have the same coordinate reference system as the planning unit data. Furthermore, any planning units missing cost (NA
) values for a particular zone should also have missing (NA
) values in the argument tostart_solution
.
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.
See Also
Other solvers:
add_cplex_solver()
,
add_default_solver()
,
add_gurobi_solver()
,
add_highs_solver()
,
add_lsymphony_solver
,
add_rsymphony_solver()
Examples
## Not run:
# load data
sim_pu_raster <- get_sim_pu_raster()
sim_features <- get_sim_features()
# create problem
p1 <-
problem(sim_pu_raster, sim_features) %>%
add_min_set_objective() %>%
add_relative_targets(0.1) %>%
add_binary_decisions() %>%
add_cbc_solver(gap = 0, verbose = FALSE)
# generate solution %>%
s1 <- solve(p1)
# plot solution
plot(s1, main = "solution", axes = FALSE)
# create a similar problem with boundary length penalties and
# specify the solution from the previous run as a starting solution
p2 <-
problem(sim_pu_raster, sim_features) %>%
add_min_set_objective() %>%
add_relative_targets(0.1) %>%
add_boundary_penalties(10) %>%
add_binary_decisions() %>%
add_cbc_solver(gap = 0, start_solution = s1, verbose = FALSE)
# generate solution
s2 <- solve(p2)
# plot solution
plot(s2, main = "solution with boundary penalties", axes = FALSE)
## End(Not run)