Flows in a river system represented visualised as a system dynamics graph

Visualising System Dynamics Models

Simulation is a powerful tool for understanding and solving complex problems, and visualisation is key to doing simulation well. Visualisation helps to communicate function, validate and tune implementation and diagnose errors for a simulator, at every stage of development and operation. System dynamics can be used to implement a certain class of simulators, and helpfully provides a visual language for defining models. 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 the upshot is that I wrote a basic visualisation module for BPTK_Py models, which I’ve found quite useful. This isn’t a visual design environment, but it supports visualisation of models defined in code.

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, and the rate at which this happens depends 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 pond level and when overflow occurs).

I targeted BPTK_Py as the simulation framework because I liked its Python DSL for model definition. For visualisation, the model is represented as a graph, with nodes for each class of system dynamics object defined: stocks, flows, constants and converters. Where these objects are related by equations, edges are added to the graph to show the dependencies.

Flows are typically drawn connected to sources or sinks, but I decided to leave that construct implicit. The direction of dependency, rather than the (nominal) direction of flow is shown between stocks and flows. To see the detail of dependencies, the equations can be overlaid on each node. Networkx is used to model and render the graph.

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

This final example also shows the visual representation of converters, and you can compare this generated visualisation to the visual design in the BPTK introductory tutorial.