add_constraint_locked_planning_units: Add locked planning units to a problem

In multiscape: Multi-Action, Multi-Objective Spatial Planning

Add locked planning units to a problem

Description

Define planning units that must be included in, or excluded from, the optimization problem.

This function updates the planning-unit table stored in the Problem object by creating or replacing the logical columns locked_in and locked_out. These columns are later used by the model builder when translating the problem into optimization constraints.

Lock information may be supplied either directly as logical vectors, as vectors of planning-unit ids, or by referencing columns in the raw planning-unit data originally passed to create_problem.

Usage

add_constraint_locked_planning_units(x, locked_in = NULL, locked_out = NULL)

Arguments

x	A Problem object created with create_problem.
locked_in	Optional locked-in specification. It may be NULL, a column name in the raw planning-unit data, a logical vector, or a vector of planning-unit ids.
locked_out	Optional locked-out specification. It may be NULL, a column name in the raw planning-unit data, a logical vector, or a vector of planning-unit ids.

Details

Use this function when whole planning units must be forced into or out of the solution, regardless of which action may later be selected in them.

Let \mathcal{I} denote the set of planning units and let w_i \in \{0,1\} denote the binary variable indicating whether planning unit i \in \mathcal{I} is selected by the model.

This function defines two subsets:

• \mathcal{I}^{in} \subseteq \mathcal{I}, the planning units that must be included,

• \mathcal{I}^{out} \subseteq \mathcal{I}, the planning units that must be excluded.

Conceptually, these sets correspond to the following conditions:

• if i \in \mathcal{I}^{in}, then w_i = 1,

• if i \in \mathcal{I}^{out}, then w_i = 0.

These constraints are not imposed immediately by this function; instead, they are stored in the planning-unit table and enforced later when building the optimization model.

Philosophy

The role of create_problem is to construct and normalize the basic inputs of the planning problem. Locking planning units is treated as a separate modelling step so that users can define or revise selection restrictions after the Problem object has already been created.

In contrast, add_constraint_locked_actions is used to fix specific feasible (pu, action) decisions rather than whole planning units.

Supported input formats

For both locked_in and locked_out, the function accepts:

• NULL, meaning that no planning units are locked on that side,

• a single character string, interpreted as a column name in the raw planning-unit data,

• a logical vector of length nrow(pu),

• a vector of planning-unit ids.

When a column name is supplied, the referenced column is coerced to logical. Numeric values are interpreted as non-zero = TRUE; character and factor values are interpreted using common logical strings such as "true", "t", "1", "yes", and "y". Missing values are treated as FALSE.

Repeated calls

Calls accumulate compatible locks and preserve omitted arguments. Repeating the same lock is idempotent. A planning unit cannot be locked in after it was locked out, or vice versa. Conflicts with existing action locks are also rejected. To change a lock, rebuild from the problem before it was added.

Consistency checks

The function checks that no planning unit is simultaneously assigned to both locked_in and locked_out. If such conflicts are found, an error is raised.

Value

An updated Problem object in which the planning-unit table contains logical columns locked_in and locked_out.

See Also

create_problem, add_actions, add_constraint_locked_actions, add_constraint_locked_pu

Examples

# Load a complete simulated planning problem.
example_data <- load_sim_multiaction()

pu <- example_data$planning_units
pu$lock_col <- pu$id %in% c(1, 4)
pu$out_col <- pu$id == 5

p <- create_problem(
  pu = pu,
  features = example_data$features,
  dist_features = example_data$dist_features,
  cost = "cost"
)

# 1) Lock by planning-unit ids
p1 <- add_constraint_locked_planning_units(
  x = p,
  locked_in = c(1, 3),
  locked_out = c(5)
)

p1$data$pu[, c("id", "locked_in", "locked_out")]

# 2) Read lock information from raw planning-unit data columns
p2 <- add_constraint_locked_planning_units(
  x = p,
  locked_in = "lock_col",
  locked_out = "out_col"
)

p2$data$pu[, c("id", "locked_in", "locked_out")]

# 3) Use logical vectors
p3 <- add_constraint_locked_planning_units(
  x = p,
  locked_in = pu$id %in% c(1, 3),
  locked_out = pu$id == 4
)

p3$data$pu[, c("id", "locked_in", "locked_out")]

multiscape documentation built on Oct. 12, 2026, 5:08 p.m.