Installation

Explains how to install the BPTK-Py business simulation framework.
Keywords

agent-based modeling, abm, bptk, bptk-py, python, business simulation

Installation

BPTK-Py requires Python 3.11 or later. Installing it into your Python environment takes a single command:

pip install BPTK-Py

That gives you everything you need to build and simulate models: the SD DSL, agent-based modeling, hybrid models — and both execution engines.

The two execution engines

BPTK evaluates System Dynamics models on one of two engines. The Python engine is the default and runs everywhere Python does, including in the browser. The Rust engine evaluates the same model in compiled code, which is worth having once a model is large or you run the same scenario hundreds of times.

You choose the engine per run or per bptk instance; how to do that is covered later in this documentation. The Rust engine ships pre-compiled inside the wheel, so there is no Rust toolchain to install and nothing to configure.

Extras

Capabilities that not every modeller needs are available as extras. Each is named after the capability it buys rather than after the library behind it:

Install Adds
pip install "BPTK-Py[plotting]" Plotting via Matplotlib — plot_scenarios, Element.plot, plot_lookup
pip install "BPTK-Py[xmile]" The XMILE compiler, for models built in Stella or iThink
pip install "BPTK-Py[server]" BptkServer and the Postgres and Redis state adapters
pip install "BPTK-Py[observability]" Logging to Pydantic Logfire

They combine: pip install "BPTK-Py[plotting,xmile]". Note the quotes — some shells, zsh among them, read the square brackets as a filename pattern.

Using a capability without its extra raises an error that names the extra to install, so nothing fails silently.

Running The Documentation Notebooks

Every page of this documentation that contains code is a marimo notebook, and you can run it without installing anything at all: press the play button on a cell, change a value, and the cells that depend on it recompute right here in your browser.

To run the notebooks locally — against your own models, and without the memory limits of a browser — you need four steps:

  1. Install Python
  2. Clone the BPTK-Py repository
  3. Set up a virtual environment
  4. Open a notebook

Install Python

First of all, you need Python. Download the latest version for your operating system.

BPTK-Py was tested with Python 3.11, 3.12 and 3.13.

Clone the BPTK-Py repository

The documentation and every notebook in it live in the BPTK-Py repository, below docs/tutorial. On the command line, move into a directory where you would like to keep it, then:

git clone https://github.com/transentis/bptk_py.git
cd bptk_py

Set up a virtual environment

A virtual environment is a local copy of your Python distribution that stores all packages required and does not interfere with your system’s packages.

The following steps set up a virtual environment in a folder called venv:

python3 -m venv venv

Enter the virtual environment using the command appropriate for your operating system:

OS Command
UNIX/Linux/MacOS source venv/bin/activate
Windows venv.bat

Now you should see “(venv)” at the beginning of your command prompt. Install BPTK-Py and marimo into it:

pip install -r docs/tutorial/requirements.txt

Open a notebook

Each page of this documentation has a .py file beside it, and that file is the notebook — the page you are reading was generated from it. Open one with marimo:

marimo edit docs/tutorial/tutorials/system_dynamics/sd_tutorial.py

marimo opens your browser with the notebook running in it. Notebooks are reactive: when you change a cell, everything that depends on it recomputes, so a notebook never shows you a result that belongs to code you have since edited.

Once you are finished, close your browser and stop marimo with Ctrl-C in your terminal.

Keeping BPTK-Py up-to-date

Software evolves. We regularly release new versions to add functionality, improve the code and fix bugs.

If you are on the command line using pip, you can update BPTK-Py as follows:

pip install --upgrade BPTK-Py

You can also check for updates and install them from within a running notebook:

from BPTK_Py import bptk
bptk = bptk()
bptk.update()

The update mechanism automatically checks for a newer version and (if necessary) downloads and installs it.

To check which version is currently installed, run:

from BPTK_Py import bptk
bptk = bptk()
print(bptk.version)

Package dependencies

If for any reason you want to install the requirements manually, or need to know why we need a package, here is the list. If you observe malfunctions in the framework and believe the reason may be an incompatibility with a newer version of one of these packages, please let us know.

pip install BPTK-Py installs these:

Package What we use it for
pandas DataFrames and internal results storage
numpy Numerical operations, and required by pandas
scipy Linear interpolation for graphical functions
tqdm Progress indication for long-running simulations
jsonpickle Serialising scenarios and simulation state
xlsxwriter Writing .xlsx files — pandas uses it as the Excel engine for bptk.export_scenarios()

Each extra adds the packages its capability needs, and nothing else:

Extra Package What we use it for
plotting matplotlib Plotting environment
xmile parsimonious Parsing the SMILE equations inside XMILE models
xmile xmltodict Reading XMILE files
xmile jinja2 Generating Python classes for XMILE SD models
server flask The REST API
server psycopg The Postgres state adapter
server redis The Redis state adapter
observability logfire Sending logs and traces to Pydantic Logfire