OpenTTDLab 0.0.25

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.

[!NOTE] Work in progress. Only some of the things in this README will work: it serves as a rough design spec.

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, remote_file, save_config

# Run the experiment for a range of random seeds
results, config = run_experiment(
    days=365 * 4 + 1,
    seeds=range(0, 10),
    ais=(
        # remote_file: takes a url of a .tar.gz AI file
        # local_file: takes a path to a local .tar AI file
        ('trAIns', remote_file('https://github.com/lhrios/trains/archive/refs/tags/2014_02_14.tar.gz')),
    ),
)

# Print the results...
print(results)

# ... and config
print(config)

# ... which can be saved to a file and then shared (or archived)
save_config('my-experiment-{experiment_id}.yml', config)

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.

Reproducing an experiment

If you have the config from a previous experiment, you can pass it into run_experiment to exactly reproduce. If for some reason it cannot be reproduced, it will error.

from openttdlab import run_experiment, load_config

# Load the config from a file...
config = load_config('my-config-a5e95018.yml')

# ... and use it to run the same experiment
results, config = run_experiment(config=config)

print(results)

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.