Run LPJmL model — run_lpjml • lpjmlkit

Runs LPJmL using "config_*.json" files written by write_config(). write_config() returns a tibble that can be used as an input (see x). It contains the details to run single or multiple (dependent/subsequent) model runs.

run_lpjml(
  x,
  model_path = ".",
  sim_path = NULL,
  run_cmd = "srun --propagate",
  parallel_cores = 1,
  write_stdout = FALSE,
  raise_error = TRUE,
  output_path = NULL
)

Arguments

x: A tibble with at least one column named "sim_name". Each simulation gets a separate row. Optional run parameters are "order" and "dependency" which are used for subsequent simulations (see details). write_config() returns a tibble in the required format. OR provide a character string (vector) with the file name of one or multiple generated configuration file(s).
model_path: Character string providing the path to LPJmL (equal to LPJROOT environment variable). Defaults to "."
sim_path: Character string defining path where all simulation data are written, including output, restart and configuration files. If NULL, model_path is used. See also write_config
run_cmd: Character string defining the command used to execute lpjml (see details). Defaults to "srun --propagate" (compute ondes of old cluster at PIK). Change to "mpirun" for HPC2024 at PIK.
parallel_cores: Integer defining the number of available CPU cores/nodes for parallelization. Defaults to 1 (no parallelization). Please note that parallelization is only supported for SLURM jobs and not for interactive runs.
write_stdout: Logical. If TRUE, stdout as well as stderr files are written. If FALSE (default), these are printed instead. Within a SLURM job write_stdout is automatically set to TRUE.
raise_error: Logical. Whether to raise an error if sub-process has non-zero exit status. Defaults to TRUE.
output_path: Argument is deprecated as of version 1.0; use sim_path instead.

Value

See x, extended by columns "type", "job_id" and "status".

Details

x: A tibble for x that has been generated by write_config() and can look like the following examples can supplied:

sim_name

scen1_spinup

scen2_transient

To perform subsequent or rather dependent runs the optional run parameter "dependency" needs to be provided within the initial tibble supplied as param to write_config().

sim_name	order	dependency
scen1_spinup	1	NA
scen2_transient	2	scen1 _spinup

As a shortcut it is also possible to provide the config file "config_*.json" as a character string or multiple config files as a character string vector directly as the x argument to run_lpjml.
Also be aware that the order of the supplied config files is important (e.g. make sure the spin-up run is run before the transient one).

run_cmd: The run_cmd argument is used to define the command to execute LPJmL. This is needed because the LPJmL executable can not directly be used on all machines. Which command has to be used depends on the software installed. Further information on this can be found in the INSTALL file of LPJmL. To determine the correct command, check the lpj_submit.sh file in the bin directory of LPJmL. Using PIK infrastrucure the command is srun for the hpc2015 and mpirun for the hpc2024. To facilitate usage on the interactive (login) nodes, no command is needed for hpc2015. For the hpc2024 the command remains mpirun (in these cases run_lpjml adjusts run_cmd accordingly).

Examples


if (FALSE) {
library(tibble)

model_path <- "./LPJmL_internal"
sim_path <-"./my_runs"

# Basic usage
my_params1 <- tibble(
  sim_name = c("scen1", "scen2"),
  startgrid = c(27410, 27410),
  river_routing = c(FALSE, FALSE),
  random_seed = c(42, 404),
  `pftpar[[1]]$name` = c("first_tree", NA),
  `param$k_temp` = c(NA, 0.03),
  new_phenology = c(TRUE, FALSE)
)

config_details1 <- write_config(my_params1, model_path, sim_path)

 run_details1 <- run_lpjml(
  x = config_details1,
  model_path = model_path,
  sim_path = sim_path
)

run_details1
#   sim_name      job_id   status
#   <chr>           <int>  <chr>
# 1 scen1              NA  run
# 2 scen2              NA  run


# With run parameters dependency and order being set (also less other
#   parameters than in previous example)
my_params2 <- tibble(
  sim_name = c("scen1", "scen2"),
  startgrid = c(27410, 27410),
  river_routing = c(FALSE, FALSE),
  random_seed = c(42, 404),
  dependency = c(NA, "scen1_spinup")
)

config_details2 <- write_config(my_params2, model_path, sim_path)

run_details2 <- run_lpjml(config_details2, model_path, sim_path)

run_details2
#   sim_name        order dependency   type       job_id   status
#   <chr>           <dbl> <chr>        <chr>      <chr>    <chr>
# 1 scen1_spinup        1 NA           simulation NA       run
# 2 scen1_transient     2 scen1_spinup simulation NA       run


# Same but by using the pipe operator
library(magrittr)

run_details2 <- tibble(
  sim_name = c("scen1_spinup", "scen1_transient"),
  random_seed = as.integer(c(1, 42)),
  dependency = c(NA, "scen1_spinup")
) %>%
  write_config(model_path, sim_path) %>%
  run_lpjml(model_path, sim_path)


# Shortcut approaches
run_details3 <- run_lpjml(
  x = "./config_scen1_transient.json",
  model_path = model_path,
  sim_path = sim_path
)

run_details4 <- run_lpjml(
  c("./config_scen1_spinup.json", "./config_scen1_transient.json"),
  model_path,
  sim_path
)

}