.. _sec_catalog:

=======
Catalog
=======

This catalog lists every species from Persian mythology available for
simulation in ``stdferdowsim`` --- 36 species and 360 demographic models.
Each has made-up but population-genetically plausible genomes and demographic
histories featuring admixture graphs, ghost populations, extinction-recolonization,
and complex reticulate topologies with up to 8 populations.

Species are drawn from Ferdowsi's *Shahnameh* (Book of Kings), Zoroastrian
cosmology, and broader Persian/Iranian mythology.

Demography schematic diagrams (one per model) are shown below when available.
To generate them, run from the repo root: ``python docs/generate_demography_figures.py``
(requires ``demesdraw``; install with ``uv sync --extra docs``).

1. Which **chromosome** (:class:`.Genome` object)?
2. Which **model of demographic history** (:class:`.DemographicModel` object)?

Example: simulate Simurgh samples under the ghost-admixture model:

.. code-block:: console

    $ stdferdowsim SimAvi -d GhostAdmixture_3F10 -o simurgh.trees -L 100000 Main:10 Secondary:10


.. _shahnameh-creatures:

Shahnameh Creatures & Heroes
============================

.. _simurgh:

**Simurgh** (*Simurgh avianus*) --- The mythical bird of the Alborz mountains,
who raised Zal, Rostam's father. Ancient, wise, a bridge between worlds.
In the Shahnameh, the Simurgh is both healer and teacher, connecting otherwise
separate lineages --- a natural metaphor for admixture.

.. speciescatalog:: SimAvi

**Div** (*Divus mazandarensis*) --- The demons of Mazandaran, deeply diverged from
the Iranian hero lineages. The Div-e Sepid (White Demon) is the most powerful.
In ``stdferdowsim``, Divs represent ancient, deeply diverged populations.

.. speciescatalog:: DivMaz

**Azhdaha** (*Azhdaha draconius*) --- The Persian dragon, associated with
Mount Damavand. Zahhak, possessed by Ahriman, grew serpents from his shoulders.
Long-lived, rare --- small Ne, very long generation time.

.. speciescatalog:: AzhDra

**Rostam-lineage** (*Rostam heroicus*) --- The greatest hero of the Shahnameh,
from Zabulestan. His lineage spans many generations: Zal, Rostam, Faramarz.
Mixed ancestry (Zal raised by Simurgh, married to Rudabeh of Kabul).

.. speciescatalog:: RosHer

**Rakhsh** (*Rakhsh equinus*) --- Rostam's legendary horse, the only steed
strong enough to carry him. Small population, unique lineage.

.. speciescatalog:: RakEqu

**Zal** (*Zal albinus*) --- Born with white hair, abandoned on the Alborz,
raised by Simurgh. A living admixture between human and divine lineages.

.. speciescatalog:: ZalAlb

**Rudabeh** (*Rudabeh simurghica*) --- Princess of Kabul, descendant of Zahhak,
married to Zal. Her lineage carries both Iranian and foreign ancestry.

.. speciescatalog:: RudSim

**Esfandiyar** (*Esfandiyar smithius*) --- The bronze-bodied warrior,
invulnerable except for his eyes. Kayanian dynasty.

.. speciescatalog:: EsfSmi

**Jamshid** (*Jamshid pishdadius*) --- King of the Pishdadian dynasty,
the golden age of Iran. Eventually overthrown by Zahhak.

.. speciescatalog:: JamPis

**Kayanian** (*Kayanian dynasticus*) --- The Kayanian dynasty of heroes
(Kay Kavus, Kay Khosrow). The heroic age of the Shahnameh.

.. speciescatalog:: KayDyn

**Bahram** (*Bahram firesteed*) --- Associated with fire and victory.
Bahram V (Bahram Gur) is the hunter-king of legend.

.. speciescatalog:: BahFir

**Pahlavan** (*Pahlavan divanus*) --- Hero-monster hybrid lineages.
Some pahlavans (champions) carry Div blood through ancient admixture.

.. speciescatalog:: PahDiv

**Sorcerer** (*Sorcerer wizardus*) --- The jadugar (sorcerers) of the
Shahnameh, practitioners of dark arts, often serving Turanian kings.

.. speciescatalog:: SorWiz

**Div-e Sepid** (*Dough giant*) --- The White Demon, greatest of the
Mazandaran Divs, slain by Rostam in the Seven Labours.

.. speciescatalog:: DouGia

**Afrasiyab** (*Afrasiyab horrens*) --- The Turanian warlord, arch-enemy
of Iran, grandson of Tur son of Feridun. His lineage represents
Turanian-Iranian conflict and occasional admixture.

.. speciescatalog:: AfrHor

**Turanian** (*Turanian nomadicus*) --- The steppe nomad spirits of Turan,
the great enemy civilization in the Shahnameh. Large populations, short
generation times, representing the mobile steppe peoples.

.. speciescatalog:: TurNom


.. _spirits-jinn:

Spirits, Jinn & Peris
======================

