R/ssimEnvironment.R

Defines functions progressBar runtimeTempFolder runtimeOutputFolder runtimeInputFolder envCreateTempFolder envCreateScenarioFolder envValidateEnvironment ssimEnvironment

Documented in progressBar runtimeInputFolder runtimeOutputFolder runtimeTempFolder ssimEnvironment

# Copyright (c) 2021 Apex Resource Management Solution Ltd. (ApexRMS). All rights reserved.
# MIT License

#' SyncroSim Environment
#'
#' This function is part of a set of functions designed to facilitate the
#' development of R-based Syncrosim Packages. \code{ssimEnvironment} retrieves
#' specific environment variables.
#'
#' @return 
#' Returns a single-row data.frame of SyncroSim specific environment variables.
#' 
#' @examples 
#' \dontrun{
#' # Get the whole set of variables
#' e <- ssimEnvironment()
#' 
#' # Get the path to transfer directory, for instance
#' transferdir <- e$TransferDirectory
#' }
#' 
#' @export
ssimEnvironment <- function() {
  return(data.frame(
    PackageDirectory = Sys.getenv(tolower("SSIM_PACKAGE_DIRECTORY"), unset = NA),
    ProgramDirectory = Sys.getenv(tolower("SSIM_PROGRAM_DIRECTORY"), unset = NA),
    LibraryFilePath = Sys.getenv(tolower("SSIM_LIBRARY_FILEPATH"), unset = NA),
    ProjectId = as.integer(Sys.getenv(tolower("SSIM_PROJECT_ID"), unset = -1)),
    ScenarioId = as.integer(Sys.getenv(tolower("SSIM_SCENARIO_ID"), unset = -1)),
    InputDirectory = Sys.getenv(tolower("SSIM_INPUT_DIRECTORY"), unset = NA),
    OutputDirectory = Sys.getenv(tolower("SSIM_OUTPUT_DIRECTORY"), unset = NA),
    TempDirectory = Sys.getenv(tolower("SSIM_TEMP_DIRECTORY"), unset = NA),
    TransferDirectory = Sys.getenv(tolower("SSIM_TRANSFER_DIRECTORY"), unset = NA),
    BeforeIteration = as.integer(Sys.getenv(tolower("SSIM_STOCHASTIC_TIME_BEFORE_ITERATION"), unset = -1)),
    AfterIteration = as.integer(Sys.getenv(tolower("SSIM_STOCHASTIC_TIME_AFTER_ITERATION"), unset = -1)),
    BeforeTimestep = as.integer(Sys.getenv(tolower("SSIM_STOCHASTIC_TIME_BEFORE_TIMESTEP"), unset = -1)),
    AfterTimestep = as.integer(Sys.getenv(tolower("SSIM_STOCHASTIC_TIME_AFTER_TIMESTEP"), unset = -1)), stringsAsFactors = FALSE
  ))
}

envValidateEnvironment <- function() {
  e <- ssimEnvironment()

  if (is.na(e$ProgramDirectory)) {
    stop("This function requires a SyncroSim environment.")
  }
}

envCreateScenarioFolder <- function(scenario, parentFolder, datasheetName) {
  sidpart <- paste0("Scenario-", scenario@scenarioId)

  p <- gsub("\\", "/", parentFolder, fixed = TRUE)
  f <- file.path(p, sidpart, datasheetName, fsep = .Platform$file.sep)

  if (!dir.exists(f)) {
    dir.create(f, recursive = TRUE)
  }

  return(f)
}

envCreateTempFolder <- function(folderName) {
  t <- ssimEnvironment()$TempDirectory
  p <- gsub("\\", "/", t, fixed = TRUE)

  f <- file.path(p, folderName, fsep = .Platform$file.sep)

  if (!dir.exists(f)) {
    dir.create(f, recursive = TRUE)
  }

  return(f)
}

#' SyncroSim DataSheet Input Folder
#'
#' This function is part of a set of functions designed to facilitate the
#' development of R-based Syncrosim Packages. This function creates and returns 
#' a SyncroSim Datasheet Input Folder.
#'
#' @param scenario \code{\link{Scenario}} object. A SyncroSim result Scenario
#' @param datasheetName character. The input Datasheet name
#' 
#' @return 
#' Returns a folder name for the specified Datasheet.
#' 
#' @examples 
#' \dontrun{
#' inputFolder <- runtimeInputFolder()
#' }
#' 
#' @export
runtimeInputFolder <- function(scenario, datasheetName) {
  envValidateEnvironment()
  return(envCreateScenarioFolder(scenario, ssimEnvironment()$InputDirectory, datasheetName))
}

