add_constraint_budget: Add budget constraint

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

Add budget constraint

Description

Add a budget constraint to a planning problem.

This function stores one budget-constraint specification in the Problem object so that it can later be incorporated when the optimization model is assembled. Multiple budget constraints can be added by calling this function repeatedly, provided that no duplicated combination of action subset and constraint sense is introduced.

Usage

add_constraint_budget(
  x,
  budget,
  sense,
  tolerance = 0,
  actions = NULL,
  include_pu_cost = TRUE,
  include_action_cost = TRUE,
  name = NULL
)

Arguments

x	A Problem object.
budget	Numeric scalar greater than or equal to zero. Target value for the constrained budget.
sense	Character string indicating the type of budget constraint. Must be one of "min", "max", or "equal".
tolerance	Numeric scalar greater than or equal to zero. Only used when sense = "equal". In that case, equality is interpreted as a band around budget with half-width tolerance. Ignored otherwise.
actions	Optional subset of actions to which the constraint applies. If NULL, the constraint applies to the whole problem. Otherwise, it applies only to the selected decision variables associated with the specified subset of actions. This argument is resolved using the package's standard action subset parser.
include_pu_cost	Logical scalar indicating whether planning-unit costs should be included in the constrained budget. This is only supported when actions = NULL.
include_action_cost	Logical scalar indicating whether action costs should be included in the constrained budget.
name	Optional character string used as the label of the stored linear constraint when it is later added to the optimization model. If NULL, a default name is generated.

Details

Calls accumulate constraints for distinct action scopes, cost components, or senses. Repeating the same combination raises an error, even with a different threshold or name. To change it, rebuild from the problem before the constraint was added. Explicit names must be unique within the budget-constraint family; omitted names are generated automatically.

Use this function when spending limits or minimum spending requirements must be imposed either on the full problem or on the subset of selected decisions associated with specific actions.

Let \mathcal{I} denote the set of planning units and let \mathcal{A} denote the set of actions. Let w_i \in \{0,1\} denote the binary variable indicating whether planning unit i \in \mathcal{I} is selected by at least one decision in the model, and let x_{ia} \in \{0,1\} denote the binary variable indicating whether action a \in \mathcal{A} is selected in planning unit i \in \mathcal{I}.

The total constrained budget can include two cost components:

• planning-unit costs, associated with w_i;

• action costs, associated with x_{ia}.

The arguments include_pu_cost and include_action_cost determine which of these components are included in the stored budget constraint.

When actions = NULL, the constraint refers to the total budget across the whole problem. In that case, depending on the values of include_pu_cost and include_action_cost, the constrained quantity is one of the following:

If only planning-unit costs are included:

\sum_{i \in \mathcal{I}} c_i^{pu} w_i

If only action costs are included:

\sum_{i \in \mathcal{I}} \sum_{a \in \mathcal{A}} c_{ia}^{act} x_{ia}

If both components are included:

\sum_{i \in \mathcal{I}} c_i^{pu} w_i + \sum_{i \in \mathcal{I}} \sum_{a \in \mathcal{A}} c_{ia}^{act} x_{ia}

Depending on sense, this function stores one of the following constraints:

If sense = "min":

C \ge B

If sense = "max":

C \le B

If sense = "equal" and tolerance = 0:

C = B

If sense = "equal" and tolerance > 0, the equality is stored as a two-sided band:

B - \tau \le C \le B + \tau

where C denotes the selected cost expression and \tau is the value supplied through tolerance.

When actions is not NULL, only action costs can be included. In that case, let \mathcal{A}^\star \subseteq \mathcal{A} denote the selected subset of actions, and the constrained quantity is

\sum_{i \in \mathcal{I}} \sum_{a \in \mathcal{A}^\star} c_{ia}^{act} x_{ia}.

Action-specific budget constraints only support action costs. Therefore, include_pu_cost = TRUE is only allowed when actions = NULL, because planning-unit costs are not action-specific.

This function only stores the constraint specification; it does not validate the feasibility of the threshold against the available cost data at this stage.

Multiple budget constraints can be stored in a Problem object. However, at most one can be stored for the same combination of action subset and constraint sense. Attempting to add a duplicated actions–sense combination results in an error.

Value

An updated Problem object with the new budget-constraint specification appended to the stored budget-constraint table.

See Also

create_problem

Examples

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

p <- create_problem(
  pu = example_data$planning_units,
  features = example_data$features,
  dist_features = example_data$dist_features,
  cost = "cost"
) |>
  add_actions(
    example_data$actions,
    cost = example_data$action_costs
  )

p <- add_constraint_budget(
  x = p,
  budget = 10,
  sense = "max",
  include_pu_cost = TRUE,
  include_action_cost = TRUE
)

p <- add_constraint_budget(
  x = p,
  budget = 4,
  sense = "max",
  actions = "restore",
  include_pu_cost = FALSE,
  include_action_cost = TRUE
)

p <- add_constraint_budget(
  x = p,
  budget = 1,
  sense = "min",
  actions = "restore",
  include_pu_cost = FALSE,
  include_action_cost = TRUE
)

p$data$constraints$budget

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