Skip to contents

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


  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,
  multiphase = TRUE,
  profile = FALSE,
  get_joint_precision = TRUE,
  parallel = getOption("sdmTMB.cores", 1L),



Maximum number of evaluations of the objective function allowed.


Maximum number of iterations allowed.


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.


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.


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.


Deprecated Parse the formula with mgcv::gam()?


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).


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.


Deprecated use spatial = 'off', spatiotemporal = 'off' in sdmTMB().


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.


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)).


An optional named list of upper bounds within the optimization.


Logical: estimate the fixed and random effects in phases? Phases are usually faster and more stable.


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.


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.


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.


Anything else. See the 'Control parameters' section of stats::nlminb().


A list of control arguments


Usually used within sdmTMB(). For example:

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


#> $eval.max
#> [1] 2000
#> $iter.max
#> [1] 1000
#> $normalize
#> [1] FALSE
#> $nlminb_loops
#> [1] 1
#> $newton_loops
#> [1] 1
#> $profile
#> [1] FALSE
#> $quadratic_roots
#> [1] FALSE
#> $start
#> $map
#> $lower
#> $upper
#> $multiphase
#> [1] TRUE
#> $parallel
#> [1] 1
#> $get_joint_precision
#> [1] TRUE