#' SyncroSim DataSheet Output Folder
#'
#' This function is part of a set of functions designed to facilitate the
#' development of R-based Syncrosim Packages. This function creates and returns 
#' a SyncroSim DataSheet Output Folder.
#'
#' @param scenario \code{\link{Scenario}} object. A SyncroSim result Scenario
#' @param datasheetName character. The output Datasheet name
#' 
#' @return 
#' Returns a folder name for the specified datasheet.
#' 
#' @examples 
#' \dontrun{
#' outputFolder <- runtimeOutputFolder()
#' }
#' 
#' @export
runtimeOutputFolder <- function(scenario, datasheetName) {
  envValidateEnvironment()
  return(envCreateScenarioFolder(scenario, ssimEnvironment()$OutputDirectory, datasheetName))
}

#' SyncroSim Temporary Folder
#'
#' This function is part of a set of functions designed to facilitate the
#' development of R-based Syncrosim Packages. This function creates and returns 
#' a SyncroSim Temporary Folder.
#'
#' @param folderName character. The folder name
#' 
#' @return 
#' Returns a temporary folder name.
#' 
#' @examples 
#' \dontrun{
#' tempFolder <- runtimeTempFolder()
#' }
#' 
#' @export
runtimeTempFolder <- function(folderName) {
  envValidateEnvironment()
  return(envCreateTempFolder(folderName))
}

#' Sets the progress bar in the SyncroSim User Interface
#' 
#' This function is designed to facilitate the development of R-based Syncrosim 
#' Packages, such as beginning, stepping, ending, and reporting the progress 
#' for a SyncroSim simulation.
#' 
#' @param type character. Update to apply to progress bar. Options include
#' "begin", "end", "step", and "report" (Default is "step")
#' @param iteration integer. The current iteration. Only used if 
#' \code{type = "report"}
#' @param timestep integer. The current timestep. Only used if 
#' \code{type = "report"}
#' @param totalSteps integer. The total number of steps in the simulation. Only
#' used if \code{type = "begin"}
#' 
#' @return 
#' No returned value, used for side effects
#' 
#' @examples 
#' \dontrun{
#' # Begin the progress bar for a simulation
#' progressBar(type = "begin", totalSteps = numIterations * numTimesteps)
#' 
#' # Increase the progress bar by one step for a simulation
#' progressBar(type = "step")
#' 
#' # Report progress for a simulation
#' progressBar(type = "report", iteration = iter, timestep = ts)
#' 
#' # End the progress bar for a simulation
#' progressBar(type = "end")
#' }
#' 
#' @export
progressBar <- function(type = "step", iteration = NULL, timestep = NULL, totalSteps = NULL) {
  
  # Check Program Directory
  envValidateEnvironment()
  
  # Begin progress bar tracking
  if (type == "begin") {
    if (is.numeric(totalSteps)) {
      cat(sprintf("ssim-task-start=%d\r\n", totalSteps))
      flush.console()
    } else {
      stop("totalSteps argument must be an integer")
    }
    
  # End progress bar tracking
  } else if (type == "end") {
    cat("ssim-task-end=True\r\n")
    flush.console()
    
  # Step progress bar
  } else if (type == "step") {
    cat("ssim-task-step=1\r\n")
    flush.console()
  
  # Report iteration and timestep in UI  
  } else if (type == "report") {
    if (is.numeric(iteration) & is.numeric(timestep)) {
      cat(sprintf("ssim-task-status=Simulating -> Iteration is %d - Timestep is %d\r\n", iteration, timestep))
      flush.console()
    } else {
      stop("iteration and timestep arguments must be integers")
    }
  
  # Throw error if type not specified correctly  
  } else {
    stop("Invalid type argument")
  }
  
}

Try the rsyncrosim package in your browser

Any scripts or data that you put into this service are public.

rsyncrosim documentation built on Oct. 28, 2021, 1:07 a.m.