sdModel: Creates an Atomic System Dynamics Model Object

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

Description

A factory function that creates a sdModelClass object from functions that describe the changes in the system states in response to external actions and other system flows, and a default scenario describing the system environment (variables and default values).

Usage

sdModel(modelId = NULL, modelDescription = NULL, defaultScenario = NULL,
  aux = NULL, DifferentialEquations = NULL, InitVars = NULL,
  PostProcessVars = NULL, RootSpecification = NULL, EventFunction = NULL,
  globalFunctions = NULL)

Arguments

modelId	A character string with the model ID. Any non-word character will be removed and the result will be converted to a valid name (see make.names).
modelDescription	A character 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: 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 (which will have the time series variables evaluated for each time step during the simulation), sw is list with the model switch variables and aux is a list with the model auxiliary equations (which will be evaluated for each time step during the simulations). The return value of the 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 need to 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 must be a list containing all the variable arguments named in the same way, except the aux equations; 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.
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.

Details

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

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

Value

A sdModelClass object.

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

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