% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/problem-class.R
\name{problem-class}
\alias{problem-class}
\alias{Problem}
\title{Problem class}
\value{
No return value. This page documents the \code{Problem} class.
}
\description{
The \code{Problem} class is the central container used by \pkg{multiscape} to
represent a planning problem before, during, and after model construction.

A \code{Problem} object stores the full problem specification in a modular
way. This includes the baseline planning data, optional spatial metadata,
action definitions, effects, profit, targets, constraints, objective
registrations, solver settings, and, when available, a built optimization
model or model snapshot.

In other words, \code{Problem} is the persistent object that connects the full
\code{multiscape} workflow:
\preformatted{
create_problem()
-> add_*() / set_*()
-> solve()
}
}
\details{
\strong{Conceptual role}

The \code{Problem} class is designed for a data-first and modular workflow.
User-facing functions do not usually modify a solver object directly. Instead,
they enrich the \code{Problem} object by storing new specifications in its
internal \code{data} field.

Thus, a \code{Problem} object should be understood as a structured container
for the mathematical planning problem, not necessarily as a built
optimization model.

Before \code{\link{solve}} is called, the object may contain only input data
and user specifications. During or after solving, it may additionally contain
a built model pointer, model metadata, and solver-related information.

\strong{Core mathematical interpretation}

At a high level, the \code{Problem} object stores the ingredients required to
define an optimization problem over:
\itemize{
\item planning units \eqn{i \in \mathcal{P}},
\item features \eqn{f \in \mathcal{F}},
\item actions \eqn{a \in \mathcal{A}},
\item optional spatial relations over planning units,
\item and user-defined objectives and constraints.
}

The baseline ecological state is typically stored through a planning
unit--feature table of amounts:
\deqn{
a_{if} \ge 0,
}
where \eqn{a_{if}} is the baseline amount of feature \eqn{f} in planning unit
\eqn{i}.

Subsequent functions then add action feasibility, effects, profit, targets,
spatial relations, and optimization settings to this baseline representation.

\strong{How objects are created}

\code{Problem} objects are usually created by \code{\link{create_problem}}.

After creation, downstream functions such as \code{\link{add_actions}},
\code{\link{add_effects}}, \code{\link{add_profit}},
\code{\link{add_constraint_targets_absolute}}, \code{\link{add_constraint_targets_relative}},
spatial relation constructors, objective setters, and solver setters extend
the internal \code{data} list.

\strong{Internal storage}

The class contains a single field:
\describe{
\item{\code{data}}{A named \code{list} storing the full problem
specification, metadata, and, when available, built-model information.}
}

Common entries of \code{data} include:
\describe{
\item{\code{pu}}{Planning-unit table.}
\item{\code{features}}{Feature table.}
\item{\code{actions}}{Action catalog.}
\item{\code{dist_features}}{Planning unit--feature baseline amounts.}
\item{\code{dist_actions}}{Feasible planning unit--action pairs.}
\item{\code{dist_effects}}{Action effects by planning unit, action, and
feature.}
\item{\code{dist_profit}}{Profit by planning unit--action pair.}
\item{\code{pu_sf}}{Planning-unit geometry when available.}
\item{\code{pu_coords}}{Planning-unit coordinates when available.}
\item{\code{spatial_relations}}{Registered spatial relations.}
\item{\code{targets}}{Stored target specifications.}
\item{\code{constraints}}{Stored user-defined constraints.}
\item{\code{objectives}}{Registered atomic objectives for single- or
multi-objective workflows.}
\item{\code{method}}{Stored multi-objective method configuration, when
applicable.}
\item{\code{solve_args}}{Stored solver settings.}
\item{\code{model_ptr}}{Pointer to a built optimization model, when
available.}
\item{\code{model_args}}{Metadata describing model construction.}
\item{\code{model_list}}{Optional exported model snapshot or representation.}
\item{\code{meta}}{Auxiliary metadata, including model-dirty flags and other
bookkeeping fields.}
}

Not every \code{Problem} object contains all of these entries. The content of
\code{data} depends on how far the workflow has progressed.

\strong{Lifecycle}

A \code{Problem} object typically moves through the following stages:
\enumerate{
\item input stage: baseline planning units, features, and feature
distributions are stored,
\item specification stage: actions, effects, targets, objectives,
constraints, and spatial relations are added,
\item model stage: an optimization model is built from the stored
specification,
\item solve stage: the model is solved and results are returned in a
separate \code{Solution} or \code{SolutionSet} object.
}

The \code{Problem} object itself is not the solution. It is the structured
problem definition from which a solution can be obtained.
}
\section{Methods}{

\describe{
\item{\code{print()}}{Print a structured summary of the stored problem
specification, including data, actions and effects, spatial inputs, targets
and constraints, and model status. If a model has already been built,
additional dimensions and auxiliary-variable information are displayed.}

\item{\code{show()}}{Alias of \code{print()}.}

\item{\code{repr()}}{Return a short one-line representation of the object.}

\item{\code{getData(name)}}{Return a named entry from \code{self$data}.}

\item{\code{getPlanningUnitsAmount()}}{Return the number of planning units
stored in \code{x$data$pu}.}

\item{\code{getMonitoringCosts()}}{Return the planning-unit cost vector,
typically taken from \code{x$data$pu$cost}.}

\item{\code{getFeatureAmount()}}{Return the number of stored features.}

\item{\code{getFeatureNames()}}{Return feature names from
\code{x$data$features$name}, or feature ids if names are unavailable.}

\item{\code{getActionCosts()}}{Return action-level costs from
\code{x$data$dist_actions$cost} when available.}

\item{\code{getActionsAmount()}}{Return the number of stored actions.}
}
}

\section{Printing and diagnostics}{

The \code{print()} method is intended as a quick diagnostic summary. It helps
users understand:
\itemize{
\item what data have already been loaded,
\item whether actions, effects, spatial relations, targets, and constraints
have been registered,
\item whether objectives and methods have been configured,
\item whether a model has already been built,
\item and whether the object appears ready to be solved.
}

In particular, the model section of the printed output summarizes whether the
current problem specification is incomplete, ready, or already materialized as
a built optimization model.
}

\seealso{
\code{\link{create_problem}},
\code{\link{add_actions}},
\code{\link{add_effects}},
\code{\link{add_constraint_targets_absolute}},
\code{\link{solve}}
}
