stdferdowsim

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

A community-maintained library of population genetic simulation models for Persian mythology, the Shahnameh, and Zoroastrian cosmology.

36 species · 360 demographic models emphasizing admixture graphs, ghost populations, and non-tree-like histories.

Placeholder for Ferdowsi portrait — to be replaced

See also: stdgrimmsim — diverse training data from German folklore (32 species, 134 models) · stdvoidsim — stress-testing with extreme Lovecraftian scenarios (40 species, 82 models).

Purpose

stdferdowsim is a fork catalog of stdpopsim: it shares the same API and simulation engines (msprime, SLiM) but replaces the species catalog with fictional taxa from Persian mythology.

Primary use case: benchmarking admixture-graph inference — testing methods that must infer non-tree-like histories including pulse admixture, ghost populations, extinction-recolonization, and complex reticulate topologies with 5-8 populations.

What makes stdferdowsim unique

Unlike the other catalogs, every species in stdferdowsim includes models with:

• Pulse admixture events — not just continuous migration, but discrete gene flow pulses
• Ghost populations — extinct lineages that contributed ancestry before disappearing
• 5-8 population models — far beyond the 4-pop maximum in stdgrimmsim
• Extinction and recolonization — populations that die out and are re-founded
• Asymmetric migration reversal — migration direction changes over time
• Silk Road stepping-stone models — 8-deme geographic models along trade routes

Model Complexity Taxonomy

Available Species

Shahnameh Creatures & Heroes

Spirits, Jinn & Peris

Mythical Birds & Beasts

Zoroastrian Cosmology

Cross-cultural & Regional

Quick Start

import stdferdowsim

# Get the Simurgh species
species = stdferdowsim.get_species("SimAvi")

# Use the ghost admixture model (non-tree-like history)
model = species.get_demographic_model("GhostAdmixture_3F10")

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

# Simulate with msprime
engine = stdferdowsim.get_engine("msprime")
ts = engine.simulate(model, contig, samples={"Main": 20, "Secondary": 10}, seed=42)

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

CLI Usage

# Level 1: single-population constant
stdferdowsim SimAvi -d Constant_1F10 -o simurgh.trees -L 100000 Main:10

# Ghost admixture (3 pops, one extinct)
stdferdowsim DivMaz -d GhostAdmixture_3F10 -o div_ghost.trees -L 100000 Main:10 Secondary:10

# Five-realm admixture graph
stdferdowsim RosHer -d FiveRealm_5F10 -o five_realm.trees -L 50000 Iran:5 Turan:5 Rum:5 Hind:5 Chin:5

# Eight-population Silk Road
stdferdowsim PriJin -d SilkRoad_8F10 -o silk_road.trees -L 50000 Ray:5 Isfahan:5 Shiraz:5 Tabriz:5 Mashad:5 Merv:5 Balkh:5 Samarkand:5

Installation

pip install stdferdowsim

From source (editable):

pip install -e .

Citation

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

• Adrion, et al. (2020) — A community-maintained standard library of population genetic models.
• Lauterbur, et al. (2023) — Expanding the stdpopsim species catalog.

"Be not content with the stories that come before you. Unfold your own myth." — Rumi