sdScenario: Creates a Scenario Object

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

Description

A factory function that creates a sdScenarioClass object that represents the variables and values that constitute a system environment, and that are used to compute the equations of a model. It also stores configurations for a simulation, e.g. the time sequence and integrator method.

Usage

sdScenario(scenarioId, times = list(from = 0, to = 100, by = 1),
  method = c("lsoda", "lsode", "lsodes", "lsodar", "vode", "daspk", "euler",
  "rk4", "ode23", "ode45", "radau", "bdf", "bdf_d", "adams", "impAdams",
  "impAdams_d"), state, constant, parameter, input, interpolation, switch, unit,
  description, timeSeriesDirectory = "", variableCol = "Variable",
  valueCol = "Value", unitCol = "Unit", descriptionCol = "Description",
  interpolationCol = "Interpolation")

Arguments

scenarioId	A character string with the scenario ID.
times	A named list containing three elements to be passed to the seq function: from - the simulation initial time, to - the simulation final time and by - the time step, increment of the sequence (e.g. list(from = 0, to = 100, by = 1)).
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.
state	A numeric list with the default initial state values for the ODE system. The state variables are used to describe the mathematical "state" of a dynamic system. The continuous rate of change of these variables is determined by the model DifferentialEquations function. All the elements in this list must be named. Or a data.frame following the guidelines in the Data.frame Format section.
constant	A numeric list with the model constant variables. All the elements in the list must be named. Or a data.frame following the guidelines in the Data.frame Format section.
parameter	A numeric list containing the parameters of the scenario. All the elements in this list must be named. Or a data.frame following the guidelines in the Data.frame Format section.
input	A list containing the inputs of the scenario. All the elements in the list must be named. Or a data.frame following the guidelines in the Data.frame Format section.
interpolation	A list containing the interpolation methods for any time series variable present in the input list. All the elements in the list must be named with the respective input time series variable name. See sdTemporalFunction for the complete list of available methods. Missing if already present in the input data.frame, otherwise will overwrite it.
switch	A list containing the switches of the scenario. All the elements in the list must be named. Or a data.frame following the guidelines in the Data.frame Format section.
unit	A list with the model variables units. Each element of this list represents a variable (named with the variable name) and it's value is a string with the variable unit. Missing if variables were passed in a data.frame or it will be concatenated with the given units in any data.frame.
description	A list with the model variables descriptions. Each element of this list represents a variable (named with the variable name) and it's value is a string with the variable description. Missing if variables were passed in a data.frame or it will be concatenated with the given descriptions in any data.frame.
timeSeriesDirectory	The directory where the time series inputs are stored (when passing the time series inputs via external files).
variableCol	When using data.frames, the name of the column that contains the variable's names. Default is 'Variable'.
valueCol	When using data.frames, the name of the column that contains the variable's values. Default is 'Value'.
unitCol	When using data.frames, the name of the column that contains the variable's units. Default is 'Unit'.
descriptionCol	When using data.frames, the name of the column that contains the variable's descriptions. Default is 'Description'.
interpolationCol	When using data.frames, the name of the column of the input time series that contains the interpolation methods. Default is 'Interpolation'.

Details

To load a scenario from an EXCEL or XML file use the sdLoadScenario function.

To build a coupled scenario use the sdBuildCoupledScenario function.

Value

A sdScenarioClass object.

Data.frame Format

The data.frame of each type of variable must follow these 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 input 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 data.frame defines a new variable.

• The default decimal point character is '.'

• 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 create a scenario with two state variables, two input variables (one
# being a time series) and one constant

## First implementation using lists:

# let's create a list for each type of variable (st, inp and ct)
# state variables
st <- list(s1 = 2, s2 = 5)  
# input variables
inp <- list(i1 = 10, ts1 = data.frame(Time = c(1, 5, 10), 
                                     Value = c(5, 10, 20)))
# interpoaltion method for the time series variable
tsInterpolation <- list(ts1 = "linear")
# constant variables
ct <- list(c1 = 0.5)

# let's create dummy descriptions and units for our example variables
descriptions <- list(s1 = "state var 1",
                     s2 = "state var 2",
                     i1 = "input var 1",
                     ts1 = "time series var 1",
                     c1 = "constant var 1")
units <- list(s1 = "meter",
              s2 = "meter / second",
              i1 = "1 / second",
              ts1 = "liters / second",
              c1 = "dimensionless")

# let's create a list for the time sequence and define the integrator method
times <- list(from = 0, to = 10, by = 0.5)
method <- "rk4"
              
# call the constructor to create a scenario from the lists
dummyScen <- sdScenario(scenarioId = "dummyScenario",
                        state = st, 
                        input = inp, 
                        interpolation = tsInterpolation,
                        constant = ct,
                        description = descriptions,
                        unit = units,
                        times = times,
                        method = method)
print(dummyScen)

# let's remove the input 'i1' and add it again as a function
dummyScen$removeInput("i1")
dummyScen$addInput(i1 = function(x) {x + 10})
print(dummyScen$input$i1(5))

# let's remove all the state variables and add them again by assignment
dummyScen$removeState()
dummyScen$state <- list(s1 = 2, s2 = 5) 

# let's add the descriptions and units again
dummyScen$addDescription(s1 = "state var 1",
                         s2 = "state var 2",
                         i1 = "input fun 1")
dummyScen$addUnit(s1 = "meter",
                  s2 = "meter / second",
                  i1 = "1 / second")
print(dummyScen)

## Second implementation using data.frames:

# let's create a data.frame for each type of variable
# remember setting stringsAsFactor = FALSE to prevent wrong convertions
# state variables
st <- data.frame(Variable = c("s1", "s2"), 
                 Value = c(5,10),
                 Description = c("state var 1", "state var 2"),
                 Unit = c("meter", "meter / second"),
                 stringsAsFactors = FALSE)

# input variables
inp <- data.frame(Variable = c("i1", "ts1"), 
                 Value = c(10, "data.frame(Time = c(1, 5, 10), Value = c(5, 10, 20))"),
                 Interpolation = c(NA, "linear"),
                 Description = c("input var 1", "time series var 1"),
                 Unit = c("1 / second", "liters / second"),
                 stringsAsFactors = FALSE)
     
# constant variables
ct <- data.frame(Variable = c("c1"), 
                 Value = c(0.5),
                 Description = c("constant var 1"),
                 Unit = c("dimensionless"),
                 stringsAsFactors = FALSE)

# call the constructor to create a scenario from the data.frames
dummyScen <- sdScenario(scenarioId = "dummyScenario",
                        state = st, 
                        input = inp, 
                        constant = ct,
                        times = times,
                        method = method) 
print(dummyScen)

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