foceiControl: Control Options for FOCEi

In nlmixr2est: Nonlinear Mixed Effects Models in Population PK/PD, Estimation Routines

Control Options for FOCEi

Description

Control Options for FOCEi

Usage

foceiControl(
  sigdig = 3,
  ...,
  epsilon = NULL,
  maxInnerIterations = 1000,
  maxOuterIterations = 5000,
  n1qn1nsim = NULL,
  print = 1L,
  printNcol = NULL,
  scaleTo = 1,
  scaleObjective = 0,
  normType = c("rescale2", "mean", "rescale", "std", "len", "constant"),
  scaleType = c("nlmixr2", "norm", "mult", "multAdd"),
  scaleCmax = 1e+05,
  scaleCmin = 1e-05,
  scaleCband = c(0.1, 10),
  scaleC = NULL,
  scaleC0 = 1e+05,
  derivEps = rep(20 * sqrt(.Machine$double.eps), 2),
  derivMethod = c("switch", "forward", "central"),
  derivSwitchTol = NULL,
  covDerivMethod = c("central", "forward"),
  covMethod = c("r,s", "analytic", "r", "s", "sa", "imp", ""),
  covSolveTol = NULL,
  covFull = TRUE,
  fast = FALSE,
  priorMethod = c("auto", "general", "nwpri", "tnpri"),
  fdOutlierZ = 3.5,
  fdOutlierScale = TRUE,
  fdRefine = c("chartrand", "lanczos", "richardson"),
  fdLanczosM = 2L,
  fdRichardsonR = 2L,
  fdRichardsonV = 2,
  fdChartrandAll = FALSE,
  fdOutlierAny = FALSE,
  fdIndividualStep = TRUE,
  fdChartrand = TRUE,
  foceEbeTol = NULL,
  hessEps = (.Machine$double.eps)^(1/3),
  hessEpsLlik = (.Machine$double.eps)^(1/3),
  optimHessType = c("central", "forward"),
  optimHessCovType = c("central", "forward"),
  hessEtaStepMin = 0.05,
  censOption = c("gauss", "laplace"),
  eventType = c("central", "forward"),
  eventSens = c("jump", "fd"),
  centralDerivEps = rep(20 * sqrt(.Machine$double.eps), 2),
  lbfgsLmm = 7L,
  lbfgsPgtol = 0,
  lbfgsFactr = NULL,
  eigen = TRUE,
  diagXform = c("sqrt", "log", "identity"),
  iovXform = c("sd", "var", "logsd", "logvar"),
  iovMethod = c("auto", "theta", "omega"),
  sumProd = FALSE,
  optExpression = TRUE,
  literalFix = TRUE,
  literalFixRes = TRUE,
  ci = 0.95,
  useColor = NULL,
  boundTol = NULL,
  calcTables = TRUE,
  noAbort = TRUE,
  interaction = TRUE,
  foce = c("nonmem", "foce+"),
  cholSEtol = (.Machine$double.eps)^(1/3),
  cholAccept = 0.001,
  resetEtaP = 0.15,
  resetThetaP = 0,
  resetThetaFinalP = 0,
  diagOmegaBoundUpper = 5,
  diagOmegaBoundLower = 100,
  cholSEOpt = FALSE,
  cholSECov = FALSE,
  fo = FALSE,
  covTryHarder = FALSE,
  outerOpt = c("bobyqa", "nlminb", "lbfgsb3c", "L-BFGS-B", "mma", "lbfgsbLG", "slsqp",
    "uobyqa", "newuoa", "trust"),
  innerOpt = c("auto", "trust", "n1qn1", "BFGS"),
  innerHessian = c("focei", "conditional"),
  detHessian = c("focei", "conditional"),
  hessianMethod = c("fd", "bfgs", "sr1", "bofill"),
  trustConf = 0.975,
  trustRinit = NULL,
  trustRmax = NULL,
  trustFterm = NULL,
  trustMterm = NULL,
  outerTrustHessian = c("auto", "analytic", "bfgs", "fd"),
  outerTrustRinit = NULL,
  outerTrustRmax = NULL,
  outerTrustFterm = NULL,
  outerTrustMterm = NULL,
  outerTrustRelStep = 0.001,
  outerTrustRestarts = 3L,
  rhobeg = 0.2,
  rhoend = NULL,
  npt = NULL,
  rel.tol = NULL,
  x.tol = NULL,
  eval.max = 4000,
  iter.max = 2000,
  abstol = NULL,
  reltol = NULL,
  resetHessianAndEta = FALSE,
  muModel = c("none", "irls", "lin"),
  muRefCovAlg = TRUE,
  muModelTol = 1e-05,
  muModelMaxCycles = 20L,
  muModelClampRetries = 10L,
  stateTrim = Inf,
  shi21maxOuter = 0L,
  shi21maxInner = 20L,
  shi21maxInnerCov = 20L,
  shi21maxFD = 20L,
  shi21hMax = 2,
  shi21hMin = 1e-04,
  gillK = 10L,
  gillStep = 4,
  gillFtol = 0,
  gillRtol = sqrt(.Machine$double.eps),
  gillKcov = 10L,
  gillKcovLlik = 10L,
  gillStepCovLlik = 4.5,
  gillStepCov = 2,
  gillFtolCov = 0,
  gillFtolCovLlik = 0,
  rmatNorm = TRUE,
  rmatNormLlik = TRUE,
  smatNorm = TRUE,
  smatNormLlik = TRUE,
  covGillF = TRUE,
  optGillF = TRUE,
  covSmall = 1e-05,
  adjLik = TRUE,
  gradTrim = Inf,
  maxOdeRecalc = 5,
  odeRecalcFactor = 10^(0.5),
  gradCalcCentralSmall = 1e-04,
  gradCalcCentralLarge = 10000,
  etaNudge = qnorm(1 - 0.05/2)/sqrt(3),
  etaNudge2 = qnorm(1 - 0.05/2) * sqrt(3/5),
  etaRestart = 4L,
  nRetries = 3,
  seed = 42,
  resetThetaCheckPer = 0.1,
  etaMat = NULL,
  repeatGillMax = 1,
  stickyRecalcN = 4,
  outerMaxOdeRecalc = 5,
  outerOdeRecalcFactor = 10^(0.5),
  outerStickyRecalcN = 4,
  indTolRelax = TRUE,
  gradProgressOfvTime = 10,
  addProp = c("combined2", "combined1"),
  badSolveObjfAdj = 100,
  compress = FALSE,
  rxControl = NULL,
  sigdigTable = NULL,
  fallbackFD = FALSE,
  smatPer = 0.6,
  sdLowerFact = 0.001,
  zeroGradFirstReset = TRUE,
  zeroGradRunReset = TRUE,
  zeroGradBobyqa = TRUE,
  mceta = -2L,
  warm = c("calc", "save", "none"),
  nAGQ = 0,
  agqLow = -Inf,
  agqHi = Inf,
  sensMethod = c("default", "forward"),
  linCmtSensCarry = c("auto", "none"),
  zeroTheta = 0.001,
  boundedTransform = TRUE
)

