sdModelClass: Class Representation of an Atomic System Dynamics Model

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

Description

Represents an atomic system dynamics model that consists of functions describing the system flows and a default scenario describing the system environment (variables and values). 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

sdModelClass

Format

An object of class R6ClassGenerator of length 24.

Details

To create an object use the constructor sdModel.

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

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

Fields

modelId

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).

modelDescription

A string with the model description.

defaultScenario

The model default scenario, a sdScenarioClass object. It should contain all the model variables initialized with default values that ensures the model simulation.

aux

(Optional) A list with the model auxiliary equations in strings or R-expressions written in R-format to assist in the DifferentialEquations computation.

They have access to the following variables: (t, st, ct, par, inp, sw, aux). 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 aux is a list with the predecessors auxiliary equations, following the sorted list, evaluated for the current time step.

The auxiliary equations are evaluated at each time step during simulations and passed via the argument aux to any model function call.

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

DifferentialEquations

An R-function that computes the values of the state variables derivatives in the ODE system (the model definition) at time t.

It must be defined as: DifferentialEquations <- function(t, st, ct, par, inp, sw, aux). 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 and the time series variables evaluated for the current time step, sw is list with the model switch variables and aux is a list with the model auxiliary equations evaluated for the current time step.

The return value of DifferentialEquations must be a list, whose first element is a vector containing the derivatives of the state variables with respect to time, and whose next elements are extra values that are computed at each time step and will be included in the simulation output. The derivatives must be specified in the same order as the state variables.

InitVars

(Optional) An R-function that initialize or change the initial state values and/or other 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 state variables, using the arguments.

It must be defined as: function(st, ct, par, inp, sw, aux). Where st is a list with the initial state variables values, 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 aux is a list with the model auxiliary 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 aux equations, named in the same way, e.g. return(list(st = st, ct = ct, inp = inp, par = par, sw = sw)).

PostProcessVars

(Optional) An R-function that receives the simulation output inside the sdSimulate function and process it to derive further conclusions.

It must be defined as: function(outputTrajectory, auxTrajectory, tsTrajectory, ct, par, inp, sw). Where outputTrajectory is a data.frame with the ode output trajectory, auxTrajectory is a data.frame with the auxiliary equations trajectory, tsTrajectory is a data.frame with the time series variables trajectory, 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 and sw is a list with the model switch variables.

The return value of PostProcessVars will be stored in the postProcess field of the sdOutput simulation output object and can be anything that suits the user needs.

RootSpecification

(Optional) A numeric vector containing the times to trigger the EventFunction, or a data.frame as specified in the events documentation, or an R-function that becomes zero when a root occur.

When a root is found, the simulation triggers an event by calling the EventFunction. If no EventFunction is defined, when a root is found the simulation stops.

When specified as a function it must be defined as: function(t, st, ct, par, inp, sw, aux). 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 aux is a list with the model auxiliary equations evaluated for the current time step.

It should return a numeric vector. If any element of this vector is zero an event is trigged.

EventFunction

(Optional) An R-function that specifies the event.

It must be defined as: function(t, st, ct, par, inp, sw, aux). 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 aux is a list with the model auxiliary equations evaluated for the current time step.

It should return the state-values (some of which modified), as a vector with the variables in the right order. If no EventFunction is defined, when a root is found the simulation stops.

description

A list with the model dafault scenario variables descriptions. Each element of this list represents a variable (named with the variable name) and it's value is the variable description.

unit

A list with the model dafault scenario 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.

globalFunctions

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

Public Methods Definition

$initialize(modelId, modelDescription, DifferentialEquations, InitVars, PostProcessVars, RootSpecification, EventFunction, aux, defaultScenario, globalFunctions)

Class constructor. Sets the 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 = "sdModel.xml")

Save the model functions in a XML file.

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

## HOW TO CREATE A MODEL
## The Lotka-Volterra consumer-prey model

# parameters in a list with units and descriptions in separete lists
pars      <- list(rI = 0.2,
                  rG = 1.0,    
                  rM = 0.2 ,   
                  AE = 0.5,    
                  K  = 10)   
parsUnits <- list(rI = "1/day",    
                  rG = "1/day",   
                  rM = "1/day" ,   
                  AE = "dimensionless",    
                  K  = "mmol/m3")
parsDescription <- list(rI = "rate of ingestion",    
                        rG = "growth rate of prey",   
                        rM = "mortality rate of consumer" ,   
                        AE = "assimilation efficiency",    
                        K  = "carrying capacity")

# state variables in a data.frame with values and description
st <- data.frame(Variable = c("P", "C"), 
                 Value = c(1, 2), 
                 Description = c("Prey", "Consumer"))

# time sequence
times <- list(from = 0, to = 200, by = 1)

# auxiliary equations
aux <- list(IngestC = "par$rI * st$P * st$C",
            GrowthP = "par$rG * st$P * (1 - st$P/par$K)",
            "MortC <- par$rM * st$C")

# differential equations
LVode <- function(t, st, ct, par, inp, sw, aux) 
{
  dP    <- aux$GrowthP - aux$IngestC
  dC    <- aux$IngestC * par$AE - aux$MortC
  
  return(list(c(dP, dC)))
}

# create the scenario
lvscen <- sdScenario(scenarioId = "LVscen", times = times, method = "lsoda",
                     state = st, parameter = pars, 
                     unit = parsUnits, description = parsDescription)

# create the model object
lv <- sdModel(modelId = "Lotka-Volterra", defaultScenario = lvscen, 
              DifferentialEquations = LVode,
              aux = aux)
              
# validate the model ode
lv$verifyModel(verbose = TRUE)

# simulate the model and plot the results
outlv <- sdSimulate(model = lv, storeAuxTrajectory = TRUE)
outlv$plot("P C", multipleYAxis = TRUE, 
           main = "Prey and Consumer by Lotka-Volterra")
outlv$saveSimulationTrajectories(path = "LV")

## HOW TO LOAD A MODEL FROM THE REPOSITORY
## Load the Rigid Body Model
rb <- sdLoadModel(file = "RigidBody", repository = TRUE)
print(rb)

# simulate the model and plot the results
outrb <- sdSimulate(model = rb)
outrb$plot("x y z")

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