% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_action_max_per_pu.R
\name{add_action_max_per_pu}
\alias{add_action_max_per_pu}
\title{Limit the number of actions per planning unit (maximum)}
\arguments{
\item{x}{A \code{Problem} object created with \code{\link{create_problem}}. Must already contain actions (i.e., run
\code{\link{add_actions}} first).}

\item{max}{Integer scalar \eqn{\ge 0}. Maximum number of actions allowed per PU.
Default is \code{1L}.}

\item{pu}{Optional integer vector of planning unit ids (external ids, i.e.,
\code{x$data$pu$id}) to which the constraint is applied. If \code{NULL} (default),
the constraint applies to all PUs.}

\item{actions}{Optional character vector of action ids (i.e., \code{x$data$actions$id})
to include in the sum. If \code{NULL} (default), all actions are included.}

\item{overwrite}{Logical. If \code{TRUE}, replace any existing \code{action_max_per_pu}
constraint stored in \code{x$data$constraints}. If \code{FALSE} (default) and a constraint
already exists, an error is raised.}
}
\value{
The updated \code{Problem} object with \code{x$data$constraints$action_max_per_pu}
set to a list containing the constraint specification.
}
\description{
Store a constraint that limits the number of actions that can be selected within each
planning unit (PU). The constraint has the form:
\deqn{\sum_{a \in A} x_{pu,a} \le \mathrm{max}}
for each PU in the selected set.

This function is \strong{data-only}: it records the constraint specification in the
\code{Problem} object but does not build or modify the optimization model. The constraint
is later translated into linear constraints by the model builder (e.g.,
\code{.pa_build_model_apply_constraints()}).
}
\details{
The constraint can be applied to:
\itemize{
\item all planning units and all actions (default), or
\item a subset of planning units via \code{pu}, and/or
\item a subset of actions via \code{actions}.
}

Note that the subset is applied over the existing feasible \code{(pu, action)} pairs
in \code{x$data$dist_actions}. If the requested \code{pu}/\code{actions} subset yields
zero feasible pairs, the function stops with an informative error.

If \code{x$data$model_ptr} is already present (a model has been built previously),
the function marks the model as dirty by setting \code{x$data$meta$model_dirty <- TRUE},
signalling that the model should be rebuilt before solving.
}
\seealso{
\code{\link{add_actions}}
}
\keyword{internal}
