sdCoupledModelClass: Class Representation of a Coupled System Dynamics Model

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

Description

Represents a coupled system dynamics model made up of instanced sdModelClass, sdStaticModelClass and/or sdCoupledModelClass components and a list of connections that define the flow of information between components. The connections list determines loops of information feedback and circular causality for conceptualizing the structure of a complex system and for communicating model-based insights. The complex system is solved by integrating all the coupled system components simultaneously as one, updating the connections at each time step.

Usage

sdCoupledModelClass

Format

An object of class R6ClassGenerator of length 24.

Details

To create an object use the constructor sdCoupledModel.

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

To simulate a model in different scenarios use the sdSimulate function. Make sure to build the default coupled scenario before running the simulation or some computation time will be spent running the sdBuildCoupledScenario function to build it.

The object fields not declared in this documentation are automatically generated by the $buildCoupledModel method to be used by the package during simulations, e.g. the lists with all the components functions, the vectors representing the connections (eqConnections and stConnections) and the list with the components variables indexes (indexComponents).

Fields

coupledModelId

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

coupledModelDescription

A string with the coupled model description.

components

A list of sdModelClass, sdStaticModelClass and/or sdCoupledModelClass objects.

The models must have different ID's that will be used as unique identifiers, otherwise only the last model added with the same ID will be kept.

connections

A list of vectors that specifies the connections.

Each vector represents a connection, it must have 5 elements and be defined as:

c(ID, Component 1, Input 1, Component 2, Output 2).

Where ID: is the connection identification; Component 1: is the identification of the receiver component; Input 1: is the name of the input variable from the receiver component (component 1); Component 2: is the identification of the sender component; and Output 2: is the name of the connected state variable or, auxiliary or algebraic, equation with prefix st$, aux$ or eq$, respectively, indicating the output type from the sender component (Component 2), e.g. st$<varName>, aux$<eqName> or eq$<eqName>.

defaultCoupledScenario

The default coupled scenario, a sdScenarioClass object. Uses the method $buildCoupledModel to automatically build it by merging the components default scenarios. See sdBuildCoupledScenario for more information about how these merge occures.

Methods Definition

$initialize(coupledModelId = NULL, coupledModelDescription = NULL, components = NULL, connections = NULL)

Class constructor. Define the base components and connections of the coupled system dynamics model. The coupledModelId is mandatory, if missing a default timestamp ID will be created.

Arguments

See the Fields section above for the arguments descriptions.

$print()

A short print of the object fields.

$addComponent(...)

Add extra components to the coupled system dynamics model.

Arguments

...

A character string with a model XML file name or a sdModelClass, sdStaticModelClass and/or sdCoupledModelClass objects already initialized. The models must have different ID's to be used as unique identifiers. Only one component by ID is stored.

$removeComponent(...)

Remove the specified components from the coupled system dynamics model and all connections involving them.

Arguments

...

Character objects containing the model IDs to be removed. If missing all components will be removed.

$addConnection(...)

Add extra connections to the coupled system dynamics model.

Arguments

...

Connection vectors with 5 character elements. See more details in the connections field section above.

$removeConnection(...)

Remove the specified connections from the model connections list.

Arguments

...

Character objects containing the connections ID's to be removed. If missing all the connections will be removed.

$buildCoupledModel(from = NULL, to = NULL, by = NULL, method = NULL, timeSeriesDirectory = "")

Build the default coupled scenario by merging the components default scenarios (see sdBuildCoupledScenario), initialize the coupled auxiliary and/or algebraic equations, build the vectors representing the connections (eqConnections and stConnections) and the list with the components variables indexes (indexComponents). The arguments from, to and by must be present to define the simulation time sequence.

If the components have support to events and no component defined an event function the simulation will stop in the first root, otherwise the corresponding event function will be trigged.

Use regular expressions to update the components equations with the name of the coupled scenario variables.

Arguments

from

The starting value of the time sequence. Numeric of length 1.

to

The end (maximal) value of the time sequence. Numeric of length 1.

by

number: increment of the time sequence.

method

The integrator to be used in the simulation, a string ("lsoda", "lsode", "lsodes","lsodar","vode", "daspk", "euler", "rk4", "ode23", "ode45", "radau", "bdf", "bdf_d", "adams", "impAdams" or "impAdams_d"). Default value is "lsoda".

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.

timeSeriesDirectory

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

$isBuilt()

Test if the coupled model was already built and not modified. Return a logical object.

$verifyModel(scenario = NULL, verbose = FALSE, timeSeriesDirectory = "")

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

Arguments

scenario

A coupled scenario object (see sdBuildCoupledScenario), or a list of sdScenario objects and/or character strings with a sdScenario XML or EXCEL file name - the elements of this list must be named with the model ID that represent's it. 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.

