How to use Mathematica to rapidly build interactive stories based on System Dynamics simulations
If you want to use the insights gained from simulation models to transform your business, just having the model and the insights is often not enough – you need to develop a good story that persuades your stakeholders to make decisions and take action.
In my last post Telling Stories with System Dynamics Models I introduced our approach to telling interactive stories based on simulation models built using System Dynamics. The final work products of our approach are interactive presentations that run in a browser, built using modern webtechnology.
Writing such interactive stories is quite challenging, even if your simulation model is already fairly complete, because you need to craft the storyline while testing different scenarios with the simulation model.
Our experience is that while web applications are great to deploy interactive stories (because everyone has a browser), they are not suited to supporting the writing process itself, because they require quite a bit of engineering – the story really needs to be finished before you start building the web application.
We realised early on that what we needed was a tool that would help us to prototype a complex story line while still building the model:
 Build an initial simulation model using a visual modelling environment
 Start writing a story around the model using the tool
 Use the new questions and insights that arise during the writing process to drive experiments with the simulation model – this may lead to changes in both the model and the storyline.
We have found that Wolfram Mathematica® is a wonderful tool to support this process – it is a complete environment that supports writing, computation and presentation. Mathematica does not contain native support for System Dynamics, but we have crafted a small library that allows us to import System Dynamics models based on the XMILE standard and to run them in Mathematica.
In this post I will demonstrate our storytelling approach using our Mathematica System Dynamics Package and a very simple project management simulation. The System Dynamics model itself was built using the dynamic modeling and simulation software Stella Architect® from iseesystems.Stella saves models using the XMILE format, which is an open XML protocol for sharing interoperable system dynamics models and simulations. The XMILE standard is being developed by OASIS standards consortium.
I’ve included the stock and flow diagram of the entire model below
The next sections illustrate how to use our System Dynamics package:
 Importing the System Dynamics Package and the XMILE Model
 Getting an Overview of the Model
 Running the Model
 A Closer Look at the Underlying Equations
 Setting Up the Scenario Manager
 Using the Scenario Manager to Store and Evaluate Scenarios
 Presenting Simulation Results
 Setting Up Interactive Scenarios
Importing the System Dynamics Package and the XMILE Model
The first step is to import the System Dynamics packages:
Now we are ready to import the XMILE model:
Simulations are stored using an abstract data type appropriately named simulation
:
Getting an Overview of the Model
The following command provides a simple overview of the model:
Simulation Name  Simple Project Simulation  
Statistics 


Run Specs 


Stocks 


Flows 


Converters 


Constants 

All elements (and their equations) and the runspecs defined in the model are imported. The names of the model elements are automatically converted to camel casing.
Running the model
Unlike in Stella, the simulation model doesn’t need to be “run” in Mathematica – because all the equations are set up as recursive mathematica functions, you can evaluate them directly.
Let’ s pick on of the model variables from the list above and see which value it has on a particular day, for instance the schedulePressure on day 5 with a DT of 1 (given the initial model settings defined above).
And here is the schedulePressure on day 6, but with a DT of 0.5:
A Closer Look at the Underlying Equations
Each of the equations in the SD model is automatically converted to a function in Mathematica during import – so in practice, we don’t need to worry about the equations, because they are maintained for us by the modelling environment (Stella in this case) and Mathematica automatically.
Nevertheless it is interesting to take a look at what the equations look like in Mathematica. As an example, here is the equation for the openTasks
:

And this is the equation for the schedulePressure
:
The scenario manager is used to evaluate and store simulation scenarios. This is useful, because when experimenting with simulations it is often necessary to compare the effect that different assumptions have on particular outcomes, e.g. in our case the effect of different deadlines on the actual project completion date. Using scenarios, you can store these settings without any side effects to the model itself.
Setting Up the Scenario Manager
By definition, a scenario is a collection of settings for the model – in our case the deadline
, effortPerTask
, initialOpenTaks
and initialStaff
.
In our Mathematica implementation, we use Mathematica‘s native options mechanism to implement the scenario manager. We do this by defining a function referred to as the scenario evaluator, which assigns the option settings to the model elements they are relevant to.
The scenario evaluator uses the options mechanism that is native to Mathematica:
Now we create a new scenario manager, which is represented by the abstract data type scenarioManager
and pass the scenarioEvaluator
. The scenario manager will use the scenario evaluator to evaluate the scenarios.
Using the Scenario Manager to Store and Evaluate Scenarios
Let’s define three scenarios – the only setting we will change for now is the deadline
, which we want to be on day 80, day 100 and day 120 respectively.
We can now evaluate all scenarios at once – this calculates the time series for all model elements for each of the scenarios and stores them for later reference:
Presenting Simulation Results
Thanks to Mathematica’s graphical capabilities, plotting simulation results is easy:
Setting up an Interactive Scenario – Constant Values
Scenarios can also be interactive—this is useful, because it means you can mix predefined static scenarios with interactive scenarios in one Mathematica notebook.
First we define a new scenario, which will hold the settings defined interactively by the user:
Let’s set up input fields for the effort per task
and the initial staff
and present then in a grid layout.
This leads to the following output in the interactive presentation:
Effort per Task 

Initial Staff 
Setting up an Interactive Scenario – Graphical Functions
Setting up an input device for graphical functions is also very easy: we only need to define the range of values and the initial coordinates for the graph.
We can display a graphical input device using the following function:
You can now manipulate the graph as you wish, by dragging the grey locator buttons.
Setting up an Interactive Scenario – Interactive Feedback
Using Mathematica’s interactive elements (such as Manipulate), it is also very easy to give direct feedback to the user.
The following command sets up a panel that will let you experiment with different settings for the deadline interactively – don’t forget that your settings for effortPerTask
and the number of Staff
and the effect of schedulePressure
on productivity
will also have an effect on the results below.
Conclusion
This post detailed our approach to building interactive presentations from simulation models using Mathematica. Here are the important points you should remember:
 If you want to use the insights gained from simulation models to transform your business, just having the model and the insights is often not enough – you need to develop a good story that persuades your stakeholders to make decisions and take action.
 Mathematica is a great environment for rapidly building interactive stories that rely on data and on simulations – once you have understood the basics of Mathematica, building such presentations is actually quite easy. You can concentrate on the story and let Mathematica do the heavy lifting.
 Building complex simulations using System Dynamics is best done using visual modeling environments such as Stella Architect. Thanks to the new XMILE standard and our Mathematica System Dynamics package, we can import System Dynamics models created into Mathematica and run them there.
 Once you have finished the interactive story you can publish it to a wide audience by turning it into a webbased application. I provided details on this in my last post on Telling Stories with System Dynamics Models.
To see an interactive story written using this approach, take a look at our blog posts on the Business Prototyping Methodology or on Growth Strategies in Professional Service Firms.