Skip to contents

sdbuildR: Easily Build and Simulate Stock-and-Flow Models in R

Model systems as stock-and-flow models in R. Stock-and-flow models are foundational to system dynamics, and help to understand systems complicated by nonlinearities, delays, and feedback loops. sdbuildR aims to make stock-and-flow modeling accessible and effortless, enabling you to dedicate your expertise to what matters most: building insightful, high-quality models. Get started at https://kcevers.github.io/sdbuildR/!

Features

  • Accessibility: Get started with stock-and-flow models with limited knowledge.
  • Flexibility: Modify your models easily and robustly.
  • Insight Maker integration: Import models from Insight Maker.
  • Julia backend: Use Julia for high-performance simulations, without any knowledge of Julia.
  • Unit support: Use standard or custom units to verify and interpret your model.

All package capabilities are described in the vignettes:

  • vignette("build") Learn how to build, modify, and debug stock-and-flow models.
  • vignette("ensemble") Learn how to assess a model’s sensitivity, uncertainty and robustness with ensemble simulations.
  • vignette("units") Learn why and how to use (custom) units.

Installation

You can install the development version of sdbuildR like so:

# install.packages("remotes")
remotes::install_github("KCEvers/sdbuildR")

sdbuildR offers two simulation engines: R and Julia (supported by JuliaConnectoR). If you would like to run ensemble simulations and use units, you will need to set up the Julia environment. Run use_julia() to install Julia and required packages (initial setup may take 5–15 minutes):

sdbuildR::use_julia()
#> Starting Julia ...
#> Connecting to Julia TCP server at localhost:11980 ...
#> Setting up Julia environment for sdbuildR...

Limitations

  • Unlike in other System Dynamics software, sdbuildR minimally supports non-negative stocks and flows. Setting stocks to non-negative will not adjust flows. In any case, enforcing either stocks or flows to be non-negative is not recommended, as it may mask model misspecification. Stocks and flows that logically cannot be negative (e.g., animals or deaths) should ideally remain non-negative as a result of the model’s equations and parameters, rather than by forcing them to be non-negative.

  • sdbuildR does not support vectorized operations, destructuring assignment, or variable constraints.

  • sdbuildR does not support the Insight Maker functions Pause(), Fix(), Map(), Filter(), and Repeat(). A message is issued if any of these are detected.

Other System Dynamics software

sdbuildR is heavily based on common System Dynamics software such as Vensim, Powersim, Stella, and Insight Maker. To translate xmile models to R, see the R package readsdr. To build stock-and-flow models with the R package deSolve, the book System Dynamics Modeling with R by Jim Duggan will prove useful. In Python, stock-and-flow models are supported by PySD.

Troubleshooting

sdbuildR is under active development. While thoroughly tested, the package may have bugs, particularly in complex model translations. We encourage users to report issues on GitHub (https://github.com/KCEvers/sdbuildR/issues) - your input helps the package improve! Use debugger() to diagnose model errors, and use the vignettes for guidance.