% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/RcppExports.R
\name{.rotate_cf_orth}
\alias{.rotate_cf_orth}
\title{Orthogonal Crawford-Ferguson factor rotation}
\usage{
.rotate_cf_orth(
  L,
  kappa,
  eps = 1e-05,
  normalize = TRUE,
  random_starts = 0L,
  maxit = 1000L,
  max_line_search = 10L,
  step0 = 1,
  screen_keep = 5L,
  triage_maxit = 25L,
  triage_improve_tol = 0
)
}
\arguments{
\item{L}{Numeric matrix. The unrotated loading matrix (variables by factors).}

\item{kappa}{Numeric scalar in \verb{[0, 1]}. The Crawford-Ferguson parameter.}

\item{eps}{Numeric scalar. Convergence tolerance for the projected-gradient norm.}

\item{normalize}{Logical scalar. If \code{TRUE}, apply Kaiser normalization before
rotation and reverse it afterwards.}

\item{random_starts}{Integer scalar. Number of additional random orthogonal starts.}

\item{maxit}{Integer scalar. Maximum number of projected-gradient updates.}

\item{max_line_search}{Integer scalar. Maximum number of step-halving attempts after
the initial trial step in each line-search phase.}

\item{step0}{Numeric scalar. Initial step size used in the projected-gradient update.}

\item{screen_keep}{Integer scalar. Number of screened random starts retained for
triage optimization.}

\item{triage_maxit}{Integer scalar. Number of short optimization iterations used in
the triage stage.}

\item{triage_improve_tol}{Numeric scalar. Relative improvement required for a triaged
start to be promoted to full optimization.}
}
\value{
A named list with the rotated loadings, the orthogonal rotation matrix \code{Th}
(with \code{L \%*\% Th} reproducing the rotated loadings), the attained criterion value, and
the convergence and validity flags. The list additionally reports the
criterion value reached at each optimized start in \code{all_values}, with a per-start convergence flag in \code{all_converged}.
}
\description{
Rotate a loading matrix orthogonally under the Crawford-Ferguson criterion using a
gradient-projection optimizer along the orthogonal (Stiefel) manifold.
}
\details{
The criterion value \code{f} and its gradient \code{dQ/dL} at the rotated loadings
\code{L = A \%*\% T} define the search; the engine maps the gradient to the orthogonal
transformation \code{T}, projects it onto the tangent space, performs a
non-monotone line search, and retracts back onto the orthogonal group via a
polar (singular value) projection. \code{kappa = 0} is the quartimax criterion and
\code{kappa = ncol(A) / (2 * nrow(A))} is the equamax criterion.

Additional random orthogonal starts may be requested. To bound runtime the solver
screens each random start by its objective, runs a short triage optimization on the
best-screened starts, and fully optimizes only those that improve on the current
incumbent by at least \code{triage_improve_tol}.
}
\references{
Bernaards, C. A., & Jennrich, R. I. (2005). Gradient projection algorithms and
software for arbitrary rotation criteria in factor analysis. \emph{Educational and
Psychological Measurement}, 65, 676-696.

Crawford, C. B., & Ferguson, G. A. (1970). A general rotation criterion and its use
in orthogonal rotation. \emph{Psychometrika}, 35, 321-332.
}
\keyword{internal}
