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.
- Programmatic model building — create stocks, flows, auxiliaries, and delayed auxiliaries from Python code.
- XMILE round-trip — load
.stmx/.xmilemodels, 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.
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).
Requires Python 3.9 or later.
pip install asdmASDM and its required dependencies will be automatically installed.
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')Beyond the Python API, ASDM provides two ways to run simulations without writing code:
Perfect for exploring models, visualizing results, and quick iterations.
Launch the simulator:
asdm simulatorOpens in your browser at http://127.0.0.1:8080.
Run a specific model immediately:
asdm simulator model.stmxOptions:
--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
Ideal for batch processing, automation, and integrating into pipelines.
Run a simulation:
asdm run model.stmxResults saved as model.csv by default.
Custom output:
asdm run model.stmx --output results.csvUse in scripts:
# Process multiple models
for model in models/*.stmx; do
asdm run "$model" --output "results/$(basename $model .stmx).csv"
doneCheck version:
asdm --versionPlease refer to Documentation for detailed function descriptions.
Jupyter Notebooks demonstrate ASDM's functionalities:
- 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.
- Load and simulate
.stmxmodels. - Support for arrays.
- Modify equations and re-run simulations.
- 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.
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 |
ASDM is open-source and released under the MIT licence.
- Scientific Collaborator at Swiss Tropical and Public Health Institute, Switzerland.
- Contact: wang.zhao@swisstph.ch
- 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.