OpenTTDLab 0.0.41

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
• Examples
• API
• 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. (Although with fairly poor scaling properties.)
• Results are extracted from OpenTTD savegames as plain Python dictionaries and lists - reasonably convenient for importing 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 experiments...
results = run_experiment(
    openttd_version='13.4',  # ... for a specific versions of OpenTTD
    opengfx_version='7.1',   # ... and a specific versions of OpenGFX
    seeds=range(0, 10),      # ... for a range of random seeds
    days=365 * 4 + 1,        # ... each for a number of (in game) days
    ais=(
        # ... running specific AIs. In this case a single AI, with no
        # parameters, fetching it from https://bananas.openttd.org/package/ai
        ('trAIns', (), bananas_file('trAIns', '54524149')),
    ),
)

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(
    {
        'seed': row['seed'],
        'date': row['date'],
        'money': row['chunks']['PLYR']['0']['money'],
    }
    for row in results
)
df = df.pivot(index='date', columns='seed', values='money')
fig = px.line(df)
fig.show()

should output a plot much like this one.

Examples

A notebook of the above example and an example measuring the performance of OpenTTDLab are in the examples folder.

API

Running experiments

run_experiment(...)

The core function of OpenTTDLab is the run_experiment function, used to run an experiment and return results extracted from the savegame files that OpenTTD produces. It has the following parameters and defaults.

• ais=()

  The list of AIs to run. See the Fetching AIs section for details on this parameter.

• seeds=(1,)

  An iterable of integers, where each is used to seed the random number generator in a run of OpenTTD.

• days=365 * 4 + 1

  The number of in-game days that each run of OpenTTD should last.

• base_openttd_config=''

  OpenTTD config to run each experiment under. This must be in the openttd.cfg format. This is added to by OpenTTDLab before being passed to OpenTTD.

• max_workers=None

  The maximum number of workers to use to run OpenTTD in parallel. IfNone, then os.cpu_count() defined how many workers run.

• openttd_version=None

  The version of OpenTTD to use. If None, the latest version available at openttd_base_url is used.

• opengfx_version=None

  The version of OpenGFX to use. If None, the latest version available at opengfx_base_url is used.

• openttd_base_url='https://cdn.openttd.org/openttd-releases/

  The base URL used to fetch the list of OpenTTD versions, and OpenTTD binaries.

• opengfx_base_url='https://cdn.openttd.org/opengfx-releases/

  The URL used to fetch the list of OpenGFX versions, and OpenGFX binaries.

• get_http_client=lambda: httpx.Client(transport=httpx.HTTPTransport(retries=3)

  The HTTP client used to make HTTP requests when fetching OpenTTD, OpenGFX, or AIs. Note that the bananas_file function uses a raw TCP connection in addition to HTTP requests, and so not all outgoing connections use the client specified by this.

Fetching AIs

The ais parameter of run_experiment configures which AIs will run, and how their code will be located. Specifically, the ais parameter must be an iterable of (name, params, ai) tuples, where name is the name of the AI, params is an iterable of (key, value) parameters for the AI, and ai must be the return value of any of the following 3 functions.

bananas_file(name, id)

Defines an AI by the name and id of an AI published through OpenTTD's content service at https://bananas.openttd.org/package/ai. This allows you to quickly run OpenTTDLab with a published AI.

local_folder(path)

Defines an AI by the path to a local folder that contains the AI code.

local_file(path)

Defines an AI by the local path to a .tar AI file that contains the AI code.

remote_file(url)

Fetches the AI by the URL of a tar.gz file that contains the AI code. For example, a specific GitHub tag of a repository that contains its code.

[!NOTE] The return value of each of the above is opaque: it should not be used in client code, other than by passing into run_experiment as its ais parameter.

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.