readsdr

Overview

The goal of readsdr is to bridge the design capabilities from specialised System Dynamics software with the powerful numerical tools offered by R libraries. The package accomplishes this goal by parsing .xmile files (Vensim and Stella models) into R objects to construct networks (graph theory), ODE functions for deSolve and Stan.

Installation

You can install the released version of readsdr from CRAN with:

install.packages("readsdr")

And the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("jandraor/readsdr")

Usage

library(readsdr)
filepath <- system.file("models/", "SIR.stmx", package = "readsdr")
mdl      <- read_xmile(filepath) 
summary(mdl)
#>                    Length Class  Mode
#> description        4      -none- list
#> deSolve_components 4      -none- list

For reading Vensim models, they must be exported as .xmile.

For information on how to use this package, see the vignette or type vignette("Introduction_to_readsdr") in R.

Supported builtins

Stella
- Comparison operators (=, <>)
- Logical operators (AND, OR, NOT)
- If Else Then
- Inequality operators (<, >)
- Pulse ¹
- Step ¹
- Endogenous table functions
- Smoothing functions²: SMTH1, SMTH3, SMTHN
- Delay functions: DELAYN
- Limited support to uni-dimensional arrays. Apply all translation is restricted to numeric values.
- Math functions: ABS, SQRT
- Stats functions: NORMAL³
Vensim
- Comparison operators (=, <>)
- Logical operators (:AND:, :OR:, :NOT:)
- IF_THEN_ELSE
- Inequality operators (<, >)
- Pulse ¹
- Pulse Train ¹
- Step ¹
- Endogenous table functions
- Smoothing functions²: SMOOTH, SMOOTH3, SMOOTH3I, SMOOTHI
- Delay functions: DELAY N
- Math functions: ABS, SQRT
- Limited support to bi-dimensional arrays.
- Stats functions: RANDOM NORMAL³

¹ Restricted to Euler integration.

² These functions cannot be part of more complex mathematical expressions. That is, the auxiliary variable must only contain one smoothing function and nothing else.

³ Seed is ignored.

Notes

uniflow and non-negative stock features from Stella are not supported.
No built-in is supported for translations to Stan code.
Modules from Stella are not supported.

Applications

This package has been instrumental in the following works:

Andrade & Duggan (2022). Inferring the effective reproductive number from deterministic and semi-deterministic compartmental models using incidence and mobility data. PLOS Computational Biology.
Andrade & Duggan (2021). A Bayesian approach to calibrate system dynamics models using Hamiltonian Monte Carlo. System Dynamics Review.
Andrade & Duggan (2020). An evaluation of Hamiltonian Monte Carlo performance to calibrate age-structured compartmental SEIR models to incidence data. Epidemics.

Acknowledgments

Thanks to:

Rogelio Oliva for advocating the need to create an open-source tool for the System Dynamics community and push forward this endeavour.
Sergey Naumov for his ideas to implement several functions in this package.
Jim Duggan from whom I borrowed ideas to implement this package.

References

Duggan, J. (2016). System Dynamics Modeling with R. Springer.

lzim / readsdr