sdScenarioClass: Class Representation of a System Scenario

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

Description

Represents a system scenario that can consist of state variables, inputs, constant values, parameters and switches. It also stores configurations for a simulation, e.g. the time sequence and integrator method. Together, all the variables and values constitute a system environment for a model. All the variables, except the state, accepts vectors. All the object field are active binding variables that invoke a function to read it's value or to assign a value to it (<-).

Usage

sdScenarioClass

Format

An object of class R6ClassGenerator of length 24.

Details

To create an object use the constructor sdScenario.

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

To build a coupled scenario use the sdBuildCoupledScenario function.

Fields

scenarioId

A string with the scenario identification. If missing a default timestamp will be created.

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 simulation 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 an ODE system. The state variables are used to describe the mathematical "state" of a system dynamics. The continuous rate of change of these variables is determined by the model DifferentialEquations function. All the elements in this list must be named.

constant

A numeric list with the model constant variables. All the elements in the list must be named.

parameter

A numeric list containing the parameters of the scenario. All the elements in this list must be named.

input

A list with the input variables. It accepts any type of elements. The time series variables must be present in this list. All the elements in this list must be named.

If any interpolation method is given in the object initialization it will be stored in the input list element 'interpolation_' and the transformed temporal functions, created with the sdTemporalFunction, will be stored in the element 'fun_'.

switch

A list with the switch variables. All the elements in this list must be named.

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.

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 the variable description.

Public Methods Definition

$initialize(scenarioId, times, method, state, constant, parameter, input, interpolation, switch, unit, description, timeSeriesDirectory = "")

Class constructor. Sets the model definition fields.

Arguments

See the Fields section above for the other arguments descriptions.

interpolation

A list containing the interpolation methods for any time series variable present the input list. All the elements in this list must be named with the respective input time series variable name. See sdTemporalFunction for the complete list of available methods.

timeSeriesDirectory

The directory where the time series inputs are stored (when passing the time series inputs via external files).

$print()

Print the state, constant, parameter, input and switch data.frames (with variable, value, unit, description and interpolation columns).

$addState(..., verbose = FALSE, overwrite = FALSE)

Arguments

...

named fixed numeric values. If it is a single list, it's elements will be added instead.

verbose

Logical: If TRUE provides additional details about the added variable. Default = FALSE.

overwrite

Logical: If TRUE overwrittes all the previous added variables with the given '...' list. Default = FALSE.

$addConstant(..., verbose = FALSE, overwrite = FALSE)

Arguments

...

named numeric vectors. If it is a single list, it's elements will be added instead.

verbose

Logical: If TRUE provides additional details about the added variable. Default = FALSE.

overwrite

Logical: If TRUE overwrittes all the previous added variables with the given '...' list. Default = FALSE.

$addInput(..., interpolation = NULL, verbose = FALSE, overwrite = FALSE, timeSeriesDirectory = "")

Arguments

...

named objects. If it is a single list, it's elements will be added instead.

interpolation

A list containing the interpolation methods for any time series variable given in the '...' list. All the elements in this list must be named with the respective time series variable name. See sdTemporalFunction for the complete list of available methods.

verbose

Logical: If TRUE provides additional details about the added variable. Default = FALSE.

overwrite

Logical: If TRUE overwrittes all the previous added variables with the given '...' list. Default = FALSE.

timeSeriesDirectory

The directory where time series variables are stored (when passing the time series inputs via external files as character file names).

$addParameter(..., verbose = FALSE, overwrite = FALSE)

Arguments

...

named numeric vectors. If it is a single list it's elements will be added instead.

verbose

Logical: If TRUE provides additional details about the added variable. Default = FALSE.

overwrite

Logical: If TRUE overwrittes all the previous added variables with the given '...' list. Default = FALSE.

$addSwitch(..., verbose = FALSE, overwrite = FALSE)

Arguments

...

named numeric or complex or logical or character vectors. If it is a single list it's elements will be added instead.

verbose

Logical: If TRUE provides additional details about the added variable. Default = FALSE.

overwrite

Logical: If TRUE overwrittes all the previous added variables with the given '...' list. Default = FALSE.

$addUnit(..., verbose = FALSE, overwrite = FALSE)

Arguments

...

named character vectors. If it is a single list it's elements will be added instead.

verbose

Logical: If TRUE provides additional details about the added variable. Default = FALSE.

overwrite

Logical: If TRUE overwrittes all the previous added variables with the given '...' list. Default = FALSE.

$addDescription(..., verbose = FALSE, overwrite = FALSE)

Arguments

...

named character vectors. If it is a single list it's elements will be added instead.

verbose

Logical: If TRUE provides additional details about the added variable. Default = FALSE.

overwrite

Logical: If TRUE overwrittes all the previous added variables with the given '...' list. Default = FALSE.

$removeState(..., verbose = FALSE)

Arguments

...

Character objects containing the state variable names to be removed. If missing all states will be removed.

verbose

Logical: If TRUE provides additional details about the removed variable. Default = FALSE.

$removeConstant(..., verbose = FALSE)

Arguments

...

Character objects containing the constant variable names to be removed. If missing all constants will be removed.

verbose

Logical: If TRUE provides additional details about the removed variable. Default = FALSE.

$removeParameter(..., verbose = FALSE)

Arguments

...

Character objects containing the parameter variable names to be removed. If missing all parameters will be removed.

verbose

Logical: If TRUE provides additional details about the removed variable. Default = FALSE.

$removeInput(..., verbose = FALSE)

Arguments

...

Character objects containing the input variable names to be removed. If missing all inputs will be removed.

verbose

Logical: If TRUE provides additional details about the removed variable. Default = FALSE.

$removeSwitch(..., verbose = FALSE)

Arguments

...

Character objects containing the switch variable names to be removed. If missing all switches will be removed.

verbose

Logical: If TRUE provides additional details about the removed variable. Default = FALSE.

$removeUnit(..., verbose = FALSE)

Arguments

...

Character objects containing the variable names to remove the unit. If missing all switches will be removed.

verbose

Logical: If TRUE provides additional details about the removed variable. Default = FALSE.

$removeDescription(..., verbose = FALSE)

Arguments

...

Character objects containing the variable names to remove the description. If missing all switches will be removed.

verbose

Logical: If TRUE provides additional details about the removed variable. Default = FALSE.

$setTimeSequence(from, to, by)

Set the simulation time sequence.

Arguments

from

The simulation initial time; numeric.

to

The simulation final time; numeric.

by

the time step, increment of the sequence

$scenarioDataFrames()

Build the scenario variables data.frames.

Returned Value

A list with the state, constant, parameter, input and switch data.frames (with variable, value, unit, description and interpolation columns)

$saveToXlsx(file = "Scenario.xlsx", colWidth = c(10, 10, 10, 30, 10))

Save the scenario variables in a EXCEL file. This format is recommended for user modification. It will follow the format present in the EXCEL Format section of the sdLoadScenario help.

Arguments

file

A string with the file name to save to. The file extension must be included in the file name, e.g. '.xlsx'.

colWidth

The Excel columns width.

$saveToXml(file = "sdScenario.xml")

Save the scenario variables in a XML file. This format is not recommended for user modification.

Arguments

file

A string with the file name to save to. The file extension must be included in the file name, e.g. '.xml'.

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.