run_lpjml: Run LPJmL model

In lpjmlkit: Toolkit for Basic LPJmL Handling

Run LPJmL model

Description

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.

Usage

run_lpjml(
  x,
  model_path = ".",
  sim_path = NULL,
  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
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.

Details

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

Value

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

Examples

## Not run: 
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
)


## End(Not run)

lpjmlkit documentation built on March 31, 2023, 9:35 p.m.