% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arcopt_advanced_controls.R
\name{arcopt_advanced_controls}
\alias{arcopt_advanced_controls}
\title{Advanced Control Parameters for arcopt}
\description{
The main \code{\link{arcopt}} help page documents only the user-facing
tolerances and switches (\code{maxit}, \code{gtol_abs}, \code{ftol_abs}, \code{xtol_abs},
\code{trace}, \code{verbose}, \code{use_qn}). This page documents every other entry
that the \code{control} list of \code{arcopt()} (and the routed-to
\code{arcopt:::arcopt_qn()} variant) recognizes, organized by the
subsystem each parameter governs.
}
\section{Cubic regularization}{

These parameters control the adaptive cubic model
\eqn{m_k(s) = f_k + g_k^\top s + \tfrac{1}{2} s^\top H_k s +
\tfrac{\sigma_k}{3} \|s\|^3} and the sigma adaptation rule (Algorithm
2a/2b of \code{design/pseudocode.qmd}).
\describe{
\item{\code{sigma0}}{Initial regularization parameter (default \code{1.0}).}
\item{\code{sigma_min}}{Floor on \code{sigma_k} (default \code{1e-6}). Prevents the
cubic term from vanishing entirely on flat regions.}
\item{\code{sigma_max}}{Ceiling on \code{sigma_k} (default \code{1e12}). Triggers
emergency-stop behavior when reached.}
\item{\code{eta1}}{Step-acceptance threshold; steps with \eqn{\rho_k \ge
    \texttt{eta1}} are accepted (default \code{0.1}).}
\item{\code{eta2}}{Very-successful threshold; \eqn{\rho_k \ge
    \texttt{eta2}} triggers \code{sigma} shrinkage (default \code{0.9}).}
\item{\code{gamma1}}{Multiplicative shrink factor on a very-successful
step (default \code{0.5}).}
\item{\code{gamma2}}{Multiplicative grow factor on an unsuccessful step
(default \code{2.0}).}
}
}

\section{Trust-region fallback (cubic to TR on flat-ridge detection)}{

Cubic regularization can stagnate in "flat-ridge" regimes -- iterations
with the regularization floor pinned, model predictions matching the
objective (\eqn{\rho \approx 1}), gradient stalling, and a Hessian
that is positive-definite but nearly singular. This is outside the
local-error-bound condition of Yue, Zhou & So (2018) under which
cubic regularization is guaranteed to converge quadratically at
degenerate minimizers. arcopt detects the regime and switches once
from the cubic subproblem to a trust-region subproblem.
\describe{
\item{\code{tr_fallback_enabled}}{One-way cubic to TR switch
(default \code{TRUE}).}
\item{\code{tr_fallback_window}}{Sliding-window length for the detector
(default \code{10}).}
\item{\code{tr_fallback_tol_ridge}}{\code{lambda_min(H)} threshold defining a
"near-singular PD" Hessian (default \code{1e-3}).}
\item{\code{tr_fallback_rho_tol}}{Tolerance on \verb{|rho - 1|} for the
"near-perfect model" signal (default \code{0.1}).}
\item{\code{tr_fallback_grad_decrease_max}}{Ratio of latest to oldest
\verb{||g||_inf} above which the gradient counts as stagnant
(default \code{0.9}).}
\item{\code{tr_fallback_g_inf_floor}}{Absolute lower bound on \verb{||g||_inf}
below which the switch will not fire -- keeps the hybrid from
triggering at true local minima (default \code{1e-6}).}
\item{\code{tr_r0}}{Initial trust-region radius at the switch
(default \code{1.0}).}
\item{\code{tr_rmax}}{Maximum trust-region radius (default \code{100}).}
\item{\code{tr_eta1}}{TR step-acceptance threshold (default \code{0.25}).}
\item{\code{tr_eta2}}{TR expansion threshold (default \code{0.75}).}
\item{\code{tr_gamma_shrink}}{Radius shrink factor on a poor step
(default \code{0.25}).}
\item{\code{tr_gamma_grow}}{Radius grow factor on a very-good
boundary step (default \code{2.0}).}
}
}

