% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_constraint_area.R
\name{add_constraint_area}
\alias{add_constraint_area}
\title{Add area constraint}
\usage{
add_constraint_area(
  x,
  area,
  sense,
  tolerance = 0,
  area_col = NULL,
  area_unit = c("m2", "ha", "km2"),
  actions = NULL,
  name = NULL
)
}
\arguments{
\item{x}{A \code{Problem} object.}

\item{area}{Numeric scalar greater than or equal to zero. Target value for
the constrained area.}

\item{sense}{Character string indicating the type of area constraint. Must be
one of \code{"min"}, \code{"max"}, or \code{"equal"}.}

\item{tolerance}{Numeric scalar greater than or equal to zero. Only used when
\code{sense = "equal"}. In that case, equality is interpreted as a band
around \code{area} with half-width \code{tolerance}. Ignored otherwise.}

\item{area_col}{Optional character string giving the name of the area column
in \code{x$data$pu}. If \code{NULL}, the area source is resolved later by
the model builder.}

\item{area_unit}{Character string indicating the unit of \code{area} and
\code{tolerance}. Must be one of \code{"m2"}, \code{"ha"}, or
\code{"km2"}.}

\item{actions}{Optional subset of actions to which the constraint applies.
If \code{NULL}, the constraint applies to the total selected area in the
problem through the planning-unit selection variables. Otherwise, it applies
to the selected decision variables associated with the specified subset of
actions. This argument is resolved using the package's standard action
subset parser.}

\item{name}{Optional character string used as the label of the stored linear
constraint when it is later added to the optimization model. If
\code{NULL}, a default name is generated.}
}
\value{
An updated \code{Problem} object with the new area-constraint
specification appended to \code{x$data$constraints$area}.
}
\description{
Add an area constraint to a planning problem.

This function stores one area-constraint specification in the
\code{Problem} object so that it can later be incorporated when the
optimization model is assembled. Multiple area constraints can be added by
calling this function repeatedly, provided that no duplicated combination of
action subset and constraint sense is introduced.
}
\details{
Use this function when area requirements must be imposed either on the total
selected landscape or on the subset of selected decisions associated with
specific actions.

Let \eqn{\mathcal{I}} denote the set of planning units and let
\eqn{a_i \ge 0} be the area associated with planning unit
\eqn{i \in \mathcal{I}}

When \code{actions = NULL}, the constraint refers to the total selected area
in the problem. In that case, let \eqn{w_i \in \{0,1\}} denote the binary
variable indicating whether planning unit \eqn{i} is selected by at least one
decision in the model.

Depending on \code{sense}, this function stores one of the following
constraints:

If \code{sense = "min"}:
\deqn{
\sum_{i \in \mathcal{I}} a_i w_i \ge A
}

If \code{sense = "max"}:
\deqn{
\sum_{i \in \mathcal{I}} a_i w_i \le A
}

If \code{sense = "equal"} and \code{tolerance = 0}:
\deqn{
\sum_{i \in \mathcal{I}} a_i w_i = A
}

If \code{sense = "equal"} and \code{tolerance > 0}, the equality is stored as
a two-sided band:
\deqn{
A - \tau \le \sum_{i \in \mathcal{I}} a_i w_i \le A + \tau
}
where \eqn{\tau} is the value supplied through \code{tolerance}.

When \code{actions} is not \code{NULL}, the constraint is applied only to the
selected decisions associated with the specified subset of actions. Let
\eqn{\mathcal{A}^\star \subseteq \mathcal{A}} denote that subset and let
\eqn{x_{ia} \in \{0,1\}} denote the binary variable indicating whether action
\eqn{a \in \mathcal{A}^\star} is selected in planning unit
\eqn{i \in \mathcal{I}}. In that case, the constrained quantity is
\deqn{
\sum_{i \in \mathcal{I}} \sum_{a \in \mathcal{A}^\star} a_i x_{ia}.
}

Under formulations where at most one action can be selected per planning
unit, this coincides with the area allocated to that subset of actions.

Areas are obtained from the planning-unit table. If \code{area_col} is
provided, that column is used. Otherwise, the model builder later determines
the default area source according to the internal rules of the package. The
value of \code{area_unit} indicates the unit in which \code{area} and
\code{tolerance} are expressed and therefore how the stored threshold should
be interpreted.

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

Multiple area constraints can be stored in a \code{Problem} object. However,
at most one can be stored for the same combination of action subset and
constraint sense. Attempting to add a duplicated
\code{actions}--\code{sense} combination results in an error.
}
\examples{
pu <- data.frame(
  id = 1:4,
  cost = c(2, 3, 1, 4),
  area_ha = c(10, 15, 8, 20)
)

features <- data.frame(
  id = 1:2,
  name = c("sp1", "sp2")
)

dist_features <- data.frame(
  pu = c(1, 1, 2, 3, 4, 4),
  feature = c(1, 2, 1, 2, 1, 2),
  amount = c(1, 2, 1, 3, 2, 1)
)

actions <- data.frame(
  id = c("conservation", "restoration")
)

p <- create_problem(
  pu = pu,
  features = features,
  dist_features = dist_features
)

p <- add_actions(
  p,
  actions = actions,
  cost = c(conservation = 1, restoration = 2)
)

p <- add_constraint_area(
  x = p,
  area = 25,
  sense = "min",
  area_col = "area_ha",
  area_unit = "ha"
)

p <- add_constraint_area(
  x = p,
  area = 15,
  sense = "max",
  area_col = "area_ha",
  area_unit = "ha",
  actions = "restoration"
)

p <- add_constraint_area(
  x = p,
  area = 5,
  sense = "min",
  area_col = "area_ha",
  area_unit = "ha",
  actions = "restoration"
)

p$data$constraints$area

}
\seealso{
\code{\link{create_problem}}
}
