% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_objectives.R
\name{add_objective_min_cost}
\alias{add_objective_min_cost}
\title{Add objective: minimize cost}
\usage{
add_objective_min_cost(
  x,
  include_pu_cost = TRUE,
  include_action_cost = TRUE,
  actions = NULL,
  alias = NULL
)
}
\arguments{
\item{x}{A \code{Problem} object.}

\item{include_pu_cost}{Logical. If \code{TRUE}, include planning-unit costs
in the objective.}

\item{include_action_cost}{Logical. If \code{TRUE}, include action costs in
the objective.}

\item{actions}{Optional subset of actions to include in the action-cost
component. Values may match \code{x$data$actions$id} and, if present,
\code{x$data$actions$action_set}. If \code{NULL}, all feasible actions are
included in the action-cost term.}

\item{alias}{Optional identifier used to register this objective for
multi-objective workflows.}
}
\value{
An updated \code{Problem} object.
}
\description{
Define an objective that minimizes the total cost of the solution.

Depending on the function arguments, the objective may include planning-unit
costs, action costs, or both. Action costs can optionally be restricted to a
subset of actions.
}
\details{
Use this function when the planning problem is framed primarily as a
cost-minimization problem, with costs arising from planning-unit selection,
action implementation, or both.

Let \eqn{\mathcal{I}} be the set of planning units and let
\eqn{\mathcal{D} \subseteq \mathcal{I} \times \mathcal{A}} denote the set of
feasible planning unit--action decisions.

Let:
\itemize{
\item \eqn{w_i \in \{0,1\}} denote whether planning unit \eqn{i} is
selected,
\item \eqn{x_{ia} \in \{0,1\}} denote whether action \eqn{a} is selected
in planning unit \eqn{i},
\item \eqn{c_i^{PU} \ge 0} denote the planning-unit cost of unit \eqn{i},
\item \eqn{c_{ia}^{A} \ge 0} denote the cost of selecting action
\eqn{a} in planning unit \eqn{i}.
}

The most general form of this objective is:

\deqn{
\min \left(
\sum_{i \in \mathcal{I}} c_i^{PU} w_i
+
\sum_{(i,a) \in \mathcal{D}^{\star}} c_{ia}^{A} x_{ia}
\right),
}

where \eqn{\mathcal{D}^{\star}} denotes the subset of feasible decisions
whose action contributes to the action-cost term.

If \code{include_pu_cost = FALSE}, the planning-unit cost term is omitted.

If \code{include_action_cost = FALSE}, the action-cost term is omitted.

If \code{actions = NULL}, all feasible actions contribute to the action-cost
term. If \code{actions} is supplied, only the selected subset contributes to
that term. Planning-unit costs are never subset by \code{actions}; they are
always global whenever \code{include_pu_cost = TRUE}.
}
\examples{
pu_tbl <- data.frame(
  id = 1:4,
  cost = c(1, 2, 3, 4)
)
feat_tbl <- data.frame(
  id = 1:2,
  name = c("feature_1", "feature_2")
)
dist_feat_tbl <- data.frame(
  pu = c(1, 1, 2, 3, 4),
  feature = c(1, 2, 2, 1, 2),
  amount = c(5, 2, 3, 4, 1)
)
actions_df <- data.frame(
  id = c("conservation", "restoration"),
  name = c("conservation", "restoration")
)

p <- create_problem(
  pu = pu_tbl,
  features = feat_tbl,
  dist_features = dist_feat_tbl,
  cost = "cost"
) |>
  add_actions(actions_df, cost = c(conservation = 1, restoration = 2))

p1 <- add_objective_min_cost(p)
p1$data$model_args

p2 <- add_objective_min_cost(
  p,
  include_pu_cost = FALSE,
  include_action_cost = TRUE
)
p2$data$model_args

p3 <- add_objective_min_cost(
  p,
  actions = "restoration"
)
p3$data$model_args

}
\seealso{
\code{\link{add_objective_max_profit}},
\code{\link{add_objective_max_net_profit}}
}