\section{Quasi-Newton polish (cubic to BFGS line-search)}{

Once the iterate enters the quadratic attraction basin of a strict
local minimum, the cubic regularization penalty has decayed to its
floor and contributes negligible damping, but arcopt still evaluates
\code{hess()} every iteration. For expensive Hessians (analytic AD via
Stan, finite differences) this dominates wall-clock time. Polish
mode replaces the cubic subproblem with a Wolfe line search along the
BFGS-approximated Newton direction, skipping further \code{hess()} calls
until convergence or until the BFGS approximation drifts.

Off by default in v0.2.0 because the existing manuscript and benchmark
problems converge before the five-signal healthy-basin detector
accumulates a full window. Enable opt-in for long-running smooth
problems with expensive Hessians.
\describe{
\item{\code{qn_polish_enabled}}{Enable the cubic to qn_polish bidirectional
switch (default \code{FALSE}).}
\item{\code{qn_polish_window}}{Sliding-window length for the healthy-
basin detector (default \code{5}).}
\item{\code{qn_polish_rho}}{Minimum \code{rho_k} required throughout the
window (default \code{0.9}).}
\item{\code{qn_polish_lambda_min}}{Minimum \code{lambda_min(H_k)} required
throughout the window (default \code{1e-3}).}
\item{\code{qn_polish_g_decay}}{Maximum ratio of consecutive \verb{||g||_inf}
values; e.g. \code{0.5} requires 2x-per-iteration contraction
(default \code{0.5}).}
\item{\code{qn_polish_g_inf_floor}}{Absolute lower bound on \verb{||g||_inf}
at window start; prevents firing at convergence (default \code{1e-8}).}
\item{\code{qn_polish_c1}, \code{qn_polish_c2}}{Wolfe line-search constants
(defaults \code{1e-4} and \code{0.9}).}
\item{\code{qn_polish_alpha_max}}{Initial step length tried by the line
search (default \code{1.0}).}
\item{\code{qn_polish_max_ls_iter}}{Maximum line-search evaluations per
iteration (default \code{20}).}
\item{\code{qn_polish_max_fail}}{Consecutive line-search failures that
trigger a revert to cubic mode (default \code{3}).}
\item{\code{qn_polish_reenter_delay}}{Cubic iterations required after a
revert before qn_polish may re-fire (default \code{5}).}
\item{\code{qn_polish_curv_eps}}{Curvature threshold for skipping BFGS
updates to preserve PD (default \code{1e-10}).}
}
}

\section{Quasi-Newton variant (\code{use_qn = TRUE})}{

When \code{control$use_qn = TRUE}, \code{arcopt()} routes to an internal
quasi-Newton variant that approximates \code{H_k} via SR1/BFGS updates and
does not require a \code{hess} function. The following parameters apply
only when \code{use_qn = TRUE}.
\describe{
\item{\code{qn_method}}{One of \code{"hybrid"} (default), \code{"sr1"}, \code{"bfgs"}.
\code{"hybrid"} uses state-aware routing between SR1-first and
BFGS-first orderings based on the current B's eigenstructure and
recent rho values.}
\item{\code{bfgs_tol}}{Curvature tolerance for the BFGS update
(default \code{1e-10}).}
\item{\code{sr1_skip_tol}}{SR1 skip-test tolerance (default \code{1e-8}).}
\item{\code{sr1_restart_threshold}}{Consecutive SR1 skips before restart
(default \code{5}).}
\item{\code{qn_route_demote_rho}}{\code{rho} below this counts as a "bad"
step in the routing FSM (default \code{0.25}).}
\item{\code{qn_route_promote_rho}}{\code{rho} above this counts as a "good"
step (default \code{0.5}).}
\item{\code{qn_route_demote_k}}{Consecutive bad steps in \code{"pd"} routing
mode that demote back to \code{"indefinite"} (default \code{2}).}
\item{\code{qn_route_promote_k}}{Consecutive good PD steps in
\code{"indefinite"} mode that promote to \code{"pd"} (default \code{3}).}
\item{\code{qn_fd_refresh_k}}{Consecutive bad-rho iterations in
\code{"indefinite"} mode that trigger an FD-Hessian refresh of B
(default \code{3}).}
\item{\code{qn_stuck_refresh_k}}{Iterations stuck in \code{"indefinite"} mode
without promotion that force a refresh (default \code{100}).}
\item{\code{use_accel_qn}}{\strong{EXPERIMENTAL.} Enable Nesterov acceleration
in the QN path. May improve convergence on strongly convex
problems but can hurt nonconvex (default \code{FALSE}).}
}
}

\section{Diagnostics in \code{result$diagnostics}}{

Mode-dispatch diagnostics are nested under \code{result$diagnostics} so the
primary return list stays compact.
\describe{
\item{\code{solver_mode_final}}{\code{"cubic"}, \code{"tr"}, or \code{"qn_polish"} --
which subproblem solver was active at termination.}
\item{\code{ridge_switches}}{Integer count of cubic to TR transitions
(\code{0} or \code{1} in v1; the switch is one-way).}
\item{\code{radius_final}}{Final trust-region radius (\code{NA} if the solver
never switched to TR mode).}
\item{\code{qn_polish_switches}}{Integer count of cubic to qn_polish
transitions (bidirectional; may be \verb{> 1}).}
\item{\code{qn_polish_reverts}}{Integer count of qn_polish to cubic
reversions.}
\item{\code{hess_evals_at_polish_switch}}{\code{evaluations$hess} at the first
polish switch; compare against final \code{evaluations$hess} to
quantify Hessian-evaluation savings.}
}
QN-variant runs add \code{qn_updates}, \code{qn_skips}, \code{qn_restarts}, and
\code{qn_fd_refreshes} to the same sublist.
}

\seealso{
\code{\link{arcopt}} for the user-facing entry point.
}
