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).

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

- 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`

.- start_solution
`NULL`

or object containing the starting solution for the solver. Defaults to`NULL`

such that no starting solution is used. To specify a starting solution, the argument to`start_solution`

should be in the same format as the planning units (i.e., a`NULL`

,`numeric`

,`matrix`

,`data.frame`

,`Raster`

,`Spatial`

, or`sf::sf()`

object). See the Start solution format section for more information.- verbose
`logical`

should information be printed while solving optimization problems? Defaults to`TRUE`

.

Object (i.e., `ConservationProblem`

) with the solver
added to it.

*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.

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.

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`

has`numeric`

planning unitsThe argument to

`start_solution`

must be a`numeric`

vector with each element corresponding to a different planning unit. It should have the same number of planning units as those in the argument to`x`

. Additionally, any planning units missing cost (`NA`

) values should also have missing (`NA`

) values in the argument to`start_solution`

.`x`

has`matrix`

planning unitsThe argument to

`start_solution`

must be a`matrix`

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 to`x`

. Additionally, any planning units missing cost (`NA`

) values for a particular zone should also have a missing (`NA`

) values in the argument to`start_solution`

.`x`

has`Raster`

planning unitsThe argument to

`start_solution`

be a`Raster`

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 to`x`

. Additionally, any planning units missing cost (`NA`

) values for a particular zone should also have missing (`NA`

) values in the argument to`start_solution`

.`x`

has`data.frame`

planning unitsThe argument to

`start_solution`

must be a`data.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 a`data.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 with`sf::sf()`

data). Additionally, any planning units missing cost (`NA`

) values for a particular zone should also have missing (`NA`

) values in the argument to`start_solution`

.`x`

has`Spatial`

planning unitsThe argument to

`start_solution`

must be a`Spatial`

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 the`Spatial`

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 with`sf::sf()`

data). Additionally, the argument to`start_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 to`start_solution`

.`x`

has`sf::sf()`

planning unitsThe argument to

`start_solution`

must be a`sf::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 the`sf::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 to`start_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 to`start_solution`

.

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 solvers for an overview of all functions for adding a solver.

Other solvers:
`add_cplex_solver()`

,
`add_default_solver()`

,
`add_gurobi_solver()`

,
`add_lsymphony_solver`

,
`add_rsymphony_solver()`

```
# \dontrun{
# 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, verbose = FALSE)
# generate solution %>%
s <- solve(p)
# plot solution
plot(s, main = "solution", axes = FALSE, box = 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 = s, verbose = FALSE)
# generate solution
s2 <- solve(p2)
# plot solution
plot(s2, main = "solution with boundary penalties", axes = FALSE,
box = FALSE)
# }
```