'Object Oriented' Systems Dynamics (OOSD) model builder in python

A python package to build Systems Dynamics (SD) models as instances of the SdModel() class, which includes methods to add SD elements to the model (an thus the Object-Oriented nature of the model building process).

One of the main goals of this package is to allow for quick prototyping of Systems Dynamics models "on the go". This prototypes can be easily grown as the project moves from simpler assumptions to more complex structures, parameters, equations and relationships. The idea behing this packages it to build XMILE models that adhere to the 4 practical reasons outlined by Eberlein and Chichakly (2013) for creating the standard: archiving, replicability, analysis and specialized tool development.

The SdModel implements methods to create comprehensive Systems Dynamics models complying with the OASIS XMILE [xmile-v1.0] open standard for System Dynamics such as:

• Stocks
• Flows
• Auxiliaries
• Graphical functions
• Unit definition

Currently, it doesn't support other, more advanced funtionalities such as:

• Groups
• Built in Functions
• Submodels
• Arrays
• Styles

A simple recipie to build SD models

In the original XMILE simulation webinar (https://systemdynamics.org/wp-content/uploads/assets/xmile/xmile-simulation-webinar.pdf) a savings model was introduced to showcase the main functionalities of the XMILE standard. A recipie to create the XMILE compliant XML file using OOSD is provided below.

1) We first need to import the SdModel class from the OOSD package

# Import OOSD package and the SdModel class
from OOSD import SdModel

2) Create an instance of the SdModel class along with the main simulation specs

# Create SdModel instance and simulation specs
sd_model = SdModel(name="Bank_Balance", 
                   start=0, 
                   stop=36, 
                   dt=0.25)

3) Define the main building blocks of the SD model (i.e Stocks, Flows and Auxiliares)

# Define model variables
sd_model.add_stock(name="Savings", 
                   eqn=1000,
                   inflow="Interest")

sd_model.add_flow(name="Interest",
                  eqn="Savings * Interest_Rate")

sd_model.add_auxiliary(name="Interest_Rate",
                       eqn=0.03)

4) Generate the SD XMILE compliant file

# Generate the XMILE compliant file
sd_model.save_xmile()

The output of this function is a XMILE file that is stored in your python working folder, the file should look like this:

<?xml version="1.0" ?>
<xmile xmlns="http://docs.oasis-open.org/xmile/ns/XMILE/v1.0" version="1.0">
	<header>
		<vendor>https://github.com/rchavelas</vendor>
		<product version="0.0.1">OOSD</product>
		<name>Bank_Balance</name>
	</header>
	<sim_specs method="Euler">
		<start>0</start>
		<stop>36</stop>
		<dt>0.25</dt>
	</sim_specs>
	<model_units/>
	<model>
		<variables>
			<stock name="Savings">
				<eqn>1000</eqn>
				<inflow>Interest</inflow>
			</stock>
			<flow name="Interest">
				<eqn>Savings * Interest_Rate</eqn>
			</flow>
			<aux name="Interest_Rate">
				<eqn>0.03</eqn>
			</aux>
		</variables>
	</model>
</xmile>

5) Finally, load and run the XMILE file into a SD simulator (such as ISEE Player)

References

• Eberlein, R. L. & Chichakly, K. J. (2013). XMILE: a new standard for system dynamics. System Dynamics Review, 29(3):188-195. https://doi.org/10.1002/sdr.1504
• [xmile-v1.0] XML Interchange Language for System Dynamics (XMILE) Version 1.0. Edited by Karim Chichakly, Gary Baxter, Robert Eberlein, Will Glass-Husain, Robert Powers, and William Schoenberg. 14 December 2015. OASIS Standard. http://docs.oasis-open.org/xmile/xmile/v1.0/os/xmile-v1.0-os.html. Latest version: http://docs.oasis-open.org/xmile/xmile/v1.0/xmile-v1.0.html.