% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arcopt.R
\name{arcopt}
\alias{arcopt}
\title{Adaptive Regularization using Cubics Optimizer}
\usage{
arcopt(
  x0,
  fn,
  gr,
  hess = NULL,
  ...,
  lower = rep(-Inf, length(x0)),
  upper = rep(Inf, length(x0)),
  control = list()
)
}
\arguments{
\item{x0}{Numeric vector of initial parameter values (length Q).}

\item{fn}{Function that computes the objective function value. Should take
a numeric vector of length Q and return a scalar.}

\item{gr}{Function that computes the gradient. Should take a numeric
vector of length Q and return a numeric vector of length Q. Required.}

\item{hess}{Function that computes the Hessian matrix. Should take a
numeric vector of length Q and return a Q-by-Q symmetric matrix.
Required (unless \code{control$use_qn = TRUE}; see Details).}

\item{...}{Additional arguments passed to \code{fn}, \code{gr}, and \code{hess}.}

\item{lower}{Numeric vector of lower bounds (length Q). Use \code{-Inf} for
unbounded parameters. Default: all \code{-Inf}.}

\item{upper}{Numeric vector of upper bounds (length Q). Use \code{Inf} for
unbounded parameters. Default: all \code{Inf}.}

\item{control}{A named list of control parameters. The user-facing
tolerances and switches are documented below; advanced regularization
tuning, the trust-region fallback, and the quasi-Newton polish mode
live on a separate help page (see \verb{\link{arcopt_advanced_controls}}).
Recognized entries:
\describe{
\item{\code{maxit}}{Maximum number of iterations (default \code{1000}).}
\item{\code{gtol_abs}}{Absolute gradient-norm tolerance for convergence
(default \code{1e-5}).}
\item{\code{ftol_abs}}{Absolute objective-value tolerance (default
\code{1e-8}).}
\item{\code{xtol_abs}}{Absolute step-size tolerance (default \code{1e-8}).}
\item{\code{trace}}{Integer in \code{0:3}. Depth of per-iteration data captured
into \code{result$trace}: \code{0} collects nothing, \code{1} (the default)
collects function value and gradient norm, \code{2} adds sigma, rho,
step type and reciprocal Hessian condition number, \code{3} adds the
full iterate, step, Hessian and convergence-criterion record.
This flag controls \emph{saved} data only -- for live console output
see \code{verbose}.}
\item{\code{verbose}}{Logical. If \code{TRUE}, prints one line per iteration
to the console showing iteration number, objective value,
\verb{||g||_inf}, ratio rho, regularization scale, and active solver
mode (default \code{FALSE}). Orthogonal to \code{trace}.}
\item{\code{use_qn}}{Logical. If \code{TRUE}, route to the quasi-Newton ARC
variant, which approximates the Hessian via SR1/BFGS updates and
does not require an analytic \code{hess} function. See the
advanced-controls page for QN-specific parameters (default
\code{FALSE}).}
}
See \verb{\link{arcopt_advanced_controls}} for the full set of advanced
tuning parameters governing the cubic regularization, the trust-region
fallback, and the quasi-Newton polish mode.}
}
\value{
A list with components:
\itemize{
\item \code{par}: Optimal parameter vector.
\item \code{value}: Objective value at \code{par}.
\item \code{gradient}: Gradient at \code{par}.
\item \code{hessian}: Hessian at \code{par} (or the final BFGS approximation if the
run ended in qn_polish mode).
\item \code{sigma}: Final cubic regularization parameter.
\item \code{converged}: Logical; whether convergence criteria were met.
\item \code{iterations}: Number of iterations performed.
\item \code{evaluations}: Named list of \code{fn}, \code{gr}, and \code{hess} evaluation counts.
\item \code{message}: Convergence reason.
\item \code{trace}: Per-iteration trace data (depth controlled by
\code{control$trace}); \code{NULL} when \code{trace = 0}.
\item \code{diagnostics}: Sublist of internal mode-dispatch diagnostics --
\code{solver_mode_final}, \code{ridge_switches}, \code{radius_final},
\code{qn_polish_switches}, \code{qn_polish_reverts}, and
\code{hess_evals_at_polish_switch}. See \verb{\link{arcopt_advanced_controls}}
for the meaning of each field. Most users do not need to inspect
this; it is preserved for diagnostic and benchmarking use.
}
}
\description{
Minimizes a nonlinear objective function using Adaptive Regularization with
Cubics (ARC). Designed for robust optimization of ill-conditioned, nonconvex,
and indefinite Hessian problems common in statistical applications.
}
\details{
The ARC algorithm iteratively minimizes a cubic regularization model:
\deqn{m_k(s) = f_k + g_k^\top s + \frac{1}{2} s^\top H_k s +
  \frac{\sigma_k}{3} \|s\|^3}
where \eqn{\sigma_k} is adapted from observed model accuracy. arcopt
may transparently fall back to a trust-region subproblem in flat-ridge
regimes and (optionally, opt-in) to a line-search BFGS polish in the
quadratic attraction basin. The transitions are observable via
\code{result$diagnostics}; the algorithmic details and tunable thresholds
are documented under \verb{\link{arcopt_advanced_controls}}.
\subsection{Hessian Requirement}{

arcopt is Hessian-centric: an analytic \code{hess} function is strongly
recommended. If the analytic form is unavailable, set
\code{control$use_qn = TRUE} to obtain Hessian-free quasi-Newton updates
(see the advanced-controls page).
}
}
\examples{
\donttest{
# Rosenbrock function
rosenbrock <- function(x) (1 - x[1])^2 + 100 * (x[2] - x[1]^2)^2

rosenbrock_gr <- function(x) {
  c(-2 * (1 - x[1]) - 400 * x[1] * (x[2] - x[1]^2),
    200 * (x[2] - x[1]^2))
}

rosenbrock_hess <- function(x) {
  matrix(c(
    1200 * x[1]^2 - 400 * x[2] + 2, -400 * x[1],
    -400 * x[1], 200
  ), 2, 2)
}

result <- arcopt(
  x0 = c(-1.2, 1),
  fn = rosenbrock,
  gr = rosenbrock_gr,
  hess = rosenbrock_hess
)

print(result$par)      # Should be near c(1, 1)
print(result$value)    # Should be near 0
}
}
\seealso{
\code{\link{arcopt_advanced_controls}} for advanced tuning of
the cubic regularization, trust-region fallback, and quasi-Newton
polish mode.
}
