Waterfall cascading over ferny rock platforms

Visualising System Dynamics Models

Simulation is a powerful tool for understanding and solving complex problems, but sometimes simulations themselves can be hard to understand. Visualisation is a powerful tool for understanding what simulations are telling us, and also for socialising the limitations and assumptions built into predictions.

An approach

System dynamics is a simulation paradigm that can be used to model certain types of natural, social and business scenarios with interacting features.

The interactive visualisation above shows a system dynamics model of a pond, with seasonal inflow, evaporation, and outflow when an overflow level is reached. Hover over the nodes for the equations that link these quantities. You can also pan & zoom the view and drag the nodes to new locations. This type of visual language for models enables multidisciplinary teams to collaborate around simulations.

Augmenting open tools

While many commercial tools support visualisation of models, I haven’t found as much support for visualisation as I expected in open source system dynamics tools.

If I’m missing something, please let me know! But to fill the gap I wrote a simple visualisation module for BPTK_Py models, the output of which you see above. Usage is illustrated in this demonstration notebook; it’s just a few lines of code to transform BPTK model -> NetworkX graph -> interactice PyVis visualisation. The NetworkX graph can also be visualised statically, or exported for other uses.

I targeted BPTK_Py as the simulation framework because I liked its Python DSL for model definition. The visualisation is not a visual design environment, but it does support the visualisation of models defined in code, which still enables short feedback cycles in model design.

Pond example in detail

The model visualised above is a simple river system, where seasonal stream inflow feeds a pond (the arrow from inflow to pond). Water in the pond is lost to evaporation, depending on how much water there is in the pond (hence arrows in both directions between evaporation and pond). If the water in the pond reaches a certain level it is drained by outflow (hence pond level depends on outflow, and outflow depends on excessVolume of the pond above overflowLevel).

Time-series chart of stocks and flows for the pond example

The model graph for visualisation has nodes for each class of system dynamics object defined with a label: stocks, flows, constants and converters. Where these objects are related by equations, edges are added to the graph to show the dependencies. Edges are added by recursively inspecting terms in the equations until an object is reached. As I use a DiGraph and not a MultiDiGraph, a maximum of one edge will be created between each pair of nodes even if multiple references are found in the equation.

In system dynamics visualisations, flows are typically drawn connected to sources or sinks, but I decided to leave that construct implicit. My visualisations show the direction of dependency between stocks and flows, rather than the (nominal) direction of flow. To see the detail of dependencies, the equations can be overlaid on each node. The static version of the visualisation is shown below.

Graph representation of a system dynamics model of a pond. Stocks, flows, constants and their dependencies are shown. The dependency equations are shown on the nodes

The code could benefit from: further testing, additional support for all the equations types in BPTK_Py.sd_functions (reference), and better layout support for the static view. But maybe it helps fill a gap that would otherwise exist.

BPTK population tutorial example

This second example shows the visualisation of the BPTK introductory population tutorial.

First the interactive version.

And the static version (with first generation hexagonal converters) .

Graph representation of a system dynamics model of population. Stocks, flows, constants and their dependencies are shown. The dependency equations are shown on the nodes

You can compare both generated visualisations to the visual design from the tutorial.

Visual design of system dynamics model from BPTK population tutorial

What do you think? Let me know if you have any success using it or any thoughts on how important this type of visualisation is to building shared understanding in complex analytics projects.

Note this post was updated in September 2023 with the interactive version of the visualisation.