% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/control.R
\name{control_opt}
\alias{control_opt}
\title{Generate control specifications for \code{ngme()} function.}
\usage{
control_opt(
  seed = Sys.time(),
  burnin = 100,
  iterations = 500,
  estimation = TRUE,
  standardize_fixed = TRUE,
  n_batch = 10,
  iters_per_check = iterations/n_batch,
  optimizer = adam(),
  start = NULL,
  start_sd = 0.5,
  n_parallel_chain = 4,
  max_num_threads = n_parallel_chain,
  print_check_info = FALSE,
  max_relative_step = 0.5,
  max_absolute_step = 0.5,
  rao_blackwellization = FALSE,
  n_trace_iter = 10,
  sampling_strategy = "all",
  solver_backend = "cholmod",
  solver_type = "llt",
  verbose = FALSE,
  store_traj = TRUE,
  robust = FALSE,
  stepsize_control = NULL,
  n_min_batch = min(n_batch, 3),
  n_slope_check = min(n_batch, 3),
  trend_std_conv_check = TRUE,
  std_lim = 0.01,
  trend_lim = 0.01,
  R_hat_conv_check = TRUE,
  max_R_hat = 1.1,
  pflug_conv_check = TRUE,
  pflug_alpha = 0.9
)
}
\arguments{
\item{seed}{set the seed for pesudo random number generator}

\item{burnin}{interations for burn-in periods (before optimization)}

\item{iterations}{optimization iterations}

\item{estimation}{run the estimation process (call C++ in backend)}

\item{standardize_fixed}{whether or not standardize the fixed effect. When
\code{TRUE} (default), the design matrix is SVD-standardized internally and
any user-supplied \code{control_ngme(beta_init = ...)} is automatically
mapped from the original design scale to that standardized basis. Set to
\code{FALSE} to keep both the design matrix and any provided
\code{beta_init} on
their original scale.}

\item{n_batch}{number of checkpoints; optimization is split into \code{n_batch} equal batches}

\item{iters_per_check}{run how many iterations between each check point (or specify \code{n_batch})}

\item{optimizer}{choose different sgd optimization method,
currently support "sgd", "sgld", "precond_sgd", "momentum", "adagrad", "rmsprop", "adam", "adamW"
see ?sgd, ?precond_sgd, ?momentum, ?adagrad, ?rmsprop, ?adam, ?adamW}

\item{start}{deprecated guard argument. Do not pass model starts through
\code{control_opt()}; use \code{ngme(..., start = previous_fit)} instead.}

\item{start_sd}{standard deviation of the initial parameter (1st chain fixed, other chains random), set 0 to be fixed for all chains}

\item{n_parallel_chain}{number of parallel chains}

\item{max_num_threads}{maximum number of threads used for parallel computing, by default will be set same as n_parallel_chain.
If it is more than n_parallel_chain, the rest will be used to parallel different replicates of the model.}

\item{print_check_info}{print the convergence information}

\item{max_relative_step}{max relative step allowed in 1 iteration}

\item{max_absolute_step}{max absolute step allowed in 1 iteration}

\item{rao_blackwellization}{use rao_blackwellization}

\item{n_trace_iter}{use how many iterations to approximate the trace (Hutchinson’s trick)}

\item{sampling_strategy}{subsampling method of replicates of model, c("all", "ws")
"all" means using all replicates in each iteration,
"ws" means weighted sampling (each iteration use 1 replicate to compute the gradient, the sample probability is proption to its number of observations)}

\item{solver_backend}{backend in ("eigen", "cholmod", "pardiso")}

\item{solver_type}{factorization type: "llt" or "ldlt"}

\item{verbose}{print estimation}

\item{store_traj}{store the optimizer trajectory for diagnostics (set FALSE to reduce memory)}

\item{robust}{use robust mode in the backend optimizer/model updates}

\item{stepsize_control}{unified stepsize configuration created by
\code{stepsize_control()}, \code{poly_decay()}, or \code{batch_decay()}.
For polynomial schedule, \code{poly_decay(..., burnin_iter = B)} keeps
schedule scale at 1 for the first \code{B} iterations, then starts decay
with reset local time index.}

\item{n_min_batch}{minimum number of checkpoints before any convergence diagnostic is attempted}

\item{n_slope_check}{number of checkpoints used as the regression window for the trend test}

\item{trend_std_conv_check}{enable the trend/std diagnostic (uses \code{std_lim}, \code{trend_lim}, \code{n_slope_check})}

\item{std_lim}{maximum allowed standard deviation}

\item{trend_lim}{maximum allowed slope}

\item{R_hat_conv_check}{use the R-hat diagnostic for convergence checking}

\item{max_R_hat}{maximum allowed R_hat}

\item{pflug_conv_check}{use Pflug diagnostic for convergence check}

\item{pflug_alpha}{scaling factor (0-1] for Pflug criterion: require \code{pflug_sum < pflug_alpha * max_pflug_sum}}
}
\value{
list of control variables
}
\description{
These are configurations for \code{ngme}
optimization process.
}
\details{
Convergence diagnostics (multi-chain):
* R-hat: per-parameter Gelman–Rubin statistic; passes if \code{R_hat <= max_R_hat}.
* Trend/Std: uses the last \code{n_slope_check} checkpoints after at least \code{n_min_batch} batches.
  Passes when both the relative std (\code{sqrt(var)/|mean| <= std_lim}) and linear trend
  of the means (\code{|slope| <= trend_lim}) satisfy their thresholds.
* Pflug: per-chain criterion \code{pflug_sum < pflug_alpha * max_pflug_sum} in the latest batch;
  if all chains satisfy it, overall convergence is declared.
Checks are evaluated every \code{iters_per_check = iterations / n_batch}. A parameter is marked
converged if any enabled parameter-level diagnostic (R-hat or Trend/Std) passes; the run stops
when all parameters converge or when the Pflug diagnostic triggers.
}
