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,
  indOwnAlloc = 0L,
  nDelayState = 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. nStud from control is the replicate count, so it lands here rather than in the subject count.
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.
indOwnAlloc: TRUE/1 when every individual gets its own event and solve arrays rather than pointing into the global buffers. These are allocated on top of gsolve, so they are real extra memory. Taken from the model's evid_ flag when model is given, and overridden by control$indOwnAlloc when that is set.
nDelayState: Number of ODE states delay() looks back on. Drives the per-individual dense-history buffer, which grows by doubling inside the solve, so it is charged as a documented bound rather than an exact mirror. Taken from model when given.

Value

A named list of class "rxMemoryEstimate" whose elements are raw byte counts plus outputData, ramBytes, freeRamBytes, total, sizeofInd, and rxLlikSaveSize. total is the number of bytes actually allocated, so it excludes gsolve_n0 (the ODE state output matrix), which is reported separately but is already part of gsolve.

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: 21.14 KB
#> 
#>   gall_times (event time/dv/amt/ii/limit)    6.80 KB (32.2%)
#>   outputData (estimated returned data)       5.47 KB (25.9%)
#>   gsolve (double buffer total)               4.39 KB (20.8%)
#>     |_ n0: ODE state output matrix           2.72 KB (12.9%)
#>   gevid (event IDs)                          2.04 KB ( 9.7%)
#>   inds_global (per-subject structs)          1.66 KB ( 7.9%)
#>   gon (int buffer)                           712 B ( 3.4%)
#>   gInfusionRate (per-thread infusion)        28 B ( 0.1%)
#>   gpars (parameters)                         24 B ( 0.1%)
#>   ordId (subject ordering)                   4 B ( 0.0%)
#>   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%)
#>   indOwnAlloc (per-individual event/solve arrays) 0 B ( 0.0%)
#>   gSampleCov (resampled covariate index)     0 B ( 0.0%)
#>   gEtaPre (pre-generated eta draws)          0 B ( 0.0%)
#>   delayHist (per-individual delay() history, bound) 0 B ( 0.0%)
#>   linCmtRateHist (per-individual linCmt rates, bound) 0 B ( 0.0%)
#> 
#>   Subjects: 1  |  sizeof(rx_solving_options_ind): 1664 B  |  0.0% of RAM (16.77 GB)  |  0.0% of available memory (14.89 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: 26.00 KB
#> 
#>   gsolve (double buffer total)               9.07 KB (34.9%)
#>     |_ n0: ODE state output matrix           2.72 KB (10.5%)
#>   gall_times (event time/dv/amt/ii/limit)    6.80 KB (26.1%)
#>   outputData (estimated returned data)       5.47 KB (21.0%)
#>   gevid (event IDs)                          2.04 KB ( 7.8%)
#>   inds_global (per-subject structs)          1.66 KB ( 6.4%)
#>   gon (int buffer)                           736 B ( 2.8%)
#>   gInfusionRate (per-thread infusion)        112 B ( 0.4%)
#>   gomega (omega matrix)                      64 B ( 0.2%)
#>   gpars (parameters)                         24 B ( 0.1%)
#>   gEtaPre (pre-generated eta draws)          16 B ( 0.1%)
#>   ordId (subject ordering)                   4 B ( 0.0%)
#>   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%)
#>   indOwnAlloc (per-individual event/solve arrays) 0 B ( 0.0%)
#>   gSampleCov (resampled covariate index)     0 B ( 0.0%)
#>   delayHist (per-individual delay() history, bound) 0 B ( 0.0%)
#>   linCmtRateHist (per-individual linCmt rates, bound) 0 B ( 0.0%)
#> 
#>   Subjects: 1  |  sizeof(rx_solving_options_ind): 1664 B  |  0.0% of RAM (16.77 GB)  |  0.0% of available memory (14.89 GB available)

# }