OpenTTDLab 0.0.16

Python framework for running reproducible experiments using OpenTTD

OpenTTDLab - Run reproducible experiments using OpenTTD

---

OpenTTDLab is a Python framework for running reproducible experiments using OpenTTD, and extracting results from them. An experiment in OpenTTDLab terms is the combination of:

• Exact version of OpenTTD, any AIs used, and OpenTTDLab itself
• Ranges of values for OpenTTD config settings, command line arguments and random seed

This can be configured/extracted for each experiment in either machine or human readable forms, for use in code or publishing respectively.

OpenTTDLab is based on TrueBrain's OpenTTD Savegame Reader, but it is not affiliated with OpenTTD.

[!NOTE] Work in progress. This README 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, save_config

# Run the experiment and get results
results, config = run_experiment()

# 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)

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)

Licenses and attributions

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

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

The OpenTTDLab logo is a modified version of the OpenTTD logo. The OpenTTD logo is 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.

OpenTTD is authored by the OpenTTD team. OpenTTD is also licensed under the GNU General Public License version 2.0.