% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/optimize_model.R
\name{estimate_model_rcpp}
\alias{estimate_model_rcpp}
\title{Estimate factor model using R-based optimization}
\usage{
estimate_model_rcpp(
  model_system,
  data,
  init_params = NULL,
  control = NULL,
  optimizer = "nlminb",
  parallel = TRUE,
  verbose = TRUE,
  max_restarts = 5,
  factor_scores = NULL,
  factor_ses = NULL,
  factor_vars = NULL,
  init_factor_scores = NULL,
  checkpoint_file = NULL
)
}
\arguments{
\item{model_system}{A model_system object from define_model_system()}

\item{data}{Data frame containing all variables}

\item{init_params}{Initial parameter values (optional)}

\item{control}{Estimation control object from define_estimation_control()}

\item{optimizer}{Optimizer to use (default "nloptr"):
\itemize{
\item \code{"nloptr"} - L-BFGS via nloptr (gradient only, no Hessian)
\item \code{"optim"} - L-BFGS-B via stats::optim (gradient only, no Hessian)
\item \code{"nlminb"} - Uses analytical gradient AND Hessian (more efficient!)
\item \code{"trust"} - Trust region method with analytical Hessian (requires trustOptim package)
}}

\item{parallel}{Whether to use parallel computation (default TRUE)}

\item{verbose}{Whether to print progress (default TRUE)}

\item{max_restarts}{Maximum number of eigenvector-based restarts for escaping
saddle points (default 5). Set to 0 to disable.}

\item{factor_scores}{Matrix (n_obs x n_factors) of factor score estimates from
a previous stage. Used for adaptive quadrature. (default NULL)}

\item{factor_ses}{Matrix (n_obs x n_factors) of factor score standard errors
from a previous stage. Used for adaptive quadrature. (default NULL)}

\item{factor_vars}{Named numeric vector of factor variances from a previous
stage. Used for adaptive quadrature. (default NULL)}

\item{init_factor_scores}{Matrix (n_obs x n_factors) of factor scores to use
for initializing factor loadings. When provided, loadings are estimated by
treating factor scores as regressors, giving better starting values than
the default (0.5). Useful for two-stage estimation where Stage 1 factor
scores can improve Stage 2 initialization. (default NULL)}

\item{checkpoint_file}{Path to file for saving checkpoint parameters during
optimization. When specified, parameters are saved each time the Hessian is
evaluated at a point with improved likelihood. Useful for long-running
estimations that may need to be restarted. The file contains parameter names
and values as CSV with metadata headers. (default NULL = no checkpointing)}
}
\value{
List with parameter estimates, standard errors, log-likelihood, etc.
}
\description{
This function estimates a factor model by optimizing the likelihood using
C++ for fast evaluation and R for optimization and parallelization.
}
\details{
For maximum efficiency, use \code{optimizer = "nlminb"} or \code{optimizer = "trust"}
which exploit the analytical Hessian computed in C++. The default L-BFGS methods
only use the gradient and approximate the Hessian from gradient history.

When optimization fails to converge (possibly at a saddle point), the function
will attempt to escape by moving in the direction of negative Hessian eigenvalues.
This is controlled by the \code{max_restarts} parameter.
}
\examples{
\donttest{
# Simulate a simple one-factor model with two linear indicators
set.seed(1); n <- 100
f <- rnorm(n)
dat <- data.frame(intercept = 1,
  y1 = 1.0 * f + rnorm(n, 0, 0.5),
  y2 = 0.8 * f + rnorm(n, 0, 0.5))
fm <- define_factor_model(n_factors = 1)
mc1 <- define_model_component("m1", dat, "y1", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = 1)
mc2 <- define_model_component("m2", dat, "y2", fm,
  covariates = "intercept", model_type = "linear",
  loading_normalization = NA_real_)
ms <- define_model_system(components = list(mc1, mc2), factor = fm)
ctrl <- define_estimation_control(n_quad_points = 8, num_cores = 1)
result <- estimate_model_rcpp(ms, dat, control = ctrl,
  optimizer = "nlminb", parallel = FALSE, verbose = FALSE)
result$estimates
}
}
