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

Accepts either a pre-summarised 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
)

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

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.71 KB
#> 
#>   gall_times (event time/dv/amt/ii/limit)    6.80 KB (28.7%)
#>   outputData (estimated returned data)       5.47 KB (23.1%)
#>   gsolve (double buffer total)               4.38 KB (18.5%)
#>     |_ n0: ODE state output matrix           2.72 KB (11.5%)
#>   gevid (event IDs)                          2.04 KB ( 8.6%)
#>   inds_global (per-subject structs)          872 B ( 3.7%)
#>   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%)
#> 
#>   Subjects: 1  |  sizeof(rx_solving_options_ind): 872 B  |  0.0% of RAM (16.77 GB)  |  0.0% of free RAM (15.23 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.48 KB
#> 
#>   gsolve (double buffer total)               9.01 KB (31.6%)
#>   gall_times (event time/dv/amt/ii/limit)    6.80 KB (23.9%)
#>   outputData (estimated returned data)       5.47 KB (19.2%)
#>     |_ n0: ODE state output matrix           2.72 KB ( 9.6%)
#>   gevid (event IDs)                          2.04 KB ( 7.2%)
#>   inds_global (per-subject structs)          872 B ( 3.1%)
#>   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%)
#> 
#>   Subjects: 1  |  sizeof(rx_solving_options_ind): 872 B  |  0.0% of RAM (16.77 GB)  |  0.0% of free RAM (15.23 GB available)

# }