Estimate memory required by rxSolve() for a given dataset and model

Accepts either a pre-summarized per-ID table (an rxMemSummary or any data.frame with nobs and ndoses columns) or a full event-table data.frame with an evid column. Model dimensions can be supplied via a compiled rxode2 model object or overridden individually.

Usage

rxMemoryEstimate(
  dat,
  model = NULL,
  control = NULL,
  neq = 1L,
  stateSize = neq,
  nlhs = 0L,
  npars = neq,
  neta = 0L,
  neps = 0L,
  ncov = 0L,
  nsim = 1L,
  cores = 1L,
  nMtime = 0L,
  extraCmt = 0L,
  linB = FALSE,
  nLlik = 0L,
  nIndSim = NULL,
  numLinSens = 0L,
  numLin = 0L,
  stiff = NA_integer_,
  doIndLin = 0L
)

Arguments

dat: A rxMemSummary, a data.frame with nobs/ndoses columns, or a full event-table data.frame with an evid column. This can also be a serialized solve state file path, a solve state bundle list containing an events element, or an rxSolve object (using its stored solve events).
model: Optional rxode2 model object. When supplied, neq, nlhs, npars, extraCmt, linB, nMtime, nLlik, and nIndSim are extracted automatically.
control: Optional rxControl object. When supplied, cores, nsim, neta (from omega), neps (from sigma), and nLlik (adjusted by nLlikAlloc) are overridden automatically.
neq: Number of ODE states.
stateSize: Effective state.size() seen by the solver. Equals neq for pure ODE models; may differ for linCmt-only models. Defaults to neq.
nlhs: Number of LHS (calculated) output variables.
npars: Number of model parameters (drives gpars size).
neta: Number of random effects (etas).
neps: Number of residual-error levels (epsilons).
ncov: Number of time-varying covariates.
nsim: Number of simulations.
cores: Number of parallel OMP threads.
nMtime: Number of model measurement times.
extraCmt: Extra compartments (0, 1 = depot, 2 = depot+central).
linB: TRUE/1 if using a linear-compartment model.
nLlik: Number of log-likelihood terms (FOCEi use).
nIndSim: Per-individual simulation count. Defaults to neta + neps when not supplied explicitly.
numLinSens: Number of linear sensitivity parameters (FOCEi + linCmt).
numLin: Number of linear compartment terms (FOCEi + linCmt).
stiff: Solving method as an integer (odeMethodToInt); only 3 ("indLin") allocates anything extra. Taken from control when given, and overridden to 3 for any matExp() model, since rxSolve() force-selects that method for one whatever the control says.
doIndLin: Which matrix-exponential driver runs: 0 not a matExp() model, 1 pure matrix exponential, 2 plus a state-free indLin() forcing, 3/4 true inductive linearization. Taken from model when given. These cost very different amounts, so it is worth getting right.

Value

A named list of class "rxMemoryEstimate" whose elements are raw byte counts plus outputData, ramBytes, freeRamBytes, total, sizeofInd, and rxLlikSaveSize.

Details

The byte counts are computed by rxMemoryComponents_() which calls the same rxFillMemLayout() used by the real allocator, so any change to the allocation formulas propagates here automatically.

Examples


# \donttest{

mod <- rxode2::rxode2({
  d/dt(depot)  <- -ka * depot
  d/dt(center) <- ka * depot - cl / v * center
  cp           <- center / v
})
#>  
#>  

ev <- rxode2::et(amt = 100, ii = 24, until = 168) |>
  rxode2::et(seq(0, 168, by = 1))

# Basic estimate from event table and model
rxMemoryEstimate(as.data.frame(ev), model = mod)
#> rxSolve() memory estimate
#>   Total: 23.83 KB
#> 
#>   gall_times (event time/dv/amt/ii/limit)    6.80 KB (28.5%)
#>   outputData (estimated returned data)       5.47 KB (23.0%)
#>   gsolve (double buffer total)               4.39 KB (18.4%)
#>     |_ n0: ODE state output matrix           2.72 KB (11.4%)
#>   gevid (event IDs)                          2.04 KB ( 8.6%)
#>   inds_global (per-subject structs)          976 B ( 4.1%)
#>   gon (int buffer)                           712 B ( 3.0%)
#>   ordId (subject ordering)                   680 B ( 2.9%)
#>   gpars (parameters)                         24 B ( 0.1%)
#>   gInfusionRate (per-thread infusion)        16 B ( 0.1%)
#>   gcov (covariates)                          0 B ( 0.0%)
#>   gomega (omega matrix)                      0 B ( 0.0%)
#>   gsigma (sigma matrix)                      0 B ( 0.0%)
#>   gall_timesS (extra sim times)              0 B ( 0.0%)
#>   indLinExpCache (per-thread exponential cache) 0 B ( 0.0%)
#>   indLinWork (per-thread indLin scratch)     0 B ( 0.0%)
#> 
#>   Subjects: 1  |  sizeof(rx_solving_options_ind): 976 B  |  0.0% of RAM (16.77 GB)  |  0.0% of available memory (14.84 GB available)

# With rxControl: population simulation with omega and 4 cores
ctrl <- rxode2::rxControl(
  cores = 4L,
  omega = lotri::lotri(eta.ka ~ 0.09, eta.cl ~ 0.04)
)
rxMemoryEstimate(as.data.frame(ev), model = mod, control = ctrl)
#> rxSolve() memory estimate
#>   Total: 28.65 KB
#> 
#>   gsolve (double buffer total)               9.07 KB (31.7%)
#>   gall_times (event time/dv/amt/ii/limit)    6.80 KB (23.7%)
#>   outputData (estimated returned data)       5.47 KB (19.1%)
#>     |_ n0: ODE state output matrix           2.72 KB ( 9.5%)
#>   gevid (event IDs)                          2.04 KB ( 7.1%)
#>   inds_global (per-subject structs)          976 B ( 3.4%)
#>   gon (int buffer)                           736 B ( 2.6%)
#>   ordId (subject ordering)                   680 B ( 2.4%)
#>   gomega (omega matrix)                      64 B ( 0.2%)
#>   gInfusionRate (per-thread infusion)        64 B ( 0.2%)
#>   gpars (parameters)                         24 B ( 0.1%)
#>   gcov (covariates)                          0 B ( 0.0%)
#>   gsigma (sigma matrix)                      0 B ( 0.0%)
#>   gall_timesS (extra sim times)              0 B ( 0.0%)
#>   indLinExpCache (per-thread exponential cache) 0 B ( 0.0%)
#>   indLinWork (per-thread indLin scratch)     0 B ( 0.0%)
#> 
#>   Subjects: 1  |  sizeof(rx_solving_options_ind): 976 B  |  0.0% of RAM (16.77 GB)  |  0.0% of available memory (14.84 GB available)

# }