sdLoadScenario: Loads a Scenario Object from External Files

In EmbrapaInformaticaAgropecuaria/sdsim: System Dynamics Model Simulator for Initial Value Problems of ODE

Description

A factory function that creates a sdScenarioClass object from XML or EXCEL files. Uses the file extension to determine it's format.

Usage

sdLoadScenario(file, timeSeriesDirectory = "", stateSheet = "state",
  constantSheet = "constant", inputSheet = "input",
  parameterSheet = "parameter", switchSheet = "switch",
  simulationSheet = "simulation", variableCol = "Variable",
  valueCol = "Value", unitCol = "Unit", descriptionCol = "Description",
  interpolationCol = "Interpolation")

Arguments

file	A scenario file name in '.xlsx', '.xls' or '.xml' containing the format extension.
timeSeriesDirectory	The directory where time series inputs are stored (when passing the time series inputs via external files).
stateSheet	A character string with the name of the EXCEL sheet that contains the state variables. Default is 'state'. (Only used if the file is a '.xlsx' or '.xls').
constantSheet	A character string with the name of the EXCEL sheet that contains the constant variables. Default is 'constant'. (Only used if the file is a '.xlsx' or '.xls').
inputSheet	A character string with the name of the EXCEL sheet that contains the input variables. Default is 'input'. (Only used if the file is a '.xlsx' or '.xls').
parameterSheet	A character string with the name of the EXCEL sheet that contains the parameter variables. Default is 'parameter'. (Only used if the file is a '.xlsx' or '.xls').
switchSheet	A character string with the name of the EXCEL sheet that contains the switch variables. Default is 'switch'.(Only used if the file is a '.xlsx' or '.xls').
simulationSheet	A character string containing the name of the EXCEL sheet that contains the simulation configuration variables. Default is 'simulation'. (Only used if the file is a '.xlsx' or '.xls').
variableCol	A character string with the name of the column containing the variables names.
valueCol	A character string with the name of the column containing the variables values.
unitCol	A character string with the name of the column containing the variables units.
descriptionCol	A character string with the name of the column containing the variables descriptions.
interpolationCol	A character string with the name of the column containing the input time series variables interpolation method.

Details

Use the sdExcelTemplate function to create an empty template for a sdsim scenario EXCEL file.

Value

A sdScenarioClass object.

EXCEL Format

The EXCEL file representing a sdScenarioClass object must have one sheet per type of variable and a sheet for the simulation configurations, e.g. the stateSheet, constantSheet, inputSheet, parameterSheet, switchSheet and the simulationSheet. A sheet can be missing if the scenario do not have the corresponding type of variable.

Each sheet must follow this guidelines:

• Have header

• Have 4 columns, with the default parameters labels as bellow:

  1. Variable - the column with the variables name

  2. Value - the column with the variables value

  3. Unit - the column with the variables unit

  4. Description - the column with the variables description

  With the exception of the inputSheet that should also contain a fifth column, labeled 'Interpolation' containing the interpolation method to be used in the time series variables. Each variable that have a valid method will be passed to the sdTemporalFunction to be automatically converted into a temporal function.

• Each row of the sheets defines a new variable. With exception to the simulationSheet that can only have the following 5 (five) hard coded variables rows, named as bellow:

  1. scenarioId - A string with the scenario identification.

  2. from - the simulation initial time

  3. to - the simulation final time

  4. by - the simulation time step, increment of the sequence

  5. method - The default integrator to be used in the simulations, a string ("lsoda", "lsode", "lsodes","lsodar","vode", "daspk", "euler", "rk4", "ode23", "ode45", "radau", "bdf", "bdf_d", "adams", "impAdams" or "impAdams_d"). When running with support to events the given method must be one of the following routines, which have root-finding capability: lsoda, lsode or radau; If the given method is different from any of these three routines the simulator will run with the default method "lsoda". See the ode and the events details section for more information.

• The default decimal point character is '.'

• The sheet names must follow the defaults or be specified in the arguments.

• Empty sheets, empty variable names and invalid values will be skipped with a warning to the user.

• All the leading and trailing whitespaces will be trimmed.

Examples

## Let's load a model from the repository, save it's default scenario in a 
# EXECEL file, change it and then reload it to use it in a different 
# simulation

## Load the Bouncing Ball Model from the sdsim repository
bb <- sdLoadModel(file = "BouncingBall", repository = TRUE)

# save the bouncing ball default scenario to an EXCEL file
bb$defaultScenario$saveToXlsx(file = "bb.xlsx")

## Let's edit the the EXCEL file to define a new scenario where we are 
# throwing a tennis ball  from our hand to the ground
# To represent this scenario we need to edit the following 4 sheets:
# In the 'state' sheet:
#  - change the value of the variable 'height' to 1.5
#  - change the value of the variable 'speed' to -10 (negative indicating the 
# ball direction, to the ground)
# In the 'input' sheet:
#  - change the value of the variable 'k' to 0.75 (the tennis ball 
# coefficient of restitution when kicking in a tennis field)
# In the 'simulation' sheet: 
#  - change the value of the variable 'to' to 8 (it will stop faster)
#  - change the value of the variable 'by' to 0.001 (more precision)
#  - change the value of the variable 'scenarioId' to 'TennisBallKicking'
# Remove the 'constant' sheet (we will use the default value)

## Save the modified EXCEL file and reload it
tennisBallScen <- sdLoadScenario(file = "bb.xlsx")

# Simulate the Bouncing Ball model with the new scenario and plot the result
outbbTennis <- sdSimulate(model = bb, scenario = tennisBallScen)
outbbTennis$plot()

EmbrapaInformaticaAgropecuaria/sdsim documentation built on May 10, 2019, 9:58 a.m.