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

[Deprecated] javastics_path is no longer supported, use javastics instead.

data_dir

[Deprecated] data_dir is no longer supported, use workspace instead.

successive_usms

[Deprecated] 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 :

  1. 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;

  2. a stics executable file available from the bin folder in JavaStics, e.g. "stics_modulo.exe";

  3. 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.
}