Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Overview Of The BPTK-Py Tutorial

This tutorial contain sample agent-based and System Dynamics models along with Jupyter notebooks that illustrate the features of the BPTK-Py framework. This tutorial is designed as a companion to the BPTK-Py online documentation.


Using Docker

If you have Docker installed (e.g. Docker Desktop on MacOS or on Windows), follow these steps:

  1. On the command line, move into a directory where you would like to store the BPTK-Py tutorial.
  2. Clone this repository: git clone
  3. Run docker-compose up
  4. Point your browser at http://localhost:8888 – this will open JupyterLab showing the contents of your directory.
  5. Open the notebook readme.ipynb from within JupyterLab.
  6. When you are finished, close your browser and call docker-compose down from within your directory. This will stop and remove the container.

Using a virtual environment

First, make sure you have Python 3 installed on your machine.

Then follow these steps:

  1. On the command line, move into a directory where you would like to store the BPTK-Py tutorial.
  2. Clone this repository: git clone
  3. Install a virtual environment in that directory: python3 -m venv venv
  4. Activate the virtual environment: source venv/bin/activate (MacOS/Linux) or venv\scripts\activate.bat (Windows)
  5. Install the necessary python modules: pip install -r requirements.txt
  6. Start JupyerLab: jupyter lab
  7. Your browser will open showing JupyterLab and your chosen directory
  8. Open the notebook readme.ipynb from within JupyterLab

Getting Started

This tutorial contains a number of Jupyter notebooks that illustrate usage of the BPTK-Py framework. Which one to get started with depends on whether you are interested in Agent-based modeling, in System Dynamics using XMILE (e.g. using Stella Architect or iThink) or in our domain-specific language for System Dynamics (SD DSL):


Learning More About System Dynamics and Agent-based Modeling

The main objective of this tutorial is to show you how to use the BPTK-Py framework and not to explain System Dynamics or Agent-based modeling.

For those new to dynamic modeling, we have included a small step-by-step Introduction to System Dynamics with Python.

You can also find further introductions on our blog:

Advanced Examples on GitHub

You can find more advanced examples of models and dashboards build using BPTK on GitHub:

  • COVID Simulation. Jupyter notebooks and dashboards illustrating the SIR model.
  • COVID Simulation Dashboard. A web-based simulation dashboard for the COVID simulation built using our BPTK Widgets library for Javascript. View a live version of the dashboard online.
  • Beer Distribution Game. In-depth analysis of the beergame using both System Dynamics and Agent-based simulation. Includes an illustration of how to use BPTK in conjunction with reinforcement learning to train agents to play the beergame autonomously.
  • Model Library Repository. A growing repository which contains a number of models that illustrate how to model socio-economic systems using Agent-based modeling, System Dynamics and BPTK.

Get in Touch

Please let us know if you need help getting started, if you find a bug or are missing important functionality.

We are keen to hear how you use BPTK-Py – your feedback is invaluable in helping us improve BPTK-Py.

You can best reach us per e-mail at


Tutorial for BPTK-Py, the Python simulation engine for System Dynamics & Agent based models.







No packages published