stdferdowsim 0.1.0

A library of population genetic simulation models for Persian mythology and the Shahnameh

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.

	stdferdowsim	stdgrimmsim	stdvoidsim
Focus	Admixture graphs & reticulate histories	Diverse training data & benchmarking	Stress-testing & identifiability limits
Species	36 (Persian mythology)	32 (German folklore)	40 (Cthulhu Mythos)
Models	360 (1- to 8-population)	134 (1- to 4-population)	82 (1- and 2-population)
Key feature	Ghost pops, pulse admixture, 5-8 demes	4-cluster rate architecture	Extreme parameters (Ne=1 to 10^6)
Parameter range	Moderate to deep-time	Moderate, plausible	Extreme
Ploidy	All diploid	All diploid	Diploid to hexaploid

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

Level	Type	Count	Examples
1	1-population constant	36	Constant_1F10
2	1-population piecewise (3 epochs)	36	ThreeEpoch_1F10
3	2-population split + migration	36	TwoPopSplit_2F10
4	3-population ghost admixture	36	GhostAdmixture_3F10
5	3-population bidirectional admixture	36	ThreePopAdmix_3F10
6	4-population stepping-stone	36	FourRegion_4F10
7	5-population admixture graph	36	FiveRealm_5F10
8	6-population extinction/recolonization	36	SixPopExtRecolon_6F10
9	2-population migration reversal	36	AsymReversal_2F10
10	8-population Silk Road	36	SilkRoad_8F10

Available Species

Shahnameh Creatures & Heroes

ID	Species	Common Name	Ne	Gen Time	Models
SimAvi	Simurgh avianus	Simurgh (mythical bird)	15,000	200 yr	10
DivMaz	Divus mazandarensis	Div (demon of Mazandaran)	50,000	80 yr	10
AzhDra	Azhdaha draconius	Azhdaha (dragon)	5,000	500 yr	10
RosHer	Rostam heroicus	Rostam-lineage (hero dynasty)	25,000	35 yr	10
RakEqu	Rakhsh equinus	Rakhsh (mythical steed)	3,000	25 yr	10
ZalAlb	Zal albinus	Zal (raised by Simurgh)	20,000	35 yr	10
RudSim	Rudabeh simurghica	Rudabeh-lineage	18,000	30 yr	10
EsfSmi	Esfandiyar smithius	Esfandiyar (bronze-bodied)	32,000	30 yr	10
JamPis	Jamshid pishdadius	Jamshid (Pishdadian age)	60,000	100 yr	10
KayDyn	Kayanian dynasticus	Kayanian (heroic dynasty)	45,000	30 yr	10
BahFir	Bahram firesteed	Bahram-kind	35,000	30 yr	10
PahDiv	Pahlavan divanus	Pahlavan (hero-monster hybrid)	28,000	35 yr	10
SorWiz	Sorcerer wizardus	Sorcerer (jadugar)	30,000	50 yr	10
DouGia	Dough giant	Div-e Sepid (White Demon)	4,000	120 yr	10
AfrHor	Afrasiyab horrens	Afrasiyab (Turanian warlord)	65,000	28 yr	10
TurNom	Turanian nomadicus	Turanian (steppe nomad)	120,000	22 yr	10

Spirits, Jinn & Peris

ID	Species	Common Name	Ne	Gen Time	Models
PriJin	Jinnus persicus	Jinn (elemental spirit)	200,000	30 yr	10
PerPar	Peri paradisi	Peri (fairy/angel spirit)	100,000	40 yr	10
AlDem	Al daemonius	Al (nocturnal demon)	70,000	20 yr	10
GhoUnd	Ghoul underworld	Ghoul (desert undead)	40,000	25 yr	10
DaeWar	Daeva warrior	Daeva (war demon)	90,000	50 yr	10
DraAng	Druj angra	Druj (demon of deceit)	150,000	25 yr	10
GulRos	Gulistan rosagarden	Gul-spirit (rose guardian)	55,000	20 yr	10

Mythical Birds & Beasts

ID	Species	Common Name	Ne	Gen Time	Models
HumBir	Huma paradisica	Huma (bird of paradise)	8,000	150 yr	10
ManTig	Manticore persicus	Manticore (martyaxwar)	12,000	60 yr	10
SenBir	Senmurv birddog	Senmurv (dog-bird hybrid)	10,000	45 yr	10
ChaGri	Chamrosh griffinus	Chamrosh (dog-eagle)	7,000	40 yr	10
ShaSha	Shahbaz shahinus	Shahbaz (royal falcon)	6,000	15 yr	10
GavPri	Gavaevodata primus	Gavaevodata (primordial bull)	2,000	300 yr	10

Zoroastrian Cosmology

ID	Species	Common Name	Ne	Gen Time	Models
FarGlo	Faravahar glorius	Faravahar (guardian spirit)	80,000	60 yr	10
MitSol	Mithra solarius	Mithra (solar deity)	1,000	800 yr	10
YazGua	Yazata guardian	Yazata (divine being)	3,000	500 yr	10
ZorPri	Zoroaster primus	Zoroaster-lineage	10,000	100 yr	10
KhiWis	Khidr wisdomus	Khidr (immortal sage)	500	1,000 yr	10

Cross-cultural & Regional

ID	Species	Common Name	Ne	Gen Time	Models
NarHer	Nart heronius	Nart-spirit (Caucasian-Iranian)	22,000	28 yr	10
MarMor	Marduk mortalis	Marduk-spirit (Mesopotamian)	75,000	45 yr	10

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