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.

Installation

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 https://github.com/transentis/bptk_py_tutorial.git
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 https://github.com/transentis/bptk_py_tutorial.git
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):

• Agent-based Modeling – start with Agent-based Modeling with BPTK-Py
• SD with XMILE – start with Working With XMILE System Dynamics Models
• SD DSL – start with A Simple Python Library for System Dynamics

Contents

• Step by Step Guides

  • Introduction to System Dynamics with Python. Introduction to System Dynamics using the SD DSL, for those new to dynamic modeling.

• General Information on The Framework

  • In Depth Discussions
    • The Architecture of the BPTK-Py Framework Explains the overall architecture of the BPTK-Py framework.
    • Scenarios In Depth Explains the scenario definition format and how to add and manipulate scenarios at run-time.
  • HOW TOs
    • How To: Accessing Raw Simulation Results Explains how to access raw simulation results with scenarios.
    • How To: Advanced Plotting Features Discusses some advanced features of the bptk.plot_scenarios method.
    • How To: Develop Dashboards Using the SimpleDashboard Utility Class. Shows how do build simple interactive dashboards using the bptk.dashboard method.
    • How To: Develop Dashboards Using Jupyter Widgets Explains how to develop more advanced user interfaces using Jupyter Widgets, Pandas dataframes and Matplotlib.
    • How To: Persist BPTK-Server State Show how to persist the state of BptkServer using an ExternalStateAdapter.

• Agent-based Modeling

  • In Depth Discussions
    • Agent-based Modeling with BPTK-Py Illustrates how to create an agent-based implementation of a simple project management model.

• System Dynamics using XMILE

  • In Depth Discussions
    • Writing Computational Essays Using Simulation Models. Introduction to writing Computational Essays around System Dynamics models created using the XMILE Standard (e.g. using ®Stella or ®iThink).
  • HOW TOs
    • How To: Working With XMILE System Dynamics Models Illustrates the quickest route to importing a System Dynamics model stored in the XMILE format, such as those created with ®Stella (.stmx) or ®iThink (.itmx).
    • How To: Exporting Simulation Results Explains how to export simulation results into a spreadsheet.
    • How To: Working with Arrayed Variables in XMILE Models Explains how to use arrayed operators aund functions in BPTK_Py

• System Dynamics using SD DSL

  • In Depth Discussions
    • A Simple Python Library for System Dynamics. Introduction to building System Dynamics models directly in Juptyer Notebooks, using SD DSL, a specially created domain specific language for System Dynamics, that is part of BPTK-Py.
    • SD DSL Functions An overview of how to use the SD DSL operators such as MIN, MAX and DELAY.
  • HOW TOs
    • How To: Creating User Defined Functions in SD Models Explains how to create user defined functions in SD models.

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:

• Step-by-step introduction to System Dynamics using the simple project management model.
• Introduction to the Bass Diffusion Model.
• The Customer Acquisition Model is discussed in our series of post introducing the Business Prototyping Methodology.
• Our Business Prototyping Toolkit Meetup Group gathers online regularly. This is a good place to see BPTK in action, ask questions and suggest new features. We record every session and you can view past recordings on the meetup homepage.

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 support@transentis.com