Skip to contents

Run an ensemble of parameter sets

Source: R/run_aeme_ensemble.R
run_aeme_ensemble.Rd

Runs a model once per supplied parameter set and stores every member's output on the returned Aeme object as output(aeme)$ens_001 ... ens_00k, alongside output(aeme)$n_members. That is the structure get_var() reads with ens_n, and write_aeme_parquet() exports.

This runs parameter sets you supply: it does not sample them. Drawing sets from parameter bounds and extracting a posterior from a pestpp-ies calibration are provided by the aemetools package, which passes its sets through here. Sets that use zone ratios (zone_ratio_param()) work as they are: input_model_parameters() expands them.

Each member is one input_model_parameters() followed by one run_aeme(), so a member's cost is a single model run. A member that errors, times out or produces no output is dropped with a warning and the survivors are renumbered.

A model can also fail without saying so. GLM, for instance, exits normally when an unphysical parameter combination drains the lake: the water level goes to zero or below and the rest of the output is NA, but the run reports success. With drop_incomplete = TRUE (the default) a member is also dropped when its water level (LKE_lvlwtr) reaches zero or is NA at any timestep, spin-up included. This needs LKE_lvlwtr among the model's output variables; if it was not written the check cannot be made and the member is kept.

Usage

run_aeme_ensemble(
  aeme,
  model,
  param_sets,
  path,
  parallel = FALSE,
  ncore = NULL,
  model_controls = NULL,
  timeout = Inf,
  drop_incomplete = TRUE,
  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.

param_sets

the parameter sets to run. Either a list of long param data.frames, one per member (such as the aeme_param_sets object returned by aemetools::pest_posterior_params()), or a single long data.frame with an ensemble column identifying each member. Each member needs the columns model, file, name and value, as in parameters() (a group and index are used where present). Names, or the ensemble ids, are kept as the member labels.

path

character; directory where input files are located. Defaults to the path stored in aeme, or the current working directory if not set.

parallel

logical; run members in parallel, each worker in its own copy of the model directory. Default FALSE. The workers load the installed version of AEME.

ncore

integer; number of workers when parallel = TRUE. NULL (default) uses one fewer than the cores available, and never more than the number of members.

model_controls

data.frame; model configuration, typically loaded via get_model_controls().

timeout

Timeout for the process, in seconds, or as a difftime object. If it is not finished before this, it will be killed.

drop_incomplete

logical; drop members whose water level reached zero or went NA (a lake that dried out or a model that stopped part-way), as well as members that errored. Default TRUE. FALSE keeps them, NA-padded.

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

The Aeme object with the ensemble stored in output(). When param_sets was named, the labels of the surviving members are on attr(output(aeme), "realisation").

See also

add_param(), input_model_parameters(), run_aeme(), write_aeme_parquet()

Examples

if (FALSE) { # \dontrun{
aeme_file <- system.file("extdata/aeme.rds", package = "AEME")
aeme <- readRDS(aeme_file)
path <- tempdir()
aeme <- build_aeme(path = path, aeme = aeme, model = "glm_aed",
                   ext_elev = 5)

# Ten members, each scattering the default values by up to 10 %
data("aeme_parameters", package = "AEME")
param <- aeme_parameters[aeme_parameters$model == "glm_aed", ]
param_sets <- lapply(1:10, function(i) {
  p <- param
  p$value <- p$value * runif(nrow(p), 0.9, 1.1)
  p
})

aeme <- run_aeme_ensemble(aeme, model = "glm_aed", path = path,
                          param_sets = param_sets)
output(aeme)$n_members
} # }