**Jinn** (*Jinnus persicus*) --- Elemental spirits of pre-Islamic and
Islamic Persian tradition. Made of smokeless fire, they exist in a
parallel world (Jinnestan). Very large populations, widespread.

.. speciescatalog:: PriJin

**Peri** (*Peri paradisi*) --- Beautiful fairy-like spirits, intermediate
between the divine and mortal realms. In the Shahnameh, Peris sometimes
interbreed with human lineages --- natural admixture events.

.. speciescatalog:: PerPar

**Al** (*Al daemonius*) --- Nocturnal demons from Iranian folklore,
associated with sleep paralysis and childhood illness.

.. speciescatalog:: AlDem

**Ghoul** (*Ghoul underworld*) --- Desert-dwelling undead (ghul),
shape-shifters that prey on travellers. Originated in Persian folklore
before spreading to Arabic tradition.

.. speciescatalog:: GhoUnd

**Daeva** (*Daeva warrior*) --- False gods and war demons in Zoroastrian
cosmology, the opposite of the Yazata. Large populations in the armies
of Ahriman.

.. speciescatalog:: DaeWar

**Druj** (*Druj angra*) --- Demons of deceit and chaos in Zoroastrian
theology, the fundamental force of evil (Angra Mainyu).

.. speciescatalog:: DraAng

**Gul-spirit** (*Gulistan rosagarden*) --- Guardians of the rose garden
(Gulistan), from Saadi's literary tradition. Representing the gentler
spirits of Persian literary mythology.

.. speciescatalog:: GulRos


.. _birds-beasts:

Mythical Birds & Beasts
========================

**Huma** (*Huma paradisica*) --- The bird of paradise whose shadow
bestows kingship. Never lands on the ground. Rare, with long generation times.

.. speciescatalog:: HumBir

**Manticore** (*Manticore persicus*) --- The martyaxwar (man-eater),
a composite creature with a human face, lion body, and scorpion tail.
Originally Persian (from *mardykhor*), a natural metaphor for admixture
between deeply diverged lineages.

.. speciescatalog:: ManTig

**Senmurv** (*Senmurv birddog*) --- A hybrid creature with the body of a
dog and the wings and head of a bird. Featured in Sasanian art.

.. speciescatalog:: SenBir

**Chamrosh** (*Chamrosh griffinus*) --- Dog-eagle hybrid, disperser of
seeds from the world-tree. Related to the Simurgh but smaller.

.. speciescatalog:: ChaGri

**Shahbaz** (*Shahbaz shahinus*) --- The royal falcon, symbol of Persian
kingship and hunting tradition. Short generation time, moderate populations.

.. speciescatalog:: ShaSha

**Gavaevodata** (*Gavaevodata primus*) --- The primordial bull of
Zoroastrian cosmology, from whose body all animals were created after its
death. Extremely long generation time, very small Ne --- the deepest
ancestral lineage.

.. speciescatalog:: GavPri


.. _zoroastrian:

Zoroastrian Cosmology
=====================

**Faravahar** (*Faravahar glorius*) --- Guardian spirits (fravashi) that
protect each person. The winged disc symbol of Zoroastrianism.

.. speciescatalog:: FarGlo

**Mithra** (*Mithra solarius*) --- The deity of covenant and the sun,
predating Zoroaster. Later adopted into Roman religion as Mithras.
Very long generation time, small populations.

.. speciescatalog:: MitSol

**Yazata** (*Yazata guardian*) --- Divine beings worthy of worship in
Zoroastrian theology, including Asha (truth), Vohu Manah (good mind),
and others. Small populations, deep time.

.. speciescatalog:: YazGua

**Zoroaster-lineage** (*Zoroaster primus*) --- The prophet Zarathustra's
spiritual lineage, keepers of the sacred fire.

.. speciescatalog:: ZorPri

**Khidr** (*Khidr wisdomus*) --- The Green One, an immortal sage who
appears at moments of crisis. The smallest Ne and longest generation time
in the catalog --- an almost-singleton immortal lineage.

.. speciescatalog:: KhiWis


.. _cross-cultural:

Cross-cultural & Regional
=========================

**Nart-spirit** (*Nart heronius*) --- From the Nart sagas, the heroic
cycle shared between Caucasian and Iranian peoples. Represents
cultural and genetic exchange between the Caucasus and Iran.

.. speciescatalog:: NarHer

**Marduk-spirit** (*Marduk mortalis*) --- A Mesopotamian-Iranian
crossover spirit, representing the deep cultural exchange between
Mesopotamia and the Iranian plateau.

.. speciescatalog:: MarMor


.. _generic-models:

Generic models
==============

In addition to the species-specific models listed in this catalog, ``stdferdowsim`` offers
generic demographic models that can be run with any species.
These are described in the :ref:`API <sec_api_generic_models>`.

 - :meth:`stdferdowsim.PiecewiseConstantSize`
 - :meth:`stdferdowsim.IsolationWithMigration`