Add constraint to a restoration problem (`restopt_problem()`

) object
to specify that certain planning units cannot be selected
for restoration activities.

## Arguments

- problem
`restopt_problem()`

Restoration problem object.- data
`terra::rast()`

or`terra::vect()`

Either a raster object containing binary values hat indicate which planning units cannot be selected for any restoration (i.e., cells with a value equal one are locked out from the solution), or a vector object whose features correspond to the locked out areas. See the function`add_available_areas_constraint()`

to get a locked out constraint from allowed restoration areas.- touches
`logical`

If the locked out data is a vector, define wether the rasterization must include all pixels touching the polygons. (see`terra::rasterize()`

). Useless if the data is raster data.

## Value

An updated restoration problem (`restopt_problem()`

) object.

## Details

Locked out constraints can be used to incorporate a wide range of
criteria into restoration planning problems.
They can be used to account for existing land-use practices,
feasibility of restoration activities, and stakeholder preferences.
For example, locked out constraints can be used to
ensure that urban areas are not selected for restoration.
Additionally, if restoration activities can only be implemented depending
on certain conditions -- such as places where landscape slope is not
too steep -- then locked out constraints could be used to ensure
restoration activities are not prioritized for places where they
could not be implemented.
Furthermore, if stakeholders require solutions that do not prioritize
particular places for restoration, then locked out constraints
can also be used to achieve this.
See `add_available_areas_constraint()`

, which achieve the same as the locked
out constraint by defining areas that ARE available for restoration.

## See also

Other constraints:
`add_available_areas_constraint()`

,
`add_compactness_constraint()`

,
`add_components_constraint()`

,
`add_connected_constraint()`

,
`add_min_iic_constraint()`

,
`add_min_mesh_constraint()`

,
`add_restorable_constraint()`

## Examples

```
# \donttest{
# load data
habitat_data <- rast(
system.file("extdata", "habitat_hi_res.tif", package = "restoptr")
)
locked_out_data <- rast(
system.file("extdata", "locked_out.tif", package = "restoptr")
)
# plot data
plot(rast(list(habitat_data, locked_out_data)), nc = 2)
# create problem with locked out constraints
p <- restopt_problem(
existing_habitat = habitat_data,
aggregation_factor = 16,
habitat_threshold = 0.7
) %>%
set_max_iic_objective() %>%
add_restorable_constraint(
min_restore = 5,
max_restore = 5,
) %>%
add_locked_out_constraint(data = locked_out_data) %>%
add_settings(time_limit = 1)
# print problem
print(p)
#> -----------------------------------------------------------------
#> Restopt
#> -----------------------------------------------------------------
#> original habitat: habitat_hi_res.tif
#> aggregation factor: 16
#> habitat threshold: 0.7
#> existing habitat: in memory
#> restorable habitat: in memory
#> -----------------------------------------------------------------
#> objective: Maximize integral index of connectivity
#> -----------------------------------------------------------------
#> constraints:
#> - restorable (min_restore = 5, max_restore = 5, min_proportion = 1, unit = ha)
#> - locked out (data = in memory)
#> -----------------------------------------------------------------
#> settings:
#> - precision = 4
#> - time_limit = 1
#> - nb_solutions = 1
#> - optimality_gap = 0
#> - solution_name_prefix = Solution
#> -----------------------------------------------------------------
# solve problem
s <- solve(p)
#> Note: The current solution is the best that the solver could find within the time limit. However, the solver had not enough to prove whether it is optimal or not. Consider increasing the time limit if you need a better solution (solving time = 1.05 s)
# plot solution
plot(s)
# }
```