stdvoidsim

Install: pip install stdvoidsim

A community-maintained library of population genetic simulation models for Lovecraftian entities and eldritch horrors.

Built on the stdvoidsim framework, stdvoidsim provides fictional but population-genetically plausible demographic models for creatures from H.P. Lovecraft's Cthulhu Mythos. All models use realistic population genetic parameters and are fully simulatable with msprime and SLiM.

40 species, 80 demographic models.

Available Species

Outer Gods & Great Old Ones

Servitor Races & Engineered Species

Ancient Civilizations

Amphibious & Aquatic

Subterranean Horrors

Dreamlands Creatures

Interdimensional & Temporal

Arctic & Desert

Human-Adjacent Horrors

Quick Start

import stdvoidsim

# Get the Shoggoth species (hexaploid engineered servitors)
species = stdvoidsim.get_species("ShoNig")

# Use the Antarctic Revolt demographic model
model = species.get_demographic_model("AntarcticRevolt_1D31")

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

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

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

CLI Usage

# List all available species
stdvoidsim --help

# Simulate 10 Deep One samples under the Innsmouth Decline model
stdvoidsim DagHyd -d InnsmouthDecline_1M27 -o deep_ones.trees -L 100000 DeepOnes:10

# Simulate Shoggoth rebellion scenario
stdvoidsim ShoNig -d AntarcticRevolt_1D31 -o shoggoths.trees -L 50000 Antarctic:20

Installation

From PyPI (once published):

pip install stdvoidsim

From source (editable):

pip install -e .

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 tell a story consistent with the Mythos lore
• 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 (extreme bottlenecks, very small populations, polyploidy, highly asymmetric migration, etc.).

Citation

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

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

"Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fhtagn."