stdgrimmsim

Install: pip install stdgrimmsim · Docs: stdgrimmsim.readthedocs.io

A community-maintained library of population genetic simulation models for German folklore, fairy tales, and mythology, with a strong focus on geographic regions: Bavaria (Bayern), Prussia (Preußen, East Prussia, Masuria), Rhine, Harz, Black Forest, and more.

Forked from stdvoidsim (and ultimately stdpopsim), stdgrimmsim provides fictional but population-genetically plausible demographic models for creatures and spirits from German-speaking folklore. Demographics are tied to real regions (Upper Bavaria, Bavarian Forest, East Prussia, Kurische Nehrung, Masurian Lakes, etc.). All models use realistic population genetic parameters and are fully simulatable with msprime and SLiM.

32 species, 150 demographic models — Bavaria, Prussia, Saxony, Pomerania, Lower Saxony/Bremen, Thuringia/Hesse, and more Grimm fairy-tale species.

Available Species

Fairy tale & Grimm

Water & river spirits

Bavaria (Bayern)

Demographic models use Upper Bavaria (Oberbayern), Bavarian Forest (Bayrischer Wald), Allgäu, Salzburg, Tyrol, Oberpfalz.

Prussia (Preußen)

Demographic models use East Prussia (Ostpreußen), West Prussia, Berlin–Brandenburg, Kurische Nehrung (Curonian Spit), Memelland, Samland, Masurian Lakes, Spirdingsee (Śniardwy), Mauersee (Mamry).

Saxony (Sachsen) & Pomerania (Pommern)

Demographic models use Erzgebirge, Vogtland, Dresden region (Saxony); Usedom, Rügen, Stettin (Pomeranian Baltic).

Thuringia & Hesse (Grimm heartland)

Rumpelstiltskin (RumSti) and other Grimm species use Thuringia (Thüringen) and Hesse (Hessen) populations — the core Grimm fairy-tale region.

Lower Saxony & Bremen

Town Musicians of Bremen (BreSta) use Bremen, Lower Saxony (Niedersachsen), Lüneburg Heath (Lüneburger Heide).

Mountain & regional mythology

Beings & hauntings

Dragons & medieval bestiary

Pre-Christian & tribal Germanic

17th-18th century folklore

Quick Start

import stdgrimmsim

# Get the mountain dwarf species (Schwarzwald / Harz)
species = stdgrimmsim.get_species("ZweBerg")

# Use the Black Forest single-population demographic model
model = species.get_demographic_model("BlackForest_1D12")

# Set up a generic contig of 100kb
contig = species.get_contig(length=100_000)

# Simulate with msprime
engine = stdgrimmsim.get_engine("msprime")
ts = engine.simulate(model, contig, samples={"BlackForest": 20}, seed=42)

print(f"Trees: {ts.num_trees}, Mutations: {ts.num_mutations}")

CLI Usage

# List all available species
stdgrimmsim --help

# Simulate 10 Black Forest dwarf samples
stdgrimmsim ZweBerg -d BlackForest_1D12 -o dwarves.trees -L 100000 BlackForest:10

# Simulate Nix (water spirit) from Rhine and Elbe
stdgrimmsim NixRhe -d RhineElbe_2D12 -o nix.trees -L 50000 Rhine:10 Elbe:10

# Bavaria: Wolpertinger (Upper Bavaria + Bavarian Forest)
stdgrimmsim WolBay -d UpperBavariaBavarianForest_2D12 -o wolpertinger.trees -L 50000 UpperBavaria:10 BavarianForest:10

# Prussia: Puk (East Prussia and Berlin–Brandenburg)
stdgrimmsim PukPru -d EastPrussiaBerlinBrandenburg_2D12 -o puk.trees -L 50000 EastPrussia:10 BerlinBrandenburg:10

Installation

From PyPI (once published):

pip install stdgrimmsim

From source (editable):

pip install -e .

SLiM engine (optional)

To run simulations with the SLiM engine instead of msprime, install SLiM and ensure slim is on your PATH. Use SLiM 3.x (e.g. 3.7); the generated scripts target the SLiM 3 API.

stdgrimmsim ZweBerg -d BlackForest_1D12 -e slim -o dwarves.trees -L 10000 BlackForest:10

Development with uv

uv makes installing and running tests fast. Install uv (pip install uv or brew install uv), then from the repo root:

make install    # editable install + dev/CI dependencies
make test       # run test suite
make test-cov   # run tests with coverage
make quick-sim  # run quick simulation check (.test/run_simulation.py)

Or without Make: uv pip install -e ., uv pip install -r requirements/CI/requirements.txt, then uv run pytest -v tests.

Releasing to PyPI

The package uses setuptools_scm for versioning; the version is read from git tags. To publish a release to PyPI:

1. One-time: Create a PyPI account and an API token at pypi.org/manage/account/token/. Add the token as repository secret PYPI_API_TOKEN in GitHub (Settings → Secrets and variables → Actions).
2. Each release: Tag the commit with a semantic version and push. The GitHub Action will build and upload to PyPI:

   git tag v0.1.0
   git push origin v0.1.0
   

   Use a new tag for each release (e.g. v0.1.1, v0.2.0). To test without publishing, use Test PyPI and set TWINE_REPOSITORY_URL in the workflow or run twine upload --repository-url https://test.pypi.org/legacy/ dist/* locally.

Design Philosophy

Each species has:

• Made-up but internally consistent genome: chromosome counts, lengths, ploidy, mutation rates, and recombination rates chosen to reflect the creature's biology
• Demographic models: population size changes, bottlenecks, splits, and migrations that reflect regional folklore and fairy-tale settings (Bavaria, Prussia, Black Forest, Harz, Rhine, Masuria, etc.)
• Simulatable parameters: all values are chosen so that simulations complete in reasonable time and produce meaningful coalescent trees

The models are designed to be useful for testing population genetic inference methods on non-standard demographic scenarios (bottlenecks, splits, migrations) in a fun, folklore-themed setting.

Citation

This project is a fork of stdvoidsim and stdpopsim. If you use the simulation framework, please cite:

• Adrion, et al. (2020)
• Lauterbur, et al. (2023)

"Es war einmal …"