% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/paths.R
\name{k_shortest_paths}
\alias{k_shortest_paths}
\title{Find K Shortest Loopless Paths (Yen's Algorithm)}
\usage{
k_shortest_paths(x, from, to, k = 3, weights = NULL, directed = NULL, ...)
}
\arguments{
\item{x}{Network input: matrix, igraph, network, cograph_network, or tna object}

\item{from}{Character or numeric node identifier for the source node.}

\item{to}{Character or numeric node identifier for the target node.}

\item{k}{Integer; number of shortest paths to find. Default 3.}

\item{weights}{Edge weight handling: NULL (default) auto-detects from edge
attributes, NA forces unweighted distances, or a numeric vector of custom
weights.}

\item{directed}{Logical or NULL. If NULL (default), auto-detect from matrix
symmetry. Set TRUE to force directed, FALSE to force undirected.}

\item{...}{Additional arguments passed to \code{\link{to_igraph}}}
}
\value{
A list with class "cograph_k_paths" containing:
\describe{
\item{paths}{List of up to \code{k} character vectors, each containing node
names in path order}
\item{distances}{Numeric vector of path lengths (sum of edge weights or hop
count)}
\item{from}{Source node name}
\item{to}{Target node name}
\item{k}{Number of paths requested}
}
}
\description{
Computes up to \code{k} shortest loopless paths between two nodes using
Yen's algorithm. Each path is a sequence of distinct nodes from source to
target.
}
\details{
Yen's algorithm finds the k shortest loopless (simple) paths in a graph.
It works by:
\enumerate{
\item Finding the shortest path via Dijkstra's algorithm
\item For each subsequent path, systematically exploring deviations from
previously found paths by temporarily removing edges, finding spur paths,
and selecting the shortest candidate
}

The algorithm may return fewer than \code{k} paths if fewer distinct loopless
paths exist between the two nodes.
}
\examples{
# Find 3 shortest paths in a small network
adj <- matrix(c(
  0, 1, 1, 0, 0,
  0, 0, 1, 1, 0,
  0, 0, 0, 1, 1,
  0, 0, 0, 0, 1,
  0, 0, 0, 0, 0
), 5, 5, byrow = TRUE)
rownames(adj) <- colnames(adj) <- LETTERS[1:5]
kp <- cograph::k_shortest_paths(adj, from = "A", to = "E", k = 3)
kp

}
\references{
Yen, J.Y. (1971). Finding the K shortest loopless paths in a network.
\emph{Management Science}, 17(11), 712-716.
\doi{10.1287/mnsc.17.11.712}
}
\seealso{
\code{\link{shortest_paths}}
}
