Skip to content
Tutorial for BPTK-Py, the python simulation engine for System Dynamics & Agent based models
Jupyter Notebook Python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


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

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 a "work" directory in the file browser. This directory is mapped to your working directory.
  5. Open the notebook readme.ipynb from within JupyterLab to get started.
  6. When you are finished, close your browser and call docker-compose down from within your directory. This will stop and remove your containers.

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

The tutorial contains a number of noteboos and models. Which one to get started with depends on whether you are interested in Agent-based modeling, in System Dynamics using XMILE (e.g. Stella Architect or iThink) or in the System Dynamics DSL:


We illustrate the BPTK-Py framework using three simple models:

  • Simple Project Management Model. This model is an illustration of Parkinson's law, which states that work expands so as to fill the time available for its completion.
  • Bass Diffusion Model. This model is an implementation of the Bass diffusion model originally created by Frank Bass that describes the process of how new products get adopted in a population. The Bass model has been widely used in forecasting, especially new products' sales forecasting and technology forecasting.
  • Customer Acquisition Model. A small model about referral marketing that builds upon the Bass Diffusion Model.

Here is an overview of the documents contained in this tutorial, they all use at least one of the models listed above.

Learning More About System Dynamics and Agent-based Modeling

The 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. If you want to learn more about the techniques themselves, please refer to our blog:

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

You can’t perform that action at this time.