Arguments

sigdig	Optimization significant digits. One value drives, with a single consistent formula, the inner/outer optimizer convergence tolerance (10^-sigdig), the boundary check tolerance (5*10^(-sigdig+1)), and the ODE solver tolerances: the rtol exponent IS sigdig and atol sits three orders below, so rtol = 10^-sigdig, atol = 10^(-sigdig-3) for every solver (stiff, non-stiff or auto-switching). The sensitivity (atolSens/rtolSens) tolerances match the main solve (the outer gradient and covariance are built from them); the steady-state (ssAtol/ssRtol) tolerances run one order looser. Keying the optimizer to the same 10^-sigdig means it converges to exactly the precision the solve supports. At the default sigdig = 3 this is atol = 1e-6, rtol = 1e-3.
...	Ignored parameters
epsilon	Precision of estimate for n1qn1 optimization.
maxInnerIterations	Number of iterations for n1qn1 optimization.
maxOuterIterations	Maximum number of L-BFGS-B optimization for outer problem.
n1qn1nsim	Number of function evaluations for n1qn1 optimization.
print	Either a scalar print-frequency ('0' = suppress, '1' (default) = every evaluation, 'N' = every Nth), OR a pre-built [iterPrintControl()] object. Equivalent to 'iterPrintControl(every = print, ncol = printNcol, useColor = useColor)'.
printNcol	Integer (or 'NULL') parameter columns per row before wrapping. 'NULL' (default) uses 'floor((getOption("width") - 23) / 12)'.
scaleTo	Scale the initial parameter estimate to this value. By default this is 1. When zero or below, no scaling is performed.
scaleObjective	Scale the initial objective function to this value. By default this is 0 (meaning do not scale)
normType	Parameter normalization/scaling used to get scaled initial values for scaleType, of the form Vscaled = (Vunscaled-C1)/C2 (see Feature Scaling; rescale2 follows the OptdesX manual): "rescale2" scales all parameters to (-1, 1); "rescale" (min-max) scales to (0, 1); "mean" centers on the mean with range (0, 1); "std" standardizes by mean/sd; "len" scales to unit (Euclidean) length; "constant" performs no normalization (C1=0, C2=1).
scaleType	The scaling scheme for nlmixr2: "nlmixr2" (default) scales as (current-init)*scaleC[i] + scaleTo, with scaleTo from normType and scales from scaleC; "norm" uses the simple scaling from normType; "mult" scales multiplicatively as current/init*scaleTo; "multAdd" scales linearly ((current-init)+scaleTo) for parameters in an exponential block (e.g. exp(theta)) and multiplicatively otherwise.
scaleCmax	Maximum value of the scaleC to prevent overflow.
scaleCmin	Minimum value of the scaleC to prevent underflow.
scaleCband	Length-2 increasing pair 'c(low, high)' (default ‘c(0.1, 10)'). Each 'theta'’s derivative-based scaling constant ('1/|init|' for a linear parameter, or the transform-specific formula) is kept when it lands inside this band, and otherwise replaced by the parameter's native magnitude '|init|'. This catches the singular cases – '1/|init|' blowing up for a small covariate initial estimate, 'log()' at init '1', 'logit' at the interval midpoint, 'factorial'/'gamma' at a digamma zero – while leaving the well-scaled common case (and its results) untouched.
scaleC	Scaling constant used with scaleType="nlmixr2"; when not specified, chosen by parameter type to keep gradient sizes similar on a log scale: '1' for exp()-transformed/power/boxCox/ yeoJohnson parameters, '0.5*abs(est)' for additive/proportional/ lognormal error parameters, 'abs(1/digamma(est+1))' for factorials, and 'log(abs(est))*abs(est)' for log-scale parameters. May be set explicitly per parameter if these defaults don't apply well.
scaleC0	Number to adjust the scaling factor by if the initial gradient is zero.
derivEps	Forward difference tolerances (relative, absolute); step size h = abs(x)*derivEps[1] + derivEps[2].
derivMethod	Derivative method for the outer problem: "switch", "central", or "forward". "switch" starts forward and toggles to central when abs(delta(OFV)) <= derivSwitchTol.
derivSwitchTol	The tolerance to switch forward to central differences.
covDerivMethod	indicates the method for calculating the derivatives while calculating the covariance components (Hessian and S).
covMethod	Method for calculating the covariance. "r,s" (the default) is the sandwich estimator (see below). "analytic" uses the exact analytic observed-information R-matrix (reported as R^{-1}) and additionally returns the residual and Omega standard errors; it covers FOCEI/FOCE fits with additive, proportional, or combined error, mu-referenced/covariate/other structural parameters (and non-mu-referenced etas), and SD-scale inter-occasion variability, and emits a message and falls back to the finite-difference Hessian for anything out of scope (FO, nAGQ > 1, censoring, DV-transformed error, bounded-parameter transforms, a structural theta shared by two etas, non-SD iovXform, or a pure-proportional variance that vanishes at a near-zero prediction). The finite-difference methods use R (the Hessian) and S (the sum of individual gradient cross-products at the empirical Bayes estimates): "r,s" sandwich (solve(R)%*%S%*%solve(R)), "r" Hessian-based (solve(R)), "s" cross-product-based (solve(S)), or "" to skip the covariance step. "sa" (SAEM Louis stochastic-approximation FIM) and "imp" (importance-sampling Monte-Carlo observed information) are also accepted for any method; they are computed post-fit at the converged estimates by the decoupled recompute engine.
covSolveTol	absolute/relative ODE tolerance for the covariance solves – the augmented-sensitivity solves behind covMethod="analytic" and the perturbed solves behind the finite-difference methods. NULL (default) derives a tight tolerance from sigdig; supply a number to override it.
covFull	shape of fit$cov. TRUE (default) installs the full theta + residual sigma + Omega covariance (assembled analytically for covMethod="analytic", or by central finite differences over the same parameter set otherwise). For the finite-difference methods it follows covMethod: "r,s" is the full sandwich solve(Rfull) %*% Sfull %*% solve(Rfull), "s" is solve(Sfull), "r" is solve(Rfull). FALSE installs only the structural-theta block (the historical shape). The installed shape is named by fit$covMethod – "r,s (full)" versus "r,s" – and the other shape is cached, so setCov() swaps between them without recomputing either.
fast	When TRUE, compute the outer (population) gradient analytically from Almquist (2015) sensitivity equations instead of by finite differences, and use the Eq-48 random-effect extrapolation for the next inner-problem starting values. Requires an analytic-scope model. Conditionally Gaussian endpoints route through the general (f,R) assembler, which covers more than the plain add/prop case – multiple endpoints, combined and power error, both-sides transforms and a single estimated boxCox/yeoJohnson lambda. A single non-Gaussian (ll()/generalized) endpoint instead differentiates the log-density directly, giving an exact inner Hessian and analytic outer gradient. Out of scope are linCmt(), fo, IOV, more than one estimated lambda, a theta mu-referenced by several random effects, and (for the non-Gaussian path) multiple endpoints, censoring or nAGQ > 1; those fall back to the finite-difference gradient with a message (linCmt() and out-of-scope log-likelihood models downgrade to fast=FALSE up front). When unspecified, the outer optimizer defaults to "lbfgsb3c" (vs "bobyqa" for fast=FALSE); pairing fast=TRUE with a derivative-free outerOpt reverts to fast=FALSE. The *f methods (e.g. foceif) default this to TRUE.
priorMethod	Which of the shared prior kernel's three omega conventions (nlmixr2/rxode2#1270) to evaluate an ini({}) prior() under – "general" (textbook Bayesian), "nwpri" (NONMEM's own ⁠$PRIOR NWPRI⁠), or "tnpri" (the Monolix/NONMEM-own-estimation joint-normal convention on omega). The default, "auto", reads the convention off what the model's own ini({}) actually wrote (an invWishart() degrees-of- freedom prior on an omega block means "nwpri"; a normal prior directly on an omega element means "tnpri"; anything else, including a dcauchy() prior, means "general") – deliberately never a fixed default, since the identical invWishart(nu) syntax means a different number under "general" and "nwpri". Setting this explicitly forces that convention regardless of what auto-detection would have picked, and errors before any estimation starts if the model's priors are not representable under it (e.g. priorMethod="tnpri" on a model with an invWishart() prior). Ignored when the model has no prior at all.
fdOutlierZ	Cut of the Iglewicz-Hoaglin modified z-score that decides whether a finite-differenced subject's slope is an outlier against the exact analytic slopes, and so whether 'fdChartrand' refines it. The conventional 3.5; lower it to make the pass fire more readily (and to exercise it), raise it to suppress it without turning 'fdChartrand' off.
fdOutlierScale	Test the outlier criterion on the **per-observation** slope ('TRUE', the default) rather than the raw one. A per-subject slope scales with how much data that subject carries, so raw slopes from a 3-observation and a 20-observation subject are not draws from one distribution – pooling them makes a legitimately large slope look like an outlier on unbalanced or sparse data. Only the test is scaled; the gradient itself is untouched. On balanced data this changes nothing, since dividing every slope by the same count leaves the modified z-score unchanged.
fdRefine	Estimator used to recompute a finite-differenced slope once the outlier pass fires. On noisy, hard-to-solve likelihood surfaces the ordering is roughly '"richardson"' < '"lanczos"' < '"chartrand"': * '"richardson"' – Richardson extrapolation of central differences at 'h, h/v, h/v^2, ...', cancelling the 'h^2, h^4, ...' truncation terms in turn. Cheapest, and right when the surface is smooth and only truncation matters. It extrapolates toward 'h -> 0', which is *into* the noise, so it is the wrong instrument when the noise floor is what limits the difference. * '"lanczos"' – the Lanczos generalized derivative, a least-squares slope through '2m+1' points. Same 'O(h^2)' truncation as a central difference but lower variance, since independent evaluation noise averages down as points are added rather than being amplified. The middle rung. * '"chartrand"' (default) – total-variation regularized differentiation over a wide interval, which absorbs curvature through the regularized derivative itself instead of assuming a stencil. Most expensive and most robust to a genuinely rough surface. All three apply identically: they are gated by the same outlier test, touch only the finite-differenced subjects, and never recompute a subject whose analytic gradient is available.
fdLanczosM	Half-width 'm' of the '"lanczos"' estimator ('2m' evaluations).
fdRichardsonR	Depth of the '"richardson"' extrapolation table.
fdRichardsonV	Step-shrink ratio 'v' of the '"richardson"' estimator.
fdChartrandAll	When the outlier pass fires for a parameter, refine **every** finite-differenced subject with the Chartrand TV derivative rather than only the outlying ones. Subjects whose augmented solve succeeded keep their exact analytic gradient either way – only finite differences are ever recomputed. Default 'FALSE' (refine the outliers only).
fdOutlierAny	Let an outlier among the **exact analytic** slopes fire the outlier pass as well, not only an outlier among the finite differences. Still only the finite differences are recomputed. Default 'FALSE'.
fdIndividualStep	For the per-subject finite-difference fallback of the analytic outer gradient ('fast=TRUE'), search the shi step size separately for every flagged subject ('TRUE', the default) rather than once on the summed objective over them. The subjects that reach this path are the badly conditioned ones, so one shared step cannot suit them all; a per-subject search also supplies the population of converged peers a clamped step is repaired from. 'FALSE' restores the single shared step, which costs fewer evaluations.
fdChartrand	Refine finite-difference slopes that the robust outlier test flags (default TRUE). When a subject's per-parameter slope sits far outside the modified z-score interval of the others, its central difference is suspect; those slopes – and only those – are recomputed with a total-variation regularized derivative (Chartrand) on a wide interval. Set FALSE to keep the plain central difference. On by default because the outlier test is itself the gate: a well-behaved problem flags nothing and pays nothing, so the cost falls only on the complex fits where a slope really is an outlier – exactly where you would want the refinement, and where a user is least likely to know to ask for it. fit$env$nFdOutlier reports flagged parameters and refined slopes, so you can see whether it engaged for a given fit. Worth knowing when judging it: the measurements that originally motivated this refinement were taken while the likelihood and the Shi step selection were both faulty, so they do not evidence its value on current code, and it has not been observed to trigger on ordinary fits.
foceEbeTol	Convergence tolerance on the score of the FOCE frozen-variance EBE re-solve, which the analytic outer gradient (fast=TRUE, interaction=FALSE) needs because FOCE's mode is not the inner problem's mode. NULL (default) uses 1e-9; the first iteration uses a looser 1e-3 so an already-stationary eta is returned untouched. Unlike the solver and optimizer tolerances this is not derived from sigdig – it is a convergence target on an inner Newton rather than a precision request. It also bounds the Newton decrement at which a stalled subject is accepted at the ODE solve's noise floor rather than declining the gradient. Set it explicitly to test whether a fit's finite-difference fallbacks are tolerance-driven.
hessEps	is a double value representing the epsilon for the Hessian calculation. This is used for the R matrix calculation.
hessEpsLlik	is a double value representing the epsilon for the Hessian calculation when doing focei generalized log-likelihood estimation. This is used for the R matrix calculation.
optimHessType	Hessian type for numeric-difference individual Hessians in generalized log-likelihood estimation: "central" (matches R's 'optimHess()', default) or "forward" (faster).
optimHessCovType	Hessian type for numeric-difference individual Hessians used for the covariance step/final likelihood: "central" (more accurate, used here) or "forward".
hessEtaStepMin	Floor on the finite-difference step used for the individual (eta) Hessian in generalized log-likelihood estimation, expressed as a fraction of that random effect's own standard deviation (sqrt(diag(Omega))). Default 0.05; 0 restores the plain absolute shi21hMin floor. The Shi (2021) step search is told the function's noise floor is rxControl(atolSens=), but the inner gradient it differences comes out of a sensitivity solve that rtolSens governs as well, so the noise is understated and the search shrinks the step until the difference is taken inside it. n1qn1 absorbs that – it uses this Hessian only as a warm-start seed and then corrects it by its own quasi-Newton updates as it iterates – but innerOpt="trust" re-derives it as its trust-region model Hessian at every trial point, with nothing to correct it, and adds its log-determinant to the reported objective. Flooring the step relative to the eta scale stops the runaway without paying for a tighter solve. It applies to every inner optimizer: the step a finite difference needs is a property of the problem, not of who consumes the Hessian.
censOption	Treatment of the second derivative for censored (M2/M3/M4/BLQ) observations in the FOCEI family. "gauss" (the default) keeps the historic uncensored Gauss-Newton curvature, matching common PMx tools; "laplace" uses the exact censored second derivative of the objective (a proper Laplace inner Hessian and analytic covariance). Accepted by saemControl/nlmControl for a uniform interface but inert there – SAEM (stochastic EM) has no Laplace inner Hessian, and NLM uses a finite-difference Hessian that already reflects censoring exactly.
eventType	Event gradient type for dosing events; Can be "central" or "forward"
eventSens	Controls how dosing/event-parameter ('alag', 'F', 'rate', 'dur') sensitivities are computed for THETA/ETA gradients: ‘"jump"' (default) uses rxode2’s analytic event sensitivities; '"fd"' uses the legacy finite-difference behavior. Also gates the analytic moving-boundary correction for a modeled 'alag()'/'f()' on a 'linCmt()' compartment; set '"fd"' if that model infuses a dose into the lagged/scaled compartment (rxode2/rxode2#1236), or if the regimen also doses an *unlagged/unscaled* compartment alongside the lagged/scaled one – a common design for estimating 'f()' from paired IV+oral data (rxode2/rxode2#1237).
centralDerivEps	Central difference tolerances (relative, absolute); step size h = abs(x)*derivEps[1] + derivEps[2].
lbfgsLmm	An integer giving the number of BFGS updates retained in the "L-BFGS-B" method, It defaults to 7.
lbfgsPgtol	Projected-gradient convergence tolerance for "L-BFGS-B": iteration stops when max(| proj g_i |) <= lbfgsPgtol. Defaults to '0' (check suppressed).
lbfgsFactr	Convergence factor for "L-BFGS-B": converges when the objective reduction is within lbfgsFactr * .Machine$double.eps. Derived from sigdig as 10^(-sigdig-2) / .Machine$double.eps, two orders tighter than the other sigdig-derived tolerances. It tests the objective reduction of a SINGLE step rather than stationarity, so a target of 10^-sigdig stops as soon as one step is small; the extra two orders are what make the analytic-gradient (fast=TRUE) methods reach the same optimum as the derivative-free default.
eigen	A boolean indicating if eigenvectors are calculated to include a condition number calculation.
diagXform	Transformation used on the diagonal of chol(solve(omega)) (the FOCEi-estimated parameters): one of "sqrt" (default), "log", or "identity".
iovXform	Transformation used on the diagonal of the IOV: one of "sd", "var", "logsd", or "logvar". This parameterizes the magnitude theta of the "theta" iovMethod; it has no effect under "omega", where the magnitude is fixed at one and the variability is carried by the omega block itself.
iovMethod	How inter-occasion variability is expanded before estimation: one of "auto" (default), "theta" or "omega". "theta" is the long-standing expansion: each occasion parameter becomes a magnitude theta, with one unit-variance eta per occasion fixed to it. That shape cannot represent a correlation between two occasion parameters. "omega" instead fixes the magnitude theta at one and estimates the per-occasion eta blocks directly, occasion one being the block and the rest repeating it (NONMEM's $OMEGA BLOCK(n) SAME). The correlation then lives in the estimated block. "auto" picks "omega" when the IOV block has any off-diagonal element, since "theta" provably cannot represent one, and "theta" otherwise. "omega" may be asked for on a diagonal block as well, so the two can be compared on the same model. The choice is made per LEVEL of variability, so a correlation on occ does not change how an unrelated diagonal occ2 is expanded. "omega" is only available for estimation methods that honour the repeated block (the FOCEi family). saem and the variational, nonparametric and importance-sampling methods estimate omega elsewhere, so they continue to refuse a correlated occasion block rather than silently estimate each occasion on its own. The two are the same statistical model – at an occasion variance of one, where the parameterizations coincide, they agree on the objective to machine precision, and evaluated at matched random effects they agree to ~2e-8 at any variance. They are not interchangeable in practice: "theta" hands FOCEi's inner optimizer unit-scale etas and so converges the inner problem better when the occasion variance is far from one. That is why "auto" keeps "theta" unless a correlation forces "omega".
sumProd	Is a boolean indicating if the model should change multiplication to high precision multiplication and sums to high precision sums using the PreciseSums package. By default this is FALSE.
optExpression	Optimize the rxode2 expression to speed up calculation. By default this is turned on.
literalFix	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
literalFixRes	boolean, substitute fixed population values as literals and re-adjust ui and parameter estimates after optimization; Default is 'TRUE'.
ci	Confidence level for some tables. By default this is 0.95 or 95% confidence.
useColor	Logical (or 'NULL') emit ANSI bold/color escapes in the iteration print. 'NULL' (default) defers to [crayon::has_color()].
boundTol	Tolerance for boundary issues.
calcTables	This boolean is to determine if the foceiFit will calculate tables. By default this is TRUE
noAbort	Boolean to indicate if you should abort the FOCEi evaluation if it runs into troubles. (default TRUE)
interaction	Boolean indicate FOCEi should be used (TRUE) instead of FOCE (FALSE)
foce	Controls how FOCE (interaction = FALSE) evaluates the residual variance R in the inner objective; ignored for FOCEi. Either "nonmem" (default) or "foce+": "nonmem" freezes R at the eta = 0 population prediction and holds it constant across the inner optimization. This follows NONMEM's residual-variance convention for FOCE without interaction. "foce+" evaluates R at the current conditional eta (the live variance), keeping the truncated FOCE inner score, which is refined before evaluating the marginal objective. It retains the live-variance convention used in nlmixr2est 6.0.1 and earlier. It differs from NONMEM's FOCE without interaction and omits the variance derivatives included in FOCEI.
cholSEtol	tolerance for Generalized Cholesky Decomposition. Defaults to suggested (.Machine$double.eps)^(1/3)
cholAccept	Tolerance to accept a Generalized Cholesky Decomposition for a R or S matrix.
resetEtaP	P-value for resetting an individual ETA to 0 during optimization, based on a z-test of chol(omega^-1) %*% eta or eta/sd(allEtas). '0' = never reset, '1' = always reset.
resetThetaP	P-value for resetting mu-referenced THETAs based on ETA drift, checked at the start and near a local minimum (see resetThetaCheckPer). '0' = never reset (the default); '1' is not allowed. Defaults to off: when the etas cannot re-center the reset repeats without progress and can error the fit out, and where it converges it reaches a worse optimum than leaving it off.
resetThetaFinalP	represents the p-value for resetting the population mu-referenced THETA parameters based on ETA drift during optimization, and resetting the optimization one final time. '0' = never reset (the default); see resetThetaP.
diagOmegaBoundUpper	Upper bound of the diagonal omega matrix, as diag(omega)*diagOmegaBoundUpper. '1' = no upper bound.
diagOmegaBoundLower	Lower bound of the diagonal omega matrix, as diag(omega)/diagOmegaBoundLower. '1' = no lower bound.
cholSEOpt	Boolean indicating if the generalized Cholesky should be used while optimizing.
cholSECov	Boolean indicating if the generalized Cholesky should be used while calculating the Covariance Matrix.
fo	is a boolean indicating if this is a FO approximation routine.
covTryHarder	If the R matrix is non-positive definite and cannot be corrected to be non-positive definite try estimating the Hessian on the unscaled parameter space.
outerOpt	optimization method for the outer problem Fast "nlminb" fits automatically use the analytical outer Hessian for supported Gaussian FOCE/FOCE+/FOCEI/AGQ models, restarting with gradients only if curvature is unavailable. "trust" is a trust-region Newton method (RcppTrust) built on that same Hessian; see outerTrustHessian. It is unbounded, so a trial point outside the box is reported as an infinite objective and the region shrinks instead.
innerOpt	optimization method for the inner (per-subject eta) problem: '"auto"' (default), '"trust"' (RcppTrust trust-region Newton, using an exact Gauss-Newton+Omega^-1 Hessian every iteration) or '"n1qn1"' (quasi-Newton, gets a Hessian only once as a warm-start seed). '"BFGS"' is accepted but not implemented – it silently falls back to '"n1qn1"'. '"auto"' picks '"n1qn1"' for a generalized-likelihood endpoint ('dnorm()', 'll()', 'dpois()', ...) and '"trust"' for everything else. Such an endpoint has no Gauss-Newton shortcut, so the inner eta Hessian is finite-differenced; '"trust"' rebuilds it at every trial point, which costs 2*neta inner solves each time, while '"n1qn1"' builds it once as a warm-start seed and corrects it with its own quasi-Newton updates. On everything else '"trust"' is typically the faster of the two.
innerHessian	Inner optimization curvature: '"focei"' (default) or '"conditional"'. Full conditional curvature requires fast Gaussian FOCEI. Inner trust uses it at each trial; n1qn1 uses it with 'warm="calc"'. Value, gradient and full curvature share one sensitivity solve. The marginal objective's FOCEI curvature is unchanged. It is not supported with registered external likelihood contributions.
detHessian	Curvature entering the objective's Laplace log-determinant: '"focei"' (default), the Gauss-Newton expected information, or '"conditional"', the full conditional Hessian (the observed information at the conditional mode, as NONMEM's LAPLACE). '"conditional"' requires fast Gaussian FOCEI; the analytic outer gradient then carries the matching third-order terms, and the analytic covariance falls back to finite differences.
hessianMethod	For a non-normal-endpoint model (any distribution other than norm), the per-subject inner Hessian has no Gaussian Gauss-Newton shortcut and falls back to a finite difference of the gradient every 'innerOpt="trust"' Newton step ('calcEtaHessian()', 'src/inner.cpp'). '"fd"' (default) recomputes this Hessian from scratch every Newton step via finite difference. '"bfgs"' is the damped BFGS update (Nocedal & Wright, *Numerical Optimization*, 2nd ed., 2006, Procedure 18.2), always positive definite; '"sr1"' is the Symmetric Rank-1 update (Nocedal & Wright; Murtagh & Sargent, *Comput. J.* 13, 1970), not forced positive definite; ‘"bofill"' is Bofill’s (1994, *J. Comput. Chem.* 15, 1-11) SR1/Powell-Symmetric-Broyden blend. All three are built from consecutive Newton steps' already-computed gradients (no extra evaluations), seeded from one '"fd"'-style Hessian on the first Newton step of each inner solve. Unlike ‘trustControl(hessianMethod=)'’s analogous OUTER-theta option (where '"sr1"' is the default), this inner Hessian is not just a step-direction aid: 'LikInner2()' ('src/inner.cpp') adds this Hessian's log-determinant directly into the reported Laplace objective, which the OUTER optimizer then searches over. A quasi-Newton estimate built from the handful of Newton steps one subject's inner solve takes is accurate enough to guide the step but not accurate enough to serve as that objective term – confirmed on a real one-compartment IV model fit as a general ll()/'dnorm()' endpoint: '"bfgs"'/'"sr1"'/'"bofill"' all converged to the same wrong 'Vc' (about 90 against a simulated 70 and a plain (non-'ll()') ‘focei' fit’s 67, with a *worse* reported objective than ‘"fd"'’s correct answer) – the biased log-determinant misleads the outer search into a worse point it reports as better. ‘"fd"'’s fresh finite difference has no such bias, so it stays the default here even though '"bfgs"'/'"sr1"'/'"bofill"' remain available (and are genuinely faster, per this package's own small benchmark, 'inst/benchmarks/benchmark-focei-hessian-method.R') for a caller who has verified their model does not depend on this Hessian's precision. Has no effect for normal-endpoint models (the Gauss-Newton inner Hessian is used unconditionally there). Only meaningful with 'innerOpt="trust"', which the default 'innerOpt="auto"' does not pick for these models – so setting this needs 'innerOpt="trust"' pinned as well. Asking for '"bfgs"'/'"sr1"'/'"bofill"' under any other inner optimizer is an error rather than a silent no-op: 'foceiControl()' refuses a pinned 'innerOpt', and the fit refuses one '"auto"' resolves to '"n1qn1"'.
trustConf	confidence level defining the 'innerOpt="trust"' trust-region radius: since eta ~ N(0, Omega), the radius (in sqrt(diag(Omega))-scaled units) is 'sqrt(qchisq(trustConf, df=neta))', the boundary of the 'trustConf'-level eta confidence region. Default 0.975.
trustRinit	initial 'innerOpt="trust"' trust-region radius. 'NULL' (default) derives it from 'trustConf'.
trustRmax	maximum 'innerOpt="trust"' trust-region radius. 'NULL' (default) derives it from 'trustConf'.
trustFterm, trustMterm	‘innerOpt="trust"'’s own function-value and predicted-decrease convergence tolerances for the per-subject Newton solve. 'NULL' (default) uses '10^(-sigdig-2)', two orders tighter than the plain '10^(-sigdig)' most tolerances here use, for the same reason 'lbfgsFactr' is: the inner solve is the function the outer problem differentiates, so this tolerance sets the objective's noise floor and a finite-difference outer gradient cannot resolve a step below it. Left at the plain '10^(-sigdig)', an 'nAGQ=2' 'theo_sd' fit stopped at an objective of 134.46 against 118.52, and took longer doing it – the noisy gradient misleads the outer search as well as lengthening it. Deliberately NOT derived from ‘epsilon' ('"n1qn1"'’s own, unrelated "precision of estimate" tolerance) – tying ‘"trust"'’s stopping criterion to a value picked for a different optimizer is exactly the coupling these parameters exist to remove. Has no effect unless 'innerOpt="trust"'.
outerTrustHessian	Curvature source for outerOpt="trust". "auto" (default) uses the analytical outer Hessian when fast=TRUE makes it available and the damped-BFGS update otherwise, and falls back to that update if the Hessian is refused mid-fit. "analytic" requires fast=TRUE. "bfgs" is the damped BFGS update (Nocedal & Wright, Numerical Optimization 2nd ed., Procedure 18.2) built from consecutive gradients, so it adds no evaluations. "fd" differences the outer gradient, costing one extra population gradient per parameter per iteration.
outerTrustRinit, outerTrustRmax	Initial and maximum trust-region radius for outerOpt="trust", in the scaled-parameter space the outer problem optimizes in. NULL (default) derives outerTrustRinit from minqa::bobyqa()'s own default-rhobeg formula and outerTrustRmax as 8 * outerTrustRinit.
outerTrustFterm, outerTrustMterm	Function-value and predicted-decrease convergence tolerances for outerOpt="trust". NULL (default) uses 10^(-sigdig-2); outerTrustMterm defaults to outerTrustFterm.
outerTrustRelStep	Relative step handed to the analytical outer Hessian, and used for the outerTrustHessian="fd" gradient difference.
outerTrustRestarts	How many times outerOpt="trust" may re-enter the trust region from its own reported solution when the Newton decrement there says the point is not stationary. A collapsing trust region satisfies the solver's own convergence test at a point that is not a minimum; re-entering restores the initial radius. maxOuterIterations is the total across restarts, not per restart.
rhobeg	Initial trust region radius for the bobyqa outer optimizer (with 'rhoend', must satisfy '0 < rhoend < rhobeg'). Default '0.2' (20 'abs(upper-lower)/2'. (bobyqa)
rhoend	Final trust region radius. If not defined, '10^(-sigdig)' is used. (bobyqa)
npt	Number of points for bobyqa's quadratic approximation to the objective; must be in '[n+2, (n+1)(n+2)/2]'. Defaults to '2*n + 1'. (bobyqa)
rel.tol	Relative tolerance before nlminb stops (nlmimb).
x.tol	X tolerance for nlmixr2 optimizer
eval.max	Number of maximum evaluations of the objective function (nlmimb)
iter.max	Maximum number of iterations allowed (nlmimb)
abstol	Absolute tolerance for nlmixr2 optimizer (BFGS)
reltol	tolerance for nlmixr2 (BFGS)
resetHessianAndEta	is a boolean representing if the individual Hessian is reset when ETAs are reset using the option resetEtaP.
muModel	Mu-referenced-FOCEI-family regression variant: "none" (default, ordinary FOCEI); "lin" (mfocei/mfoce/magq/mlaplace) profiles mu-referenced population thetas and covariate coefficients out of the outer optimizer via closed-form OLS regression of each subject's back-calculated value on the covariates (muModelTol/ muModelMaxCycles); "irls" (ifocei/ifoce/iagq/ilaplace) reweights that by inner-optimization curvature. Bounded mu parameters are regression-updated with a clamped step (muModelClampRetries); a user-fixed (fix()) mu theta is never updated.
muRefCovAlg	When 'TRUE' (default), algebraic expressions that can be mu-referenced are internally rewritten as mu-referenced covariates and restored after optimization. Mirrors saemControl(muRefCovAlg=)/nlmeControl(muRefCovAlg=); for foceiControl() only takes effect when muModel != "none".
muModelTol	Convergence tolerance for the mu-referenced-FOCEI-family "re-optimize etas, then regress" cycle (muModel != "none"): repeats until the max mu-group theta change drops below this value or muModelMaxCycles is reached.
muModelMaxCycles	Maximum number of "re-optimize etas, regress" cycles per outer iteration (see muModel, muModelTol).
muModelClampRetries	Maximum number of active-set re-solve passes per group per regression update when a bounded mu-referenced parameter must be clamped to its bound (see muModel); on hitting the cap the current clamped-feasible solution is used.
stateTrim	Trim state amounts/concentrations to this value.
shi21maxOuter	The maximum number of steps for the optimization of the forward-difference step size. When not zero, use this instead of Gill differences.
shi21maxInner	The maximum number of steps for the optimization of the individual Hessian matrices in the generalized likelihood problem. When 0, un-optimized finite differences are used.
shi21maxInnerCov	The maximum number of steps for the optimization of the individual Hessian matrices in the generalized likelihood problem for the covariance step. When 0, un-optimized finite differences are used.
shi21maxFD	The maximum number of steps for the optimization of the forward difference step size when using dosing events (lag time, modeled duration/rate and bioavailability)
shi21hMax	Upper bound on the adaptive shi21 finite-difference step size for FOCEi gradients (both the inner eta and outer theta/covariate finite differences). The step-size search never probes a parameter by more than this on its estimation scale; a larger value lets the gradient of a flat, small-magnitude parameter (e.g. a covariate coefficient near 0) clear the ODE-solver noise floor, at the cost of risking a degenerate solve at the probe.
shi21hMin	Lower bound on the adaptive shi21 finite-difference step size for FOCEi gradients. The floor is limited by the ODE solver tolerance (atol/rtol), not machine precision; below it the finite difference is dominated by solver noise.
gillK	Max steps to determine the optimal forward/central difference step size per parameter (Gill 1983). '0' = no optimal step size determined.
gillStep	When looking for the optimal forward difference step size, this is This is the step size to increase the initial estimate by. So each iteration the new step size = (prior step size)*gillStep
gillFtol	The gillFtol is the gradient error tolerance that is acceptable before issuing a warning/error about the gradient estimates.
gillRtol	The relative tolerance used for Gill 1983 determination of optimal step size.
gillKcov	Max steps to determine the optimal forward/central difference step size per parameter (Gill 1983) during the covariance step. '0' = no optimal step size determined.
gillKcovLlik	Same as gillK but for the generalized focei log-likelihood method (Gill 1986).
gillStepCovLlik	Same as above but during generalized focei log-likelihood
gillStepCov	When looking for the optimal forward difference step size, this is This is the step size to increase the initial estimate by. So each iteration during the covariance step is equal to the new step size = (prior step size)*gillStepCov
gillFtolCov	The gillFtol is the gradient error tolerance that is acceptable before issuing a warning/error about the gradient estimates during the covariance step.
gillFtolCovLlik	Same as above but applied during generalized log-likelihood estimation.
rmatNorm	A parameter to normalize gradient step size by the parameter value during the calculation of the R matrix
rmatNormLlik	A parameter to normalize gradient step size by the parameter value during the calculation of the R matrix if you are using generalized log-likelihood Hessian matrix.
smatNorm	A parameter to normalize gradient step size by the parameter value during the calculation of the S matrix
smatNormLlik	A parameter to normalize gradient step size by the parameter value during the calculation of the S matrix if you are using the generalized log-likelihood.
covGillF	Use the Gill calculated optimal Forward difference step size for the instead of the central difference step size during the central difference gradient calculation.
optGillF	Use the Gill calculated optimal Forward difference step size for the instead of the central difference step size during the central differences for optimization.
covSmall	Small number used to compare covariance estimates (sandwich vs R/S matrix) before rejecting one as too small to be the final covariance estimate.
adjLik	When 'TRUE', adjusts the likelihood by the 2*pi constant nlmixr2's objective function otherwise omits (to match NONMEM), more closely matching nlme/SAS likelihood approximations. The objective function itself always matches NONMEM regardless.
gradTrim	The parameter to adjust the gradient to if the |gradient| is very large.
maxOdeRecalc	Maximum number of times to reduce the ODE tolerances and try to resolve the system if there was a bad ODE solve.
odeRecalcFactor	The ODE recalculation factor when ODE solving goes bad, this is the factor the rtol/atol is reduced
gradCalcCentralSmall	A small number that represents the value where |grad| < gradCalcCentralSmall where forward differences switch to central differences.
gradCalcCentralLarge	A large number that represents the value where |grad| > gradCalcCentralLarge where forward differences switch to central differences.
etaNudge	When n1qn1 optimization of an ETA (starting at zero) misbehaves, reset the Hessian and nudge the ETA up by this value, then down if it still doesn't move. Defaults to 'qnorm(1-0.05/2)*1/sqrt(3)'. Falls back to etaNudge2, then to zero (stop optimizing) if unsuccessful.
etaNudge2	This is the second eta nudge. By default it is qnorm(1-0.05/2)*sqrt(3/5), which is the n=3 quadrature point (excluding zero) times by the 0.95% normal region
etaRestart	Number of Omega draws the inner restart cascade tries once the 'etaNudge'/'etaNudge2' restarts are spent and the ETA solve is still not converged. Every nudge sets EVERY ETA to the same constant, which explores poorly when the inner problem has more than one basin; a draw from Omega is a starting point from the distribution the ETAs actually come from. The draws are taken once per fit, seeded from 'seed' (so the objective stays a function of theta alone and the fit stays reproducible), and are only read after an inner solve has already failed – a fit whose inner solves converge never pays for them. Use 0 to disable. This applies to 'innerOpt="trust"' (the default for a normal endpoint), which reports a convergence verdict per solve. 'n1qn1' reports none, so its own restart cascade is unchanged.
nRetries	If FOCEi doesn't fit with the current parameter estimates, randomly sample new parameter estimates and restart the problem. This is similar to 'PsN' resampling.
seed	Integer seed (default '42') used to make a FOCEi fit reproducible and self-contained. The fit (including the 'mceta' Monte-Carlo initial-ETA draws, which pull from rxode2's threefry engine) runs inside [rxode2::rxWithSeed()], so it neither depends on the ambient RNG state nor advances/leaks it – repeated fits in the same session, and fits following other estimation methods, give identical results.
resetThetaCheckPer	represents objective function % percentage below which resetThetaP is checked.
etaMat	Initial (or final) ETA estimates; can also be a prior fit, whose final ETAs are then used as initial values. By default, uses the last fit's ETAs if supplied, else all ETAs start at zero ('NULL'). 'NA' disables reuse from a prior fit.
repeatGillMax	If the tolerances were reduced when calculating the initial Gill differences, the Gill difference is repeated up to a maximum number of times defined by this parameter.
stickyRecalcN	The number of bad ODE solves before reducing the atol/rtol for the rest of the problem.
outerMaxOdeRecalc	Maximum number of times to reduce the ODE tolerances for a single subject and retry when the analytic outer (augmented sensitivity) solve fails. Tracked separately from 'maxOdeRecalc', which governs the inner problem. A subject that solves after loosening still contributes an analytic gradient instead of dropping the whole gradient to finite differences.
outerOdeRecalcFactor	The factor the atol/rtol is loosened by on each analytic outer retry; the outer counterpart of 'odeRecalcFactor'.
outerStickyRecalcN	The number of bad analytic outer solves for a subject before its loosened tolerance is kept for the rest of the problem; the outer counterpart of 'stickyRecalcN'.
indTolRelax	When 'TRUE' (default), only subjects whose ODE solve produced NaN/Inf have their tolerances relaxed, and the relaxed tolerance persists across optimizer calls (sticky). When 'FALSE', all subjects have their tolerances relaxed on each retry and tolerances are reset afterward.
gradProgressOfvTime	This is the time for a single objective function evaluation (in seconds) to start progress bars on gradient evaluations
addProp	Type of additive-plus-proportional error: '"combined1"', where standard deviations add: y = f + (a + b\times f^c) \times \varepsilon ; or '"combined2"', where variances add: y = f + \sqrt{a^2 + b^2\times f^{2\times c}} \times \varepsilon . Here y = observed, f = predicted, a = additive sd, b = proportional/power sd, c = power exponent (1 in the proportional case).
badSolveObjfAdj	The objective function adjustment when the ODE system cannot be solved. It is based on each individual bad solve.
compress	Should the object have compressed items
rxControl	'rxode2' ODE solving options during fitting, created with 'rxControl()'
sigdigTable	Significant digits in the final output table. If not specified ('NULL'), it defaults to 'sigdig'.
fallbackFD	Fallback to the finite differences if the sensitivity equations do not solve.
smatPer	Percentage of failed per-individual parameter gradients (replaced with the overall parameter gradient) out of the total ('ntheta*nsub') above which the S matrix is considered bad.
sdLowerFact	Factor multiplying the estimate when the lower bound is zero for a standard-deviation error parameter (add.sd, prop.sd, etc); e.g. estimate 0.15 with lower bound 0 assumes a lower bound of 0.00015. '0' disables this.
zeroGradFirstReset	When 'TRUE' (default), reset a zero first gradient to 'sqrt(.Machine$double.eps)' instead of erroring; 'FALSE' errors; 'NA' ignores it only on the last reset attempt.
zeroGradRunReset	When 'TRUE' (default), reset a zero gradient encountered mid-run to 'sqrt(.Machine$double.eps)' instead of erroring.
zeroGradBobyqa	When 'TRUE' (default), a zero-gradient reset switches to the gradient-free bobyqa method; 'NA' only does so for the first zero gradient.
mceta	Monte Carlo sampling for the best initial ETA estimate (based on 'omega'): '-2' (default) uses the Almquist (2015) Eq-48 extrapolation 'eta^0 = eta* + (d eta*/d theta)(theta_new - theta_old)' when the analytic gradient supplies 'd eta*/d theta' ('fast = TRUE'), accepting the extrapolated eta only when it is within the standardized-eta reset bound (else keeping the last eta, or resetting to 0 when that is also out of bound); '-1' jumps between the extrapolated eta and eta=0, keeping the better; both '-2' and '-1' fall back to keeping the last eta when no analytic 'd eta*/d theta' is available ('fast = FALSE'). '0' uses eta=0 for each inner optimization; for 'n>0', eta=0 and n-1 etas sampled from omega are each evaluated and the best (by inner objective) starts the inner optimization. The carried last eta is deliberately not one of the ‘n>0' candidates – it is the previous iteration’s converged conditional mode, so it would win for every subject and 'n>0' would reduce to the keep-last behavior of '-1'/'-2'. When a sampled eta wins, the inner problem is also solved from eta=0 and the better converged result kept – compared on the marginal objective the fit reports, which carries the Laplace 'log|H|' term, not on the inner objective the optimizer minimizes – so no inner solve ends above the one '0' would have reached. The search is skipped while the outer gradient is being differenced, where the eta is pinned to the central evaluation's mode.
warm	Seeding of the n1qn1 inner-optimization Hessian: '"calc"' (default) warm-starts each inner problem with the eta Hessian calculated at the starting eta and the current theta; since theta moves between outer evaluations it is always recalculated, never reused from an earlier round. '"save"' restarts from the curvature n1qn1 built during the subject's previous inner solve. '"none"' lets n1qn1 initialize its own diagonal Hessian. Ignored by 'innerOpt = "trust"', which always supplies its own exact Hessian.
nAGQ	Number of Gauss-Hermite adaptive quadrature points. '0' disables AGQ; '1' is equivalent to Laplace. Cost grows quickly with ETAs: once the EBE is found, expect 'nAGQ^neta' (even 'nAGQ') or '(nAGQ^neta)-1' (odd 'nAGQ') additional evaluations per subject.
agqLow	The lower bound for adaptive quadrature log-likelihood. By default this is -Inf; in the original nlmixr's gnlmm it was -700.
agqHi	The upper bound for adaptive quadrature log-likelihood. By default this is Inf; in the original nlmixr's gnlmm was 400.
sensMethod	Method used to compute the ODE parameter sensitivities. '"forward"' uses the classic variational (forward) sensitivity ODEs; '"default"' is the same thing.
linCmtSensCarry	'"auto"' (default) substitutes the exact sensitivity-carry gradient for a 'linCmt()' parameter driven by both an eta and a time-varying covariate (needs an rxode2 with the carry sentinels; silently keeps the standard gradient otherwise); '"none"' always keeps the standard gradient.
zeroTheta	Positive magnitude (default '0.001') used to nudge a population parameter ('theta') whose initial estimate is exactly '0' off zero before estimation. FOCEi scales a linear parameter by its native magnitude '|init|', which is '0' (no scale) for a zero initial estimate, so the parameter is moved to '+zeroTheta' when it is within the parameter's bounds, otherwise '-zeroTheta'; if neither is within the bounds an error is raised. Fixed parameters (including those fixed at '0') are left untouched.
boundedTransform	When 'TRUE' (default), bounded parameters are transformed for unbounded optimization methods and back-transformed for final estimates. 'FALSE' optimizes on the original scale with bounds passed to the optimizer. 'NA' transforms for optimization but skips the final back-transform.

Details

Custom outer optimizers receive control$hessian(par, relStep=1e-3). It settles the requested point and assembles the reported objective's Hessian in the existing C++ sensitivity pool. Third-order terms are obtained by differencing second-order sensitivities in ETA directions. The result uses optimizer coordinates and objective scaling and retains negative curvature. This requires fast=TRUE. M2/M3/M4 censoring uses the analytical-SE censOption="gauss" convention. Censored "laplace" curvature, priors, clipped AGQ and estimated transformations are unsupported. Unsuccessful inner solves and an active variance floor also make curvature unavailable.

Uses R's L-BFGS-B (optim) for the outer problem and BFGS n1qn1 (restoring the prior individual Hessian) for the inner problem, which is left unscaled since eta estimates start near zero. The covariance step is performed on the unscaled problem, so its condition number may differ from the scaled problem's.

Value

The control object that changes the options for the FOCEi family of estimation methods

Author(s)

Matthew L. Fidler

References

Gill, P.E., Murray, W., Saunders, M.A., & Wright, M.H. (1983). Computing Forward-Difference Intervals for Numerical Optimization. Siam Journal on Scientific and Statistical Computing, 4, 310-321.

Shi, H.M., Xie, Y., Xuan, M.Q., & Nocedal, J. (2021). Adaptive Finite-Difference Interval Estimation for Noisy Derivative-Free Optimization.

See Also

optim

n1qn1

rxSolve

Other Estimation control: nlmixr2NlmeControl(), saemControl()

nlmixr2est documentation built on Sept. 20, 2026, 9:08 a.m.