% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arcopt_qn.R
\name{arcopt_qn}
\alias{arcopt_qn}
\title{Quasi-Newton ARC Optimizer}
\usage{
arcopt_qn(
  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 n).}

\item{fn}{Function that computes the objective function value.}

\item{gr}{Function that computes the gradient.}

\item{hess}{Optional Hessian function for hybrid mode. If provided,
initializes B_0 = H(x_0) and can refresh when approximation degrades.}

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

\item{lower}{Numeric vector of lower bounds (length n). Default: all -Inf.}

\item{upper}{Numeric vector of upper bounds (length n). Default: all Inf.}

\item{control}{List of control parameters (see Details).}
}
\value{
Same structure as \verb{\link{arcopt}}. The \code{diagnostics} sublist
gains four QN-specific counters in addition to the standard mode-
dispatch fields:
\itemize{
\item \code{qn_updates}: number of successful QN updates;
\item \code{qn_skips}: number of skipped updates (curvature condition failed);
\item \code{qn_restarts}: number of approximation restarts;
\item \code{qn_fd_refreshes}: number of FD Hessian refreshes performed
(hybrid mode only; 0 otherwise).
}

\code{qn_polish_switches}, \code{qn_polish_reverts}, and
\code{hess_evals_at_polish_switch} are always \code{0L}/\code{NA} for QN runs
(the polish mode is exact-Hessian only).
}
\description{
Minimizes a nonlinear objective function using Adaptive Regularization with
Cubics and quasi-Newton Hessian approximations. Does not require an exact
Hessian function.
}
\details{
The QN-ARC algorithm maintains a quasi-Newton Hessian approximation B_k
and solves the cubic regularization subproblem:
\deqn{m_k(s) = f_k + g_k^T s + 1/2 s^T B_k s + sigma_k/3 ||s||^3}
\subsection{Initialization of B_0}{

When \code{hess} is not supplied, \code{arcopt_qn()} seeds the initial Hessian
approximation with a one-time finite-difference Hessian computed from
the supplied gradient at \code{x0} (cost: \code{2 * length(x0)} gradient
evaluations once at startup). This provides negative-curvature
information that the pure-identity initialization used by classical
quasi-Newton methods would miss on saddle-prone problems. To opt out
and recover the identity-initialization convention, pass
\code{hess = function(x) diag(length(x))} explicitly.
}

\subsection{Control Parameters}{

In addition to standard arcopt controls:
\itemize{
\item \code{qn_method}: Update method (default: "hybrid"):
\itemize{
\item "hybrid": State-aware routing between SR1-first and BFGS-first
orderings based on the current B_k's eigenstructure and recent
rho_k values (see below). Includes automatic FD refresh of B_k
when SR1 is stuck. Recommended for saddle-prone problems.
\item "sr1": Symmetric Rank-1 (allows indefinite Hessians)
\item "bfgs": Standard BFGS (maintains positive definiteness)
}
\item \code{bfgs_tol}: Curvature tolerance for BFGS in hybrid mode (default: 1e-10)
\item \code{sr1_skip_tol}: SR1 skip test tolerance (default: 1e-8)
\item \code{sr1_restart_threshold}: Consecutive skips before restart (default: 5)
\item \code{use_accel_qn}: \strong{EXPERIMENTAL} Enable Nesterov acceleration (default:
FALSE). May improve convergence on strongly convex problems but can hurt
performance on nonconvex problems. Use with caution.
}
}

\subsection{Hybrid Routing Parameters}{

The \code{"hybrid"} method maintains an internal mode flag that starts in
\code{"indefinite"} (SR1-first priority) and promotes to \code{"pd"} (BFGS-first)
once the B_k approximation has been reliably positive definite and
cubic-model predictions have tracked the true objective:
\itemize{
\item \code{qn_route_demote_rho} (default 0.25): rho_k below this counts as a
"bad" step
\item \code{qn_route_promote_rho} (default 0.5): rho_k above this counts as a
"good" step
\item \code{qn_route_demote_k} (default 2): consecutive bad steps in "pd" mode
demote back to "indefinite"
\item \code{qn_route_promote_k} (default 3): consecutive good PD steps in
"indefinite" mode promote to "pd"
\item \code{qn_fd_refresh_k} (default 3): while in "indefinite" mode, this many
consecutive bad rho steps rebuild B_k from a fresh FD Hessian
\item \code{qn_stuck_refresh_k} (default 100): while in "indefinite" mode,
this many iterations without promoting also triggers an FD refresh
(safety net for secondary-saddle stalls)
}
}

\subsection{Trust-Region Fallback}{

All \verb{tr_fallback_*} and \verb{tr_*} control parameters from
\code{\link{arcopt}} are respected. In QN mode the flat-ridge detector
uses \code{lambda_min(B_k)} (the QN approximation's smallest eigenvalue)
as the ridge signal, consistent with the quantity the cubic subproblem
acts on. The ridge detector and the QN FD-refresh triggers are
mutually exclusive: the FD refresh fires only in \code{"indefinite"}
routing mode, while the ridge detector requires \code{lambda_min(B_k) > 0},
so both cannot fire on the same iteration. If the one-way switch to
trust-region mode occurs, subsequent iterations no longer update the
\code{indefinite}-mode counters (since they are gated on being in cubic
mode).
}
}
\keyword{internal}
