% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_spatial_relations.R
\name{spatial_relations}
\alias{spatial_relations}
\title{Spatial relations infrastructure}
\description{
Define a unified internal representation for spatial relations between
planning units and provide constructors for building such relations from
common spatial inputs.

Spatial relations in \code{multiscape} are graph-like structures defined over
the set of planning units. They are used to represent adjacency, shared
boundary length, proximity, neighbourhood graphs, or other pairwise spatial
relationships that may later be used by objectives, constraints, or
diagnostics.

Relations are stored inside the \code{Problem} object as
\code{x$data$spatial_relations[[name]]}.
}
\details{
\strong{Internal representation}

Each spatial relation is stored as a \code{data.frame} containing, at a
minimum, the columns:
\describe{
\item{\code{internal_pu1}}{Integer index of the first planning unit.}
\item{\code{internal_pu2}}{Integer index of the second planning unit.}
\item{\code{weight}}{Non-negative edge weight. Its interpretation depends
on the relation type.}
}

Additional columns may also be present, such as \code{pu1}, \code{pu2},
\code{distance}, \code{source}, or other diagnostic fields. These extra
columns are preserved when possible.

Thus, a spatial relation can be interpreted as a weighted graph
\eqn{G = (\mathcal{I}, E, \omega)}, where:
\itemize{
\item \eqn{\mathcal{I}} is the set of planning units,
\item \eqn{E} is the set of stored edges,
\item \eqn{\omega_{ij} \ge 0} is the weight associated with edge
\eqn{(i,j)}.
}

\strong{Directed and undirected relations}

Some relation constructors create undirected relations by default. In that
case, each unordered pair is typically stored once, usually with
\eqn{i < j}, unless self-edges are explicitly allowed.

\strong{Boundary relations and diagonal terms}

The function \code{\link{add_spatial_boundary}} supports boundary-length
relations derived either from a boundary table or from polygon geometry.

If \code{include_self = TRUE}, diagonal entries \eqn{(i,i)} may be added to
represent exposed boundary. These diagonal weights are intended for
boundary-based compactness or fragmentation formulations, where perimeter
exposed to the outside of the selected solution should contribute to the
objective.

\strong{Geometry safety}

All \code{sf}-based constructors operate only through spatial predicates,
topological relations, or boundary-length calculations. They never subdivide,
cut, or alter planning-unit geometries. Planning units are aligned to the
internal planning-unit order before spatial relations are computed.

\strong{Available constructors}

The following functions build and register spatial relations:
\itemize{
\item \code{\link{add_spatial_relations}}: register a precomputed relation,
\item \code{\link{add_spatial_boundary}}: shared boundary length relation,
\item \code{\link{add_spatial_rook}}: rook adjacency from polygons,
\item \code{\link{add_spatial_queen}}: queen adjacency from polygons,
\item \code{\link{add_spatial_knn}}: k-nearest-neighbours graph from
coordinates,
\item \code{\link{add_spatial_distance}}: distance-threshold graph from
coordinates.
}
}
\keyword{internal}
