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.13 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, as Execution Backends describes. 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	Packages
`pip install "BPTK-Py[plotting]"`	Plotting via Matplotlib — `plot_scenarios`, `Element.plot`, `plot_lookup`	matplotlib
`pip install "BPTK-Py[server]"`	`BptkServer` and the Postgres and Redis state adapters	flask, psycopg, redis
`pip install "BPTK-Py[observability]"`	Logging to Pydantic Logfire	logfire

They combine: pip install "BPTK-Py[plotting,server]". 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 most of them run 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. What the browser cannot do is listed under Limitations.

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

Install Python
Clone the BPTK-Py repository
Set up a virtual environment
Open a notebook

Install Python

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

Clone the BPTK-Py repository

The documentation and all of its notebooks are in the website-tutorial folder of the BPTK-Py repository. On the command line, move into a directory where you would like to keep it, then run:

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 website-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 website-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()`

The packages each extra adds are in the table under Extras.