% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_solution.R
\name{get_pu}
\alias{get_pu}
\title{Get planning-unit results from a solution}
\usage{
get_pu(x, only_selected = FALSE, run = NULL)
}
\arguments{
\item{x}{A \code{Solution} or \code{SolutionSet} object returned by
\code{\link{solve}}.}

\item{only_selected}{Logical. If \code{TRUE}, return only rows where
\code{selected == 1}. Default is \code{FALSE}.}

\item{run}{Optional positive integer giving the run index to extract from a
\code{SolutionSet}. If \code{NULL}, all runs are returned when available.}
}
\value{
A \code{data.frame} containing the stored planning-unit summary.
Typical columns include planning-unit identifiers, optional labels, and a
\code{selected} indicator.
}
\description{
Extract the planning-unit summary table from a \code{Solution} or
\code{SolutionSet} object returned by \code{\link{solve}}.

The returned table summarizes solution values at the planning-unit level and
typically includes a \code{selected} indicator showing whether each planning
unit is selected in the solution.
}
\details{
This function reads the planning-unit summary stored in
\code{x$summary$pu}. It does not reconstruct the table from the raw decision
vector; it simply returns the stored summary after optional filtering.

Let \eqn{w_i} denote the planning-unit selection variable for planning unit
\eqn{i}. In standard \code{multiscape} workflows, the \code{selected} column is the
user-facing representation of that planning-unit decision, typically coded as
\code{0} or \code{1}.

If \code{x} is a \code{SolutionSet} and \code{run} is provided, only rows
belonging to that run are returned. This requires the summary table to
contain a \code{run_id} column.

If \code{only_selected = TRUE}, only rows with \code{selected == 1} are
returned. This requires the summary table to contain a \code{selected}
column.

This function is intended for user-facing inspection of planning-unit results.
For the raw model variable vector, use \code{\link{get_solution_vector}}.
}
\examples{
\donttest{
if (requireNamespace("rcbc", quietly = TRUE)) {
  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 = "conservation",
    name = "conservation"
  )

  effects_df <- data.frame(
    pu = c(1, 2, 3, 4),
    action = "conservation",
    feature = c(1, 1, 2, 2),
    benefit = c(2, 1, 1, 2),
    loss = c(0, 0, 0, 0)
  )

  p <- create_problem(
    pu = pu_tbl,
    features = feat_tbl,
    dist_features = dist_feat_tbl,
    cost = "cost"
  ) |>
    add_actions(actions_df, cost = 0) |>
    add_effects(effects_df) |>
    add_constraint_targets_relative(0.2) |>
    add_objective_min_cost() |>
    set_solver_cbc(time_limit = 10)

  sol <- solve(p)

  get_pu(sol)
  get_pu(sol, only_selected = TRUE)
}
}
}
\seealso{
\code{\link{get_actions}},
\code{\link{get_features}},
\code{\link{get_targets}},
\code{\link{get_solution_vector}}
}
