.. stdferdowsim documentation index file

Welcome to stdferdowsim
=======================

**Population genetic simulations for Persian mythology and the Shahnameh.**

``stdferdowsim`` is a library of demographic and genome models for creatures,
spirits, and heroes from Persian mythology, Ferdowsi's *Shahnameh*, and
Zoroastrian cosmology. Simulate Simurgh, Divs, Jinn, Manticores, and dozens
more with made-up but population-genetically plausible parameters --- powered by
`msprime <https://tskit.dev/msprime/>`_ and `SLiM <https://messerlab.org/slim/>`_
and built on the `stdpopsim <https://stdpopsim.readthedocs.io/>`_ framework.

.. epigraph::
   Be not content with the stories that come before you.
   Unfold your own myth.
   --- *Rumi*

First steps
-----------

- **Install:** :ref:`Installation <sec_installation>` --- get ``stdferdowsim`` on your machine.
- **Explore:** :ref:`Catalog <sec_catalog>` --- 36 species and 360 demographic models.
- **Run:** :ref:`Tutorial <sec_tutorial>` --- examples and workflows.

.. admonition:: Quick run
   :class: quick-run

   Install and simulate 10 Simurgh samples with a ghost-admixture model:

   .. code-block:: console

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

   Then open ``simurgh.trees`` in `tskit <https://tskit.dev/tskit/>`_ or
   :ref:`continue with the tutorial <sec_tutorial>`.

Catalog at a glance
-------------------

The full :doc:`catalog <catalog>` lists every species and demographic model.
By category:

.. container:: catalog-at-a-glance

   - :ref:`Shahnameh Creatures & Heroes <shahnameh-creatures>`
     - *Simurgh avianus*, *Divus mazandarensis*, *Azhdaha draconius*, *Rostam heroicus*
   - :ref:`Spirits, Jinn & Peris <spirits-jinn>`
     - *Jinnus persicus*, *Peri paradisi*, *Al daemonius*, *Daeva warrior*
   - :ref:`Mythical Birds & Beasts <birds-beasts>`
     - *Huma paradisica*, *Manticore persicus*, *Senmurv birddog*, *Chamrosh griffinus*
   - :ref:`Zoroastrian Cosmology <zoroastrian>`
     - *Faravahar glorius*, *Mithra solarius*, *Yazata guardian*
   - :ref:`Cross-cultural & Regional <cross-cultural>`
     - *Nart heronius*, *Marduk mortalis*
   - :ref:`Generic models <generic-models>`
     - Generic demographic models (any species)

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   introduction
   installation
   catalog
   tutorial
   cli_arguments
   api
   development
   changelogs

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`