sdmTMBcontrol: Optimization control options

In sdmTMB: Spatial and Spatiotemporal SPDE-Based GLMMs with 'TMB'

Optimization control options

Description

sdmTMB() and stats::nlminb() control options.

Usage

sdmTMBcontrol(
  eval.max = 2000L,
  iter.max = 1000L,
  normalize = FALSE,
  nlminb_loops = 1L,
  newton_loops = 1L,
  mgcv = deprecated(),
  quadratic_roots = FALSE,
  start = NULL,
  map_rf = deprecated(),
  map = NULL,
  lower = NULL,
  upper = NULL,
  censored_upper = NULL,
  multiphase = TRUE,
  profile = FALSE,
  get_joint_precision = TRUE,
  parallel = getOption("sdmTMB.cores", 1L),
  suppress_nlminb_warnings = TRUE,
  ...
)

Arguments

eval.max	Maximum number of evaluations of the objective function allowed.
iter.max	Maximum number of iterations allowed.
normalize	Logical: use TMB::normalize() to normalize the process likelihood using the Laplace approximation? Can result in a substantial speed boost in some cases. This used to default to FALSE prior to May 2021. Currently not working for models fit with REML or random intercepts.
nlminb_loops	How many times to run stats::nlminb() optimization. Sometimes restarting the optimizer at the previous best values aids convergence. If the maximum gradient is still too large, try increasing this to 2.
newton_loops	How many Newton optimization steps to try after running stats::nlminb(). This sometimes aids convergence by further reducing the log-likelihood gradient with respect to the fixed effects. This calculates the Hessian at the current MLE with stats::optimHess() using a finite-difference approach and uses this to update the fixed effect estimates.
mgcv	Deprecated Parse the formula with mgcv::gam()?
quadratic_roots	Experimental feature for internal use right now; may be moved to a branch. Logical: should quadratic roots be calculated? Note: on the sdmTMB side, the first two coefficients are used to generate the quadratic parameters. This means that if you want to generate a quadratic profile for depth, and depth and depth^2 are part of your formula, you need to make sure these are listed first and that an intercept isn't included. For example, formula = cpue ~ 0 + depth + depth2 + as.factor(year).
start	A named list specifying the starting values for parameters. You can see the necessary structure by fitting the model once and inspecting your_model$tmb_obj$env$parList(). Elements of start that are specified will replace the default starting values.
map_rf	Deprecated use ⁠spatial = 'off', spatiotemporal = 'off'⁠ in sdmTMB().
map	A named list with factor NAs specifying parameter values that should be fixed at a constant value. See the documentation in TMB::MakeADFun(). This should usually be used with start to specify the fixed value.
lower	An optional named list of lower bounds within the optimization. Parameter vectors with the same name (e.g., b_j or ln_kappa in some cases) can be specified as a numeric vector. E.g. lower = list(b_j = c(-5, -5)). Note that stats::optimHess() does not implement lower and upper bounds, so you must set newton_loops = 0 if setting limits.
upper	An optional named list of upper bounds within the optimization.
censored_upper	An optional vector of upper bounds for sdmTMBcontrol(). Values of NA indicate an unbounded right-censored to distribution, values greater that the observation indicate and upper bound, and values equal to the observation indicate no censoring.
multiphase	Logical: estimate the fixed and random effects in phases? Phases are usually faster and more stable.
profile	Logical: should population-level/fixed effects be profiled out of the likelihood? These are then appended to the random effects vector without the Laplace approximation. See TMB::MakeADFun(). This can dramatically speed up model fit if there are many fixed effects but is experimental at this stage.
get_joint_precision	Logical. Passed to getJointPrecision in TMB::sdreport(). Must be TRUE to use simulation-based methods in predict.sdmTMB() or ⁠[get_index_sims()]⁠. If not needed, setting this FALSE will reduce object size.
parallel	Argument currently ignored. For parallel processing with 3 cores, as an example, use TMB::openmp(n = 3, DLL = "sdmTMB"). But be careful, because it's not always faster with more cores and there is definitely an upper limit.
suppress_nlminb_warnings	Suppress uninformative warnings from stats::nlminb() arising when a function evaluation is NA, which are then replaced with Inf and avoided during estimation?
...	Anything else. See the 'Control parameters' section of stats::nlminb().

Details

Usually used within sdmTMB(). For example:

sdmTMB(..., control = sdmTMBcontrol(newton_loops = 2))

Value

A list of control arguments

Examples

sdmTMBcontrol()

sdmTMB documentation built on Aug. 8, 2025, 6:38 p.m.