zombi2 0.2.0__tar.gz

zombi2-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: rust
+
+      # Build and install the compiled engine FIRST. zombi2 pins
+      # zombi2_core==<version>, which is not on an index during development,
+      # so installing it from ./rust here satisfies that pin locally and the
+      # editable install below never reaches out for it.
+      - name: Build and install the compiled gene-family engine
+        run: pip install ./rust
+
+      - name: Install ZOMBI2 (with dev extras)
+        run: pip install -e ".[dev]"
+
+      # The built-in genome model has no pure-Python fallback, and its tests
+      # skip (green) when the extension is absent. Fail loudly instead, so CI
+      # can never pass while silently leaving the compiled path untested.
+      - name: Require the Rust engine (fail, don't skip)
+        run: python -c "import zombi2; assert zombi2.rust_available(), 'zombi2_core (Rust engine) is not built'"
+
+      - name: Run the test suite
+        run: pytest -q
+
+  docs:
+    name: docs (mkdocs --strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      # The docs build imports zombi2 (via mkdocstrings) but does not exercise
+      # the compiled engine -- zombi2._rust degrades gracefully when zombi2_core
+      # is absent. Install without deps to skip the compiled-engine pin (no Rust
+      # toolchain needed here), then add just what the docs build imports.
+      - name: Install ZOMBI2 (docs deps, engine-free)
+        run: |
+          pip install -e . --no-deps
+          pip install "numpy>=1.24" mkdocs-material "mkdocstrings[python]"
+
+      - name: Build the documentation (strict)
+        run: mkdocs build --strict

zombi2-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,195 @@
+name: Release
+
+# Builds distributions for both packages that make up ZOMBI2:
+#   * zombi2_core -- the compiled Rust engine, one abi3 wheel per platform
+#     (CPython 3.10+) built with maturin, plus an sdist source fallback.
+#   * zombi2 -- the pure-Python front end, a single wheel + sdist.
+#
+# Publishing uses PyPI Trusted Publishing (OIDC) -- no stored API token. It is
+# GATED so nothing goes out by accident:
+#   * PyPI  -- only when a GitHub Release is published.
+#   * TestPyPI -- only on a manual run with the `testpypi` box ticked.
+# See docs/publishing.md for the one-time PyPI setup (each project needs a
+# trusted publisher pointing at this workflow). Until that is configured the
+# publish jobs fail safely at the OIDC step and nothing is uploaded.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: "Publish the built distributions to TestPyPI"
+        type: boolean
+        default: false
+
+permissions: {}
+
+jobs:
+  core-wheels:
+    name: core wheel (${{ matrix.platform.target }})
+    runs-on: ${{ matrix.platform.runner }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - { runner: ubuntu-latest, target: x86_64, manylinux: auto }
+          - { runner: ubuntu-latest, target: aarch64, manylinux: auto }
+          # Both macOS wheels build on the Apple Silicon runner: arm64 natively
+          # and x86_64 cross-compiled. GitHub's Intel macos-13 runners are being
+          # retired and queue indefinitely, which used to stall the whole matrix.
+          - { runner: macos-14, target: aarch64 }
+          - { runner: macos-14, target: x86_64 }
+          - { runner: windows-latest, target: x64 }
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      # abi3-py310 (see rust/Cargo.toml) makes this one stable-ABI wheel per
+      # platform, usable on CPython 3.10 and newer.
+      - name: Build the abi3 wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          working-directory: rust
+          target: ${{ matrix.platform.target }}
+          manylinux: ${{ matrix.platform.manylinux || 'auto' }}
+          args: --release --out dist
+          sccache: "true"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-core-${{ matrix.platform.runner }}-${{ matrix.platform.target }}
+          path: rust/dist/*.whl
+
+  core-sdist:
+    name: core sdist
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+      - name: Build the sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          working-directory: rust
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-core-sdist
+          path: rust/dist/*.tar.gz
+
+  zombi2-dist:
+    name: zombi2 wheel + sdist
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      # zombi2 is pure Python (hatchling), so it builds without numpy, the
+      # Rust toolchain, or zombi2_core -- those are runtime dependencies only.
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build --outdir dist .
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-zombi2
+          path: dist/*
+
+  # ---- publishing (gated, Trusted Publishing / OIDC) ---------------------
+
+  # Each package publishes from its own job with its own GitHub Environment.
+  # PyPI Trusted Publishing keys on (owner, repo, workflow, environment), and a
+  # *pending* publisher must be unique on those four fields -- so two
+  # not-yet-created projects cannot share one environment. Hence:
+  #   zombi2      -> environments `testpypi` / `pypi`
+  #   zombi2_core -> environments `testpypi-core` / `pypi-core`
+  # The zombi2 jobs wait on the core job so the exactly-pinned engine is
+  # already on the index before the front end that depends on it.
+
+  publish-testpypi-core:
+    name: publish zombi2_core to TestPyPI
+    if: github.event_name == 'workflow_dispatch' && inputs.testpypi
+    needs: [core-wheels, core-sdist]
+    runs-on: ubuntu-latest
+    environment: testpypi-core
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: dist-core-*
+          path: dist-core
+          merge-multiple: true
+      - name: Publish zombi2_core
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist-core
+          repository-url: https://test.pypi.org/legacy/
+          attestations: false
+
+  publish-testpypi-zombi2:
+    name: publish zombi2 to TestPyPI
+    if: github.event_name == 'workflow_dispatch' && inputs.testpypi
+    needs: [zombi2-dist, publish-testpypi-core]
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist-zombi2
+          path: dist-zombi2
+      - name: Publish zombi2
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist-zombi2
+          repository-url: https://test.pypi.org/legacy/
+          attestations: false
+
+  publish-pypi-core:
+    name: publish zombi2_core to PyPI
+    if: github.event_name == 'release'
+    needs: [core-wheels, core-sdist]
+    runs-on: ubuntu-latest
+    environment: pypi-core
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: dist-core-*
+          path: dist-core
+          merge-multiple: true
+      - name: Publish zombi2_core
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist-core
+
+  publish-pypi-zombi2:
+    name: publish zombi2 to PyPI
+    if: github.event_name == 'release'
+    needs: [zombi2-dist, publish-pypi-core]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist-zombi2
+          path: dist-zombi2
+      - name: Publish zombi2
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist-zombi2

zombi2-0.2.0/.gitignore

@@ -0,0 +1,74 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# Rust extension build artifacts (source is committed; builds are not)
+rust/target/
+*.whl
+
+# Testing / envs
+.pytest_cache/
+.venv/
+venv/
+.ipynb_checkpoints/
+
+# Simulation outputs
+out/
+/tmp/
+
+# Built docs site
+site/
+
+# Private didactic material (kept locally, not published)
+docs/non_independence.pdf
+docs/non_independence.tex
+
+# Local publication-prep working files (not part of the public repo)
+PUBLICATION_READINESS_REPORT.md
+PUBLICATION_READINESS_REPORT.pdf
+coleman_biorxiv.pdf
+
+# --- Generated artifacts: regenerable outputs; the sources that produce them ARE tracked ---
+
+# Offline single-file docs mirror (rebuild with tools/build_docs_html.py)
+/zombi2-docs.html
+
+# Publication figure renders — regenerate with figures/scripts/*.py
+# (the scripts and the small .nwk fixtures stay tracked; docs/img/*.svg is the served copy)
+figures/**/*.png
+figures/**/*.svg
+
+# Compiled analysis reports and regenerated figures
+# (run scripts, *.json results and *.tex sources stay tracked)
+analyses/**/*.pdf
+analyses/**/figures/*.png
+analyses/**/figures/*.svg
+analyses/**/figs/*.png
+analyses/**/figs/*.svg
+# ...except the performance overview embedded in README.md
+!analyses/performance/figures/overview.png
+
+# Compiled coupling explainer (keep the .tex)
+/docs/coupling_explained.pdf
+
+# LaTeX build artifacts
+*.aux
+*.log
+*.out
+*.toc
+.texmf-var/
+.tmptex/
+
+# OS
+.DS_Store
+
+# Multi-agent coordination log (shared via the working tree, not committed)
+HANDOFF.md
+
+# Phylustrator is a separate editable git checkout (figure tool), not vendored here
+tools/Phylustrator/

zombi2-0.2.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to ZOMBI2 are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-07-07
+
+First public release. ZOMBI2 is a ground-up redesign of
+[ZOMBI](https://github.com/AADavin/Zombi).
+
+### Added
+
+- **Species trees** — backward (reconstructed) and forward (complete) birth–death and Yule,
+  episodic/skyline rate shifts, fossilized birth–death and incomplete sampling, ClaDS /
+  diversity-dependent / clade-shift diversification, mass extinctions, and ghost lineages.
+  Backward trees scale to millions of tips on a laptop via a native Rust engine.
+- **Gene families** — duplication, transfer, loss and origination along a species tree, with
+  uniform, family-sampled and genome-wise rate models; ordered chromosomes with inversions and
+  transpositions; and nucleotide-resolution genomes. Output as full event logs, compact event
+  traces, or counts-only sparse profiles, with parallel replicates.
+- **Traits** — Brownian motion, Ornstein–Uhlenbeck, early burst, Mk, threshold,
+  correlated-binary, hidden-state and multi-optimum models, Pagel transforms, and DEC
+  biogeography, evolved over a phylogeny.
+- **Sequences** — a gene × lineage relaxed-clock family (strict, UCLN, UGAM, white-noise,
+  autocorrelated-lognormal, CIR) that rescales gene trees from time into substitutions/site,
+  plus nucleotide substitution models (JC, K80, HKY, GTR + Gamma).
+- **Coevolution** — a unified `coevolve` command that couples species, traits and genes along
+  six directed edges via `--couple driver:target`.
+- **Command-line interface** — `zombi2 species | genomes | trait | sequence | coevolve`, with
+  grouped, sectioned help and a per-run reproducibility manifest (version, seed, full command
+  line and resolved parameters).
+- **Packaging** — MIT license, `CITATION.cff`, and PyPI metadata.
+
+### Notes
+
+- ABC inference of DTL rates from an empirical copy-number profile (`zombi2.matching`) is
+  available as an experimental Python API but is withheld from the command line in this release.
+- The default (built-in) gene-family engine is a compiled Rust extension; build it once with
+  maturin (see [installation](docs/installation.md)).

zombi2-0.2.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: "If you use ZOMBI2, please cite it using the metadata in this file."
+title: "ZOMBI2: a phylogenetic simulator of species trees, genomes, traits and sequences"
+abstract: >-
+  ZOMBI2 simulates evolution in two steps: it builds a species tree and then evolves
+  gene families along it under duplication, transfer, loss and origination, together
+  with phenotypic traits and molecular sequences. It is a ground-up redesign of ZOMBI,
+  with a fast Rust engine, a command-line interface and a composable Python library.
+type: software
+authors:
+  - given-names: "Adrián A."
+    family-names: "Davin"
+    email: "aaredav@gmail.com"
+version: "0.2.0"
+license: "MIT"
+repository-code: "https://github.com/AADavin/zombi2"
+url: "https://github.com/AADavin/zombi2"
+keywords:
+  - phylogenetics
+  - simulation
+  - gene families
+  - birth-death
+  - evolution
+# When the ZOMBI2 paper is published, add its DOI and a `preferred-citation:` block here
+# so that citations resolve to the article rather than the software repository.

zombi2-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to ZOMBI2
+
+Thanks for your interest in ZOMBI2! Bug reports, feature ideas and pull requests are all
+welcome.
+
+## Development setup
+
+ZOMBI2 needs Python ≥ 3.10. The library itself is pure Python (only `numpy`), but the default
+gene-family engine is a compiled Rust extension that you build once with
+[maturin](https://www.maturin.rs/).
+
+```bash
+git clone https://github.com/AADavin/zombi2.git
+cd zombi2
+
+# the compiled gene-family engine FIRST (needed for the default `genomes` model
+# and its tests) -- zombi2 depends on zombi2_core, which isn't on an index during
+# development, so building it here satisfies that pin locally
+pip install ./rust
+
+# the library + dev tools (pytest, scipy)
+pip install -e ".[dev]"
+```
+
+Species trees, traits, sequences and the flexible-rate genome models run in pure Python, but
+the built-in `genomes` engine — and the tests that cover it — need the compiled extension.
+
+## Running the tests
+
+```bash
+pytest
+```
+
+The suite is deterministic (seeded) and hermetic — no network, no external data. If
+`zombi2.rust_available()` is `False`, the Rust-backed tests **skip** rather than fail, so make
+sure you built the engine (above) before concluding the suite passed. CI builds it and treats a
+missing engine as an error, so the compiled path is always exercised there.
+
+## Adding a model
+
+ZOMBI2 grows by **adding models, not editing the engine**. If you are contributing a model,
+follow the contract:
+
+- [Adding a model](docs/contributing/adding-a-model.md) — the interface for each level and the
+  end-to-end checklist (implement → export → CLI → validate → document).
+- [Conventions](docs/contributing/conventions.md) — the names, outputs, seeding, and CLI grammar
+  every model follows, so the suite reads as one tool.
+
+**The hard rule: no model enters the core without an oracle or a statistical test.** A test that
+only asserts "it runs without error" is not validation — see [Validation](docs/validation.md).
+This is enforced in review.
+
+## Documentation
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve            # live preview at http://127.0.0.1:8000
+mkdocs build --strict   # what CI runs
+```
+
+The book-style manual lives in `manual/` (Pandoc → XeLaTeX); see `manual/README.md` for how to
+build it.
+
+## Submitting changes
+
+1. Branch off `main`.
+2. Keep each pull request focused. Add or update tests for any behaviour change, and prefer
+   asserting real invariants — seeded determinism, conservation laws, analytic/oracle values —
+   over "it runs without error".
+3. Match the surrounding style: public modules, classes and functions carry docstrings.
+4. Open a pull request. CI must pass — `pytest` on Python 3.10–3.12 with the Rust engine built,
+   plus a strict documentation build.
+
+## License
+
+ZOMBI2 is released under the **MIT License** (see
+[`LICENSE`](LICENSE)). By contributing, you agree that your contributions are licensed under the
+same terms.

zombi2-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrián A. Davin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zombi2-0.2.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: zombi2
+Version: 0.2.0
+Summary: A phylogenetic simulator of species trees and gene families
+Project-URL: Homepage, https://github.com/AADavin/zombi2
+Project-URL: Repository, https://github.com/AADavin/zombi2
+Project-URL: Issues, https://github.com/AADavin/zombi2/issues
+Author: Adrian A. Davin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: birth-death,evolution,gene families,phylogenetics,simulation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: zombi2-core==0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: scipy>=1.10; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# ZOMBI2
+
+[![CI](https://github.com/AADavin/zombi2/actions/workflows/ci.yml/badge.svg)](https://github.com/AADavin/zombi2/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+
+**A simulator suite for genome evolution.**
+
+ZOMBI2 simulates how genomes evolve along a phylogeny across **four levels** — **species
+trees**, the **genomes** (gene families) that evolve along them, phenotypic **traits**, and
+molecular **sequences** — plus their **coevolution**, as one composable, seeded, fully
+reproducible suite. Use it to generate benchmark datasets with known ground truth for
+phylogenetic and comparative methods.
+
+---
+
+## Install
+
+```bash
+pip install zombi2
+```
+
+Prebuilt wheels are published for Linux, macOS, and Windows (CPython 3.10+), including the
+native engine — no toolchain required. Building from source is covered in the
+[installation guide](docs/installation.md).
+
+---
+
+## Quickstart
+
+Each level is its own subcommand — run whichever you need. Here a dated species tree, then
+gene families evolving along it under duplication, transfer, loss, and origination:
+
+```bash
+zombi2 species --birth 1 --death 0.3 --tips 50 --age 5 --seed 1  -o run/
+zombi2 genomes --tree run/species_tree.nwk \
+    --dup 0.2 --trans 0.1 --loss 0.25 --orig 0.5 --seed 42       -o run/
+```
+
+`zombi2 <command> -h` documents each of `species`, `genomes`, `trait`, `sequence`, and
+`coevolve`; see the [quickstart](docs/quickstart.md) and [CLI reference](docs/cli.md).
+
+From Python, every model is a first-class object you can compose:
+
+```python
+import zombi2 as z
+
+tree = z.simulate_species_tree(z.BirthDeath(birth=1.0, death=0.3), n_tips=20, age=5.0, seed=1)
+genomes = z.simulate_genomes(tree, duplication=0.2, transfer=0.1, loss=0.25,
+                             origination=0.5, initial_families=40, seed=42)
+
+genomes.write("run/")           # gene trees, event tables, transfers, copy-number profiles
+```
+
+---
+
+## Levels
+
+ZOMBI2 is organized around **four levels of evolution**. Each conditions on the ones above it,
+and you run whichever you need — a species tree, then genomes and/or traits along it, then
+sequences along the resulting gene trees — composed into one seeded, reproducible run.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/img/four_levels_dark.svg">
+    <img alt="The four levels of evolution ZOMBI2 simulates: species trees, genomes, traits, and sequences" src="docs/img/four_levels.svg" width="460">
+  </picture>
+</p>
+
+A broad library, grouped by the level it acts on. Each links to its guide.
+
+- **[Species trees](docs/guide/species-trees.md)** — birth–death (backward and forward),
+  episodic/skyline shifts, fossilized birth–death, incomplete sampling, diversity-dependent
+  and per-lineage (ClaDS) diversification, mass extinctions, and ghost lineages
+  ([full list](docs/species_tree_models.md)).
+- **[Genomes](docs/guide/genomes.md)** — gene families under duplication, transfer, loss,
+  and origination (DTL) with shared / family-sampled / genome-wise / per-branch rates and a full
+  [transfer model](docs/guide/transfers.md); plus genome **structure** —
+  [ordered chromosomes](docs/guide/ordered-genomes.md) with rearrangements and
+  [nucleotide-resolution genomes](docs/guide/nucleotide-genomes.md) where genes emerge as blocks.
+- **[Traits](docs/guide/traits.md)** — Brownian motion, Ornstein–Uhlenbeck, and early burst
+  (continuous); Mk and threshold (discrete); DEC biogeography.
+- **[Sequences](docs/guide/sequences.md)** — substitution models
+  (JC/K80/HKY/GTR + Gamma, and empirical amino-acid models) along the gene trees, with a family
+  of [relaxed molecular clocks](docs/guide/rate-variation.md) (strict, uncorrelated
+  lognormal/gamma, autocorrelated, Cox–Ingersoll–Ross) rescaling time into substitutions.
+
+---
+
+## Combining levels
+
+**Coevolution** couples any two levels so they drive each other with
+`coevolve --couple driver:target`: state-dependent diversification (SSE), cladogenetic change,
+key innovations, and trait-linked gene families. See the
+[coevolution models](docs/models/coevolution.md) guide.
+
+---
+
+## Performance
+
+The built-in models run on a native **Rust** engine and scale to millions of tips on a
+laptop: a backward species tree of 1M tips builds in ~6 s, and gene families over a 100k-tip
+tree simulate in ~1 s as copy-number profiles. On one shared 1,000-tip species tree, ZOMBI2
+runs the gene-family simulation **≈580× faster than ZOMBI 1** (41 s → 71 ms). Details in the
+[Rust engine guide](docs/guide/rust-engine.md).
+
+![ZOMBI2 performance](analyses/performance/figures/overview.png)
+
+---
+
+## Documentation
+
+Guides, a command-line reference, and the full API live in [`docs/`](docs/) (build locally
+with `pip install -e ".[docs]" && mkdocs serve`); a book-style [manual](manual/) is built with
+Pandoc. Start with the [quickstart](docs/quickstart.md).
+
+## Citation
+
+If you use ZOMBI2, please cite it via [`CITATION.cff`](CITATION.cff) (GitHub's *Cite this
+repository* button). A dedicated ZOMBI2 paper is in preparation; until then, cite the original
+[ZOMBI](https://github.com/AADavin/Zombi).
+
+## License
+
+ZOMBI2 is released under the [MIT License](LICENSE).