asdm 0.7.2

A Python package for System Dynamics Modeling

asdm

Agile System Dynamics Modelling

ASDM is a Python library for building and simulating System Dynamics (SD) models. It supports programmatic model creation, XMILE/.stmx import and export, and includes a built-in web simulator. ASDM is suitable for healthcare modelling, policy analysis, and any domain where stock-and-flow models are used.

Key Features

• Programmatic model building — create stocks, flows, auxiliaries, and delayed auxiliaries from Python code.
• XMILE round-trip — load .stmx/.xmile models, modify them, and save back to XMILE format.
• Arrays and subscripts — multi-dimensional variables with element-level or parallel equations.
• Conveyors — conveyor stocks with transit time and leak flows.
• Graph functions — lookup tables with interpolation, modifiable at runtime.
• Data import — feed time-varying or parameter data from CSV files into model variables.
• Built-in SD functions — DELAY, DELAY1, DELAY3, SMTH1, SMTH3, PULSE, STEP, INIT, HISTORY, NORMAL, BINOMIAL, LOOKUP, and more.
• Causal Loop Diagrams — generate CLDs from model structure using NetworkX.
• Web simulator — browser-based interactive simulator with charts and CSV export.
• Command-line interface — run simulations and export results from the terminal.

ASDM's Contribution & Impact

Check out this presentation: Project Care Home Demand, which highlights the role of ASDM in developing an online SD model-based simulator. The presentation is given by Sally Thompson, Senior Healthcare Analyst at The Strategy Unit (part of NHS Midlands and Lancashire CSU).

---

Installation

Install from PyPi

Requires Python 3.9 or later.

pip install asdm

ASDM and its required dependencies will be automatically installed.

---

Basic Usage

To create a new SD model using ASDM:

from asdm import sdmodel

model = sdmodel()

sdmodel is the core class for System Dynamics models.

Alternatively, you can load an SD model saved in XMILE format, including .stmx models:

model = sdmodel(from_xmile='example_model.stmx')

Run the simulation:

model.simulate()

Export simulation results:

• As a pandas DataFrame:

  result = model.export_simulation_result(format='df')
  

• As a Python dictionary:

  result = model.export_simulation_result(format='dict')
  

Save the model back to XMILE format:

model.save_xmile('output_model.stmx')

---

Running Simulations

Beyond the Python API, ASDM provides two ways to run simulations without writing code:

Web Interface

Perfect for exploring models, visualizing results, and quick iterations.

Launch the simulator:

asdm simulator

Opens in your browser at http://127.0.0.1:8080.

Run a specific model immediately:

asdm simulator model.stmx

Options:

• --port 8081 — Use a different port
• --host 0.0.0.0 — Allow access from other machines

Features:

• Drag-and-drop model upload (.stmx, .xmile)
• Interactive charts with variable selection
• Download results as CSV
• Auto-detects time units

---

Command Line

Ideal for batch processing, automation, and integrating into pipelines.

Run a simulation:

asdm run model.stmx

Results saved as model.csv by default.

Custom output:

asdm run model.stmx --output results.csv

Use in scripts:

# Process multiple models
for model in models/*.stmx; do
  asdm run "$model" --output "results/$(basename $model .stmx).csv"
done

Check version:

asdm --version

---

Functionalities

Please refer to Documentation for detailed function descriptions.

---

Tutorial Jupyter Notebooks

Jupyter Notebooks demonstrate ASDM's functionalities:

SD Modelling

• Creating an SD model from scratch:
  • Adding stocks, flows, auxiliaries.
  • Support for nonlinear and stochastic functions.
• Running simulations.
• Exporting and examining simulation results.
• Visualising results.

Support for .stmx Models

• Load and simulate .stmx models.
• Support for arrays.
• Modify equations and re-run simulations.

Abstract Syntax Tree (AST)

• How ASDM parses model equations into AST structures.

More tutorial notebooks will be added.
Feel free to contribute your own via pull requests—please ensure they do not contain sensitive data.

---

Dependencies

ASDM relies on the following open-source packages. All use permissive licences compatible with the MIT licence.

Package	Licence	Purpose
NumPy	BSD-3-Clause	Numerical computation
pandas	BSD-3-Clause	Data export and CSV handling
Matplotlib	PSF-based (BSD-compatible)	Result visualisation
NetworkX	BSD-3-Clause	Dependency graphs and CLDs
lxml	BSD-3-Clause	XML processing
Beautiful Soup 4	MIT	XMILE parsing
SciPy	BSD-3-Clause	Scientific functions
Flask	BSD-3-Clause	Web simulator

---

Licence

ASDM is open-source and released under the MIT licence.

---

Contributors

Wang Zhao (main author)

• Scientific Collaborator at Swiss Tropical and Public Health Institute, Switzerland.
• Contact: [e-mail]

Matt Stammers (contributor)

• Consultant Gastroenterologist & open-source developer at University Hospital Southampton, UK.
• Developed Streamlit-powered web apps using ASDM for healthcare modelling.
• Part of the Really Useful Models initiative: Learn More.
• GitHub: Matt's Homepage.

---