sdStaticModelClass: Class Representation of a System Static Model

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

Description

Represents a static (or steady-state, no state variables) model that consists of algebraic equations and a default scenario describing the system environment (variables and values). A static model calculates the system in equilibrium, and thus is time-invariant. 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

sdStaticModelClass

Format

An object of class R6ClassGenerator of length 24.

Details

To create an object use the constructor sdStaticModel.

To load a model from a XML file use the sdLoadModel function.

To simulate a model in different scenarios use the sdSimulate function.

If the static model do not have time series input variables the result of the algebraic equations will always be constant in time during simulations, and therefore the simulation will only run for the initial time.

Fields

staticModelId

A string with the model identification. Any non-word character will be removed and the result will be converted to a valid name (see make.names).

staticModelDescription

A string with the model description.

defaultScenario

The model default scenario, a sdScenarioClass object without state variables. It should contain all the model variables initialized with default values that ensures the model simulation. Any state variable will be removed.

equations

A list with the model algebraic equations in strings or R-expressions written in R-format.

They have access to the following variables: (t, ct, par, inp, sw, eq). Where t is the current time point in the integration, st is a list with the current estimate of the state variables in the ODE system, ct is a list with the model constant variables, par is a list with the model parameter variables, inp is a list with the model input variables with the time series variables evaluated for the current time step, sw is list with the model switch variables and eq is a list with the predecessors algebraic equations, following the sorted list, evaluated for the current time step.

The algebraic equation are evaluated at each time step during simulations.

See the function sdInitEquations to learn how this list is generated.

InitVars

(Optional) An R-function that initialize or change the initial values of the model variables before the solver call when running a simulation. It can be used, for example, to compute some dependent parameter variables or the initial value of variables, using the arguments.

It must be defined as: function(ct, par, inp, sw, eq). Where ct is a list with the model constant variables, par is a list with the model parameter variables, inp is a list with the model input variables, sw is a list with the model switch variables and eq is a list with the model algebraic equations in R-expression format, as defined by the user.

The return value of the InitVars function should be a list containing all the function arguments, except the algebraic equations, named in the same way, e.g. return(list(ct = ct, inp = inp, par = par, sw = sw)).

globalFunctions

A named list of extra functions that can be executed in the scope of any other function or algebraic equation defined in the model. They can be called by their names in the list.

Public Methods Definition

$initialize(staticModelId, staticModelDescription, InitVars, equations, defaultScenario, globalFunctions)

Class constructor. Sets the static model definition fields.

Arguments

See the Fields section above for the arguments descriptions.

$print()

Print the object fields.

$verifyModel(scenario = NULL, verbose = F)

Execute the model simulation first step in the default scenario or merged with a given one. Check for possible incorrect variables and warn the user.

Arguments

scenario

A sdScenarioClass object or a character string naming the sdScenario XML or EXCEL file. If missing validate the model using the default scenario.

verbose

Logical: If TRUE provides additional details as to what the computer is doing. Default = FALSE.

$saveToXml(file = "sdStaticModel.xml")

Save the model equations and functions in a XML file.

Arguments

file

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

Examples

## Let's create a simplified model to represent an environment capacity
# regulated by a population size

# define the parameter: the environment carrying capacity
parEnv <- data.frame(Variable = c("K"),
                        Value = c(10),
                        Description =c("carrying capacity"))

# define the input: the population size
inpEnv <- data.frame(Variable = c("P"),
                     Value = c(1),
                     Description = c("Population size"))

# define the algebraic equation that regulate the capacity
algEqEnvironment <- list(regulatingCapacity = "1 - inp$P/par$K")

# create the environment capacity scenario
envScen <- sdScenario(scenarioId = "EnvironmentCapacityScen", 
                      parameter = parEnv,
                      input = inpEnv,
                      times = list(from = 0, to = 200, by = 1))

# create the static model of an environment capacity
envCapacity <- sdStaticModel(staticModelId = "EnvironmentCapacity",
                             defaultScenario = envScen,
                             equations = algEqEnvironment)
# validate the equations and simulate the model
envCapacity$verifyModel()
outEnvCapacity <- sdSimulate(envCapacity)
print(outEnvCapacity)

# note that static models without time series variables have constant result
# and therefore will only be simulated for the first time step if not coupled

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