% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_objectives.R
\name{register_atomic_objective_internal}
\alias{register_atomic_objective_internal}
\title{Register an atomic objective (internal)}
\arguments{
\item{x}{A \code{Problem} object.}

\item{alias}{Optional character scalar used to register the objective as an
atomic objective. If \code{NULL}, no registration entry is created.}

\item{objective_id}{Character string giving the stable internal identifier of
the objective, for example \code{"min_cost"} or \code{"max_benefit"}.}

\item{model_type}{Character string giving the model-builder label associated
with this objective, for example \code{"minimizeCosts"}.}

\item{objective_args}{A list of objective-specific arguments to be stored with
the objective definition.}

\item{sense}{Character string giving the optimization direction. Must be
either \code{"min"} or \code{"max"}.}
}
\value{
An updated \code{Problem} object.
}
\description{
Internal helper used by objective setter functions to define the active
single-objective configuration of a \code{Problem} object and, optionally,
register that objective as an atomic objective for multi-objective workflows.
}
\details{
In \code{multiscape}, an \emph{atomic objective} is a fully specified
objective definition that can later be reused by a multi-objective method
such as a weighted-sum formulation, an \eqn{\epsilon}-constraint method,
AUGMECON, or other objective-orchestration procedures.

Each atomic objective is identified by:
\itemize{
\item a stable internal identifier \code{objective_id},
\item a solver-facing model label \code{model_type},
\item a list of objective-specific arguments stored in
\code{objective_args},
\item an optimization sense, either \code{"min"} or \code{"max"},
\item and, optionally, a user-facing identifier \code{alias}.
}

If \code{alias} is not \code{NULL}, the objective is stored in
\code{x$data$objectives[[alias]]}. This makes it possible to refer to the
same objective later by a stable user-facing name. For example, a user may
register objectives under aliases such as \code{"cost"},
\code{"benefit"}, or \code{"frag"} and then pass those aliases to a
multi-objective method.

If \code{alias} is \code{NULL}, no atomic-objective entry is created in
\code{x$data$objectives}. In that case, the calling function still defines
the currently active single-objective configuration through
\code{x$data$model_args}, but no reusable multi-objective registration is
created.

Thus, this helper supports two complementary modes:
\itemize{
\item \strong{single-objective mode}: only the active objective is stored,
\item \strong{multi-objective-ready mode}: the active objective is stored
and also registered under an alias for later reuse.
}

Conceptually, if an objective function is denoted by \eqn{f(x)}, this helper
does not itself define the mathematical form of \eqn{f}; rather, it stores
the metadata required so that downstream code can reconstruct the correct
objective expression, its direction of optimization, and its user-visible
identity.
}
\keyword{internal}
