% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eigen.R
\name{dominant_eigen}
\alias{dominant_eigen}
\title{Dominant eigen-elements of a population projection matrix}
\usage{
dominant_eigen(A, tol = 1e-12, ensure_positive = TRUE)
}
\arguments{
\item{A}{A square numeric matrix.}

\item{tol}{Numeric tolerance passed to \code{\link{stable_stage}} and
\code{\link{reproductive_values}}.}

\item{ensure_positive}{Logical. Passed to \code{\link{stable_stage}} and
\code{\link{reproductive_values}}. If \code{TRUE}, attempts to orient eigenvectors
so entries are mostly positive by flipping sign if needed.}
}
\value{
A named list with elements:
\itemize{
  \item \code{lambda}: spectral radius of \code{A}
  \item \code{w}: stable stage distribution (right eigenvector), \code{sum(w)=1}
  \item \code{v}: reproductive values (left eigenvector), \code{sum(v*w)=1}
}
}
\description{
Returns the dominant eigenvalue and its associated right/left eigenvectors
(stable stage distribution \code{w} and reproductive values \code{v}) for a square
population projection matrix \code{A}.
}
\details{
The output is normalized using the conventions in \code{\link{stable_stage}} and
\code{\link{reproductive_values}}:
\itemize{
  \item \code{w} is scaled so that \code{sum(w) = 1}
  \item \code{v} is scaled so that \code{sum(v * w) = 1}
}
}
\examples{
A <- matrix(c(
  0,   1,   2,
  0.5, 0,   0,
  0,   0.8, 0.9
), nrow = 3, byrow = TRUE)

dom <- dominant_eigen(A)
dom$lambda
sum(dom$w)
sum(dom$v * dom$w)

}
\references{
Caswell, H. (2001). \emph{Matrix population models: construction, analysis and
interpretation} (2nd ed.). Sinauer.
}
\seealso{
\code{\link{spectral_radius}}, \code{\link{stable_stage}},
\code{\link{reproductive_values}}
}
