Run aquatic model ensemble

Usage

run_aeme(
  aeme,
  model,
  path,
  args = character(),
  return_type = c("aeme", "exec_result", "both", "none"),
  ens_n = 1,
  model_controls = NULL,
  verbose = getOption("AEME.inform", FALSE),
  debug = FALSE,
  timeout = Inf,
  parallel = FALSE,
  ncores,
  check_output = FALSE,
  keep_diag = TRUE,
  extra_vars = NULL,
  sed_layers = NULL,
  zone_summary = FALSE
)

Arguments

aeme: Aeme object.
model: character vector; models to use. One or more of "dy_cd", "glm_aed", "gotm_wet", "simstrat_aed2". Defaults to all models if not found in aeme.
path: character; directory where input files are located. Defaults to the path stored in aeme, or the current working directory if not set.
args: Character vector, arguments to the command.
return_type: character; one of "aeme" (default), "exec_result", "both", or "none". "aeme" returns the aeme object with model output loaded; "exec_result" returns the raw processx::run() result(s) for each model; "both" returns a list with both aeme and exec_result elements; "none" returns NULL invisibly (useful when only the model run's side effects, i.e. the output files, are wanted).
ens_n: numeric; ensemble number to allocate to model output which is loaded. Defaults to 1.
model_controls: data.frame; model configuration, typically loaded via get_model_controls().
verbose: logical; print model output to console. Defaults to getOption("AEME.inform", FALSE).
debug: logical; write debug log (Only DYRESM). Defaults to FALSE.
timeout: Timeout for the process, in seconds, or as a difftime object. If it is not finished before this, it will be killed.
parallel: logical; run models in parallel. Defaults to FALSE.
ncores: integer; number of cores to use for parallelization. Defaults to min(c(detectCores() - 1, length(model))).
check_output: logical; check model output after running? Defaults to FALSE.
keep_diag: logical; keep the diag (diagnostic/scalar) and sediment sub-lists of each model's output (variables with dimensions other than time or depth x time, keyed by raw model names). Default TRUE; set to FALSE to save memory.
extra_vars: character; for GLM-AED, which sediment, flux and diagnostic variables beyond the standard set to read from output.nc. NULL (default) reads all of them. "none" reads none. Otherwise AEME names from glm_extra_vars (e.g. "SED_temp"), raw netCDF names, and/or the keywords "sediment" / "diag". Unrequested variables are never read, which keeps ensemble output small. See read_glm_output().
sed_layers: integer; GLM-AED sediment layers to keep for variables with a sediment-layer dimension (SED_temp). NULL keeps all. See read_glm_output().
zone_summary: logical; for GLM-AED, also add an area-weighted lake-wide series for each requested sediment-zone variable. See read_glm_output(). Default FALSE.

Value

Depends on return_type – an aeme object with model output loaded ("aeme"), the raw processx::run() result(s) ("exec_result"), a list with both ("both"), or NULL invisibly ("none").

Examples

aeme_file <- system.file("extdata/aeme.rds", package = "AEME")
aeme <- readRDS(aeme_file)
path <- tempdir()
model_controls <- get_model_controls()
model <- c("glm_aed")
aeme <- build_aeme(path = path, aeme = aeme, model = model,
                   model_controls = model_controls, ext_elev = 5)
#> Warning: ! `SIL_rsi`: SIL_rsi is constant across all rows -- this may be a placeholder
#>   value.
#> ℹ Check raw data or unit conversion for this variable.
#> 
#> ── Calculating water balance ──
#> 
#> Resolving water level
#>   ℹ Using observed water level
#> ! Missing values in observed water level
#> ℹ Estimating surface water temperature
#> ✔ Estimating surface water temperature [26ms]
#> 
#> Estimating lake water levels for glm_aed
#>   ℹ Optimizing parameters for water balance
#>   ✔ Optimization Complete: C = 0.3343, h_inv = 23.4915, Final RMSE = 0.1431
#> ℹ Correcting water balance using estimated outflows (method = 2).
#> 
#> ── Building GLM-AED for lake wainamu ──
#> 
#> ✔ GLM nml validation completed - no issues detected.
if (FALSE) { # \dontrun{
aeme <- run_aeme(aeme)

# Plot model output - temperature by default
plot_output(aeme)
} # }