Getting/setting a stics_wrapper options list with initialized fields

This function returns a default options list if called with no arguments, or a pre-formated model option list with checks on the inputs.

stics_wrapper_options(
  javastics = NULL,
  stics_exe = "modulostics",
  workspace = NULL,
  parallel = FALSE,
  cores = NA,
  time_display = FALSE,
  verbose = TRUE,
  force = FALSE,
  successive = NULL,
  javastics_path = lifecycle::deprecated(),
  data_dir = lifecycle::deprecated(),
  successive_usms = lifecycle::deprecated(),
  ...
)

Arguments

javastics: Path of JavaStics. Optional, needed if stics_exe is not provided, or if stics_exe relates to an exe in the javastics_path (see details)
stics_exe: The name, executable or path of the stics executable to use (optional, default to "modulostics", see details)
workspace: Path of the workspace containing the Stics (txt) input files or path of a single directory containing one sub-folder per USM (named as the USM names) with Stics (txt) input files in them.
parallel: Boolean. Is the computation to be done in parallel ?
cores: Number of cores to use for parallel computation.
time_display: Display time
verbose: Logical value (optional), TRUE to display informations during execution, FALSE otherwise (default)
force: Boolean. Don't check javastics, stics_exe and workspace (default to FALSE, see details)
successive: List of vectors containing the names of the UMSs to consider as successive (e.g. list(c("usm1.1","usm1.2"),c("usm2.1","usm2.2")) defines 2 successions usm1.1->usm1.2 and usm2.1->usm2.2)
javastics_path: javastics_path is no longer supported, use javastics instead.
data_dir: data_dir is no longer supported, use workspace instead.
successive_usms: successive_usms is no longer supported, use successive instead.
...: Add further arguments set the options list values

Value

A list containing Stics model stics_wrapper options

Details

stics_exe may be :

a model name pointing to a stics executable as done in JavaStics, e.g. "modulostics" for stics_modulo.exe, the standard version of the model shipping with JavaStics;
a stics executable file available from the bin folder in JavaStics, e.g. "stics_modulo.exe";
a path to a stics executable file, eg. "C:/Users/username/Desktop/stics.exe".

javastics must be provided for case (1) and (2).

If force=TRUE, checks are not done for javastics, stics_exe and workspace. In this case, they are returned as is, and will be checked (and potentially updated to match the right stics executable) only at execution of stics_wrapper(). This option is used for portability, when e.g. stics_wrapper_options() outputs are sent to a remote.

Examples

if (FALSE) {
# Getting simulations options and defaults values for the stics_wrapper
# function

stics_wrapper_options()

#> $javastics
#> [1] "unknown"
#>
#> $stics_exe
#> [1] "modulostics"
#>
#> $workspace
#> [1] "unknown"
#>
#> $parallel
#> [1] FALSE
#>
#> $cores
#> [1] NA
#>
#> $time_display
#> [1] FALSE
#>
#> $verbose
#> [1] TRUE
#>
#> $force
#> [1] FALSE

# Setting mandatory simulations options
javastics <- "path/to/javastics"
data_path <- "path/to/data_directory"
sim_options <- stics_wrapper_options(
  javastics = javastics,
  workspace = data_path
)

# Changing default values (e.g. parallel):
sim_options <- stics_wrapper_options(
  javastics = javastics,
  workspace = data_path, parallel = TRUE
)

#> $javastics
#> [1] "path/to/JavaSTICS-v85"
#>
#> $stics_exe
#> [1] "path/to/JavaSTICS-v85/bin/stics_modulo.exe"
#>
#> $workspace
#> [1] "path/to/data"
#>
#> $parallel
#> [1] TRUE
#>
#> $cores
#> [1] NA
#>
#> $time_display
#> [1] FALSE
#>
#> $verbose
#> [1] TRUE
#>
#> $force
#> [1] FALSE

# Using the `force` argument to keep the inputs as is:
sim_options <- stics_wrapper_options(
  javastics = javastics,
  data_dir = data_path, force = TRUE
)

#> $javastics
#> [1] "path/to/JavaSTICS-v85"
#>
#> $stics_exe
#> [1] "modulostics"
#>
#> $workspace
#> [1] "path/to/data"
#>
#> $parallel
#> [1] FALSE
#>
#> $cores
#> [1] NA
#>
#> $time_display
#> [1] FALSE
#>
#> $verbose
#> [1] TRUE
#>
#> $force
#> [1] TRUE

# This will be checked and modified by a `do.call()` in `stics_wrapper()`:
do.call(stics_wrapper_options, model_options)

#> $javastics
#> [1] "path/to/JavaSTICS-v85"
#>
#> $stics_exe
#> [1] "path/to/JavaSTICS-v85/bin/stics_modulo.exe"
#>
#> $workspace
#> [1] "path/to/data"
#>
#> $parallel
#> [1] FALSE
#>
#> $cores
#> [1] NA
#>
#> $time_display
#> [1] FALSE
#>
#> $verbose
#> [1] TRUE
#>
#> $force
#> [1] FALSE

# Note the `stics_exe` path that was modified and checked to the path were
# it was found.
}