timeSeriesDirectory

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

$saveToXml(file = "sdCoupledModel.xml")

Save the components and the connections in a XML file.

Arguments

file

A character object naming the file to save to. The file extension must be included in the file name, e.g. '.xml'.

Examples

# The Lotka-Volterra consumer-prey model implemented as a coupled model with
# the components being the population models of a prey and a consumer and a
# static model for the environment capacity

# set the time sequence and use the default method
times <- list(from = 0, to = 200, by = 1)

# Prey model variables and ode function
stPrey <- list(P = 1)
parsPrey      <- list(rG = 1.0)
inpPrey <- list(ingestC = 0,
                envCapacity = 1)
auxPrey <- list(GrowthP = "par$rG * st$P * inp$envCapacity")
descriptionsPrey <- list(P = "population of preys",
                         rG = "growth rate of prey",   
                         ingestC = "Consumer ingestion",
                         envCapacity = "available environment capacity")

LVodePrey <- function(t, st, ct, par, inp, sw, aux) 
{
  dP    <- aux$GrowthP - inp$ingestC
  
  return(list(c(dP)))
}

# create the component prey model
prey <- sdModel(modelId = "Prey",
                defaultScenario = sdScenario(scenarioId = "preyScen",
                                             times = times,
                                             state = stPrey,
                                             parameter = parsPrey,
                                             input = inpPrey,
                                             description = descriptionsPrey),
                aux = auxPrey,
                DifferentialEquations = LVodePrey)

# Consumer model variables and ode function
stConsumer <- list(C = 2)
parsConsumer  <- list(rI = 0.2,
                      rM = 0.2 ,   
                      aE = 0.5) 
inpConsumer <- list(P = 0)
auxConsumer <- list(ingestC = "par$rI * inp$P * st$C",
                    "mortC <- par$rM * st$C")
descriptionsConsumer <- list(C = "population of consumer",
                             rM = "mortality rate of consumer", 
                             aE = "assimilation efficiency",
                             rI = "rate of ingestion",
                             P = "population of preys")

LVodeConsumer <- function(t, st, ct, par, inp, sw, aux) 
{
  dC    <- aux$ingestC * par$aE - aux$mortC
  
  return(list(c(dC)))
}

# create the component consumer model
consumer <- sdModel(modelId = "Consumer",
                    defaultScenario = sdScenario(
                      scenarioId = "consumerScen",
                      times = times,
                      state = stConsumer,
                      parameter = parsConsumer,
                      input = inpConsumer,
                      description = descriptionsConsumer),
                    aux = auxConsumer,
                    DifferentialEquations = LVodeConsumer)

# Environment model variables and algebraic equations
parEnv <- data.frame(Variable = c("K"),
                    Value = c(10),
                    Description =c("carrying capacity"))
inpEnv <- data.frame(Variable = c("P"),
                    Value = c(1),
                    Description = c("Population size"))
eqEnvironment <- list(regulatingCapacity = "1 - inp$P/par$K")  

# create the component environment capacity model
environmentCap <- sdStaticModel(staticModelId = "Environment",
                             defaultScenario = sdScenario(
                               scenarioId = "EnvironmentScen",
                               parameter = parEnv,
                               input = inpEnv,
                               times = times),
                             equations = eqEnvironment)                   

# create the coupled model connections list 
# conP: inform the consumer model about the amount of preys; 
# conIngestC: inform the prey model about the consumer ingestion;
# conPEnv: inform the environment model about the amount of preys and
# conEnvCapacity: inform the prey model about the available environment capacity
lvConnections <- list(
  c("conP", "Consumer", "P", "Prey", "st$P"),
  c("conIngestC", "Prey", "ingestC", "Consumer", "aux$ingestC"),
  c("conPEnv", "Environment", "P", "Prey", "st$P"),
  c("conEnvCapacity", "Prey", "envCapacity", "Environment", "eq$regulatingCapacity"))

# Create the Lotka-Volterra coupled model
coupledLV <- sdCoupledModel(coupledModelId = "LVCoupled",
                            components = c(prey, consumer, environmentCap),
                            connections = lvConnections,
                            coupledModelDescription = 
  "Lotka-Volterra Equations implemented as a coupled model")
# build the coupled model and validate it
coupledLV$buildCoupledModel(from = 0, 
                            to = 200, 
                            by = 1)
coupledLV$verifyModel(verbose = TRUE)

# simulate the coupled model and plot the results
outclv <- sdSimulate(model = coupledLV)
outclv$plot("Prey.P Environment.regulatingCapacity", "Prey.P Consumer.C", 
            main = c("Coupled Prey Regulated by Environment Capacity",
                     "Coupled Prey and Consumer by Lotka-Volterra"),
            multipleYAxis = TRUE)

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