OpenTTDLab 0.0.33

Python framework for running reproducible experiments using OpenTTD

OpenTTDLab - Run reproducible experiments using OpenTTD

OpenTTDLab is a Python framework for using OpenTTD to run reproducible experiments and extracting results from them, with as few manual steps as possible.

OpenTTDLab is based on Patric Stout's OpenTTD Savegame Reader.

---

Contents

• Features
• Installation
• Running an experiment
• Plotting results
• Compatibility
• Licenses and attributions

---

Features

• Allows you to easily run OpenTTD in a headless mode (i.e. without a graphical interface) over a variety of configurations.
• And allows you to do this from Python code - for example from a Jupyter Notebook.
• As is typical from Python code, it is cross platform - allowing to share code snippets between macOS, Windows, and Linux, even though details like how to install and start OpenTTD are different on each platform.
• Downloads (and caches) OpenTTD, OpenGFX, and AIs - no need to download these separately or through OpenTTD's built-in content browser.
• Transparently parallelises runs of OpenTTD, by default up to the number of CPUs.
• Outputs results extracted from savegames, and in a format convenient to import into tools such as pandas for analysis or visualisation.

Installation

OpenTTDLab is distributed via PyPI, and so can usually be installed using pip.

python -m pip install OpenTTDLab

When run on macOS, OpenTTDLab has a dependency that pip does not install: 7-zip. To install 7-zip, first install Homebrew, and then use Homebrew to install the p7zip package that contains 7-zip.

brew install p7zip

You do not need to separately download or install OpenTTD (or OpenGFX) in order to use OpenTTDLab. OpenTTDLab itself handles downloading them.

Running an experiment

The core function of OpenTTD is the run_experiment function.

from openttdlab import run_experiment, bananas_file

# Run the experiment for a range of random seeds
results = run_experiment(
    days=365 * 4 + 1,
    seeds=range(0, 10),
    ais=(
        # 3 ways of using Ais
        # remote_file: takes a url of a .tar.gz AI file, e.g. a GitHub tag
        # local_file: takes a path to a local .tar AI file
        # bananas_file: takes the name and ID from https://bananas.openttd.org/package/ai
        ('trAIns', bananas_file('trAIns', '54524149')),
    ),
)

# Print the results
print(results)

Plotting results

OpenTTD does not require any particular library for plotting results. However, pandas and Plotly Express are common options for plotting from Python. For example if you have a results object from run_experiment as in the above example, the following code

import pandas as pd
import plotly.express as px

df = pd.DataFrame(results)
df = df.pivot(index='date', columns='seed', values='money')
fig = px.line(df)
fig.show()

should output a plot much like this one.

Compatibility

• Linux (tested on Ubuntu 20.04), Windows (tested on Windows Server 2019), or macOS (tested on macOS 11)
• Python >= 3.8.0 (tested on 3.8.0 and 3.12.0)

Licenses and attributions

TL;DR

OpenTTDLab is licensed under the GNU General Public License version 2.0.

In more detail

OpenTTDLab is based on Patric Stout's OpenTTD Savegame Reader, licensed under the GNU General Public License version 2.0.

The OpenTTDLab logo is a modified version of the OpenTTD logo, authored by the OpenTTD team. The OpenTTD logo is also licensed under the GNU General Public License version 2.0.

The .gitignore file is based on GitHub's Python .gitignore file. This was originally supplied under CC0 1.0 Universal. However, as part of OpenTTDLab it is licensed under GNU General Public License version 2.0.

trAIns is authored by Luis Henrique O. Rios, and licensed under the GNU General Public License version 2.0.

OpenTTD and OpenGFX are authored by the OpenTTD team. Both are licensed under the GNU General Public License version 2.0.