Translate Models from System Dynamics Software into 'R'

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 'Stan'; and inputs to simulate via 'deSolve' as described in Duggan (2016) .

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)

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

Tutorials

For information on how to use this package, please check:

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 (2023). Anchoring the mean generation time in the SEIR to mitigate biases in $\Re_0$ estimates due to uncertainty in the distribution of the epidemiological delays. Royal Society Open Science.
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.