stics_wrapper_options: Getting/setting a stics_wrapper options list with initialized...

In SticsRPacks/SticsOnR: Manage STICS Simulations Running the Executable or JavaStics,

Getting/setting a stics_wrapper options list with initialized fields

Description

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

Usage

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

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.

Value

A list containing Stics model stics_wrapper options

Examples

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

## End(Not run)

SticsRPacks/SticsOnR documentation built on April 19, 2024, 9:47 p.m.