Explain the PROTEUS coupling and fill out the documentation

.github/workflows/publish.yaml

@@ -0,0 +1,48 @@
+name: Publish on PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      # Mandatory for trusted publishing: the workflow exchanges this token
+      # with PyPI for a short-lived credential, so no API token is stored.
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # setuptools-scm derives the version from the tag, so the full
+          # history and its tags have to be present. A shallow clone builds
+          # the configured fallback version instead and publishes 0.0.0.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build the distribution
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build "setuptools>=64" "setuptools-scm>=8" wheel
+          python -m build --no-isolation
+
+      - name: Refuse to publish a fallback version
+        # A tagless checkout yields 0.0.0, which would take that name on PyPI
+        # permanently and cannot be reclaimed. Fail before uploading.
+        run: |
+          set -euo pipefail
+          if ls dist/ | grep -qE '0\.0\.0'; then
+            echo "Built a fallback version, so the tag history is missing." >&2
+            ls dist/ >&2
+            exit 1
+          fi
+          ls dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+contact@formingworlds.space.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing guidelines
+
+Morrigan is part of the [PROTEUS](https://proteus-framework.org/PROTEUS) ecosystem and follows its conventions. This page covers what a change has to satisfy before it can land.
+
+## Getting set up
+
+```console
+git clone git@github.com:FormingWorlds/Morrigan.git
+cd Morrigan
+pip install -e ".[develop]"
+pre-commit install -f
+```
+
+## Building the documentation
+
+The documentation is written in [Markdown](https://www.markdownguide.org/basic-syntax/) and built with [Zensical](https://zensical.org/), which reads the existing `mkdocs.yml` directly.
+
+```console
+pip install -e ".[docs]"
+zensical serve
+```
+
+For a one-shot production build:
+
+```console
+zensical build --clean
+```
+
+The build must finish with no warnings. A warning usually means a link that does not resolve or a footnote that is never referenced, and both render as visible defects on the published site.
+
+## What a change has to satisfy
+
+```console
+pytest -m "(unit or smoke) and not skip"   # the tiers that run on every pull request
+ruff check --fix src/ tests/ tools/
+ruff format src/ tests/ tools/
+bash tools/validate_test_structure.sh      # every test carries a tier marker
+python tools/check_test_quality.py --check  # anti-happy-path lint
+```
+
+All four run in CI and block a merge. The test contract itself is documented in [Testing](https://proteus-framework.org/Morrigan/How-to/testing.html), and it is stricter than most: every physics routine must be pinned against a published value, an analytical limit or a cross-implementation check, and a pinned value needs a discrimination guard showing that the plausible wrong formula would fail the test.
+
+A pull request that adds or substantially changes more than fifty lines of test code triggers an independent review before it can merge.
+
+## Changing the physics
+
+Two things beyond the tests:
+
+**Cite the equation.** A change that transcribes or corrects a formula names the equation number in the source paper, in the pull request and in a comment at the call site. Transcription slips are this model's most common defect class, and the citation is what makes the next reader able to check it.
+
+**Say what moved.** Most physics changes shift ensemble outcomes. State what you measured, over how many seeds, and in which configuration, so that someone comparing results across versions knows what to expect.
+
+## Changing the record schema
+
+The per-impact record is the interface PROTEUS consumes. Any change to its fields, units or conventions is a breaking change for a coupled run and has to be called out in the pull request that makes it, so the PROTEUS-side pin can be updated in step. See [Coupling to PROTEUS](https://proteus-framework.org/Morrigan/Explanations/proteus_coupling.html).
+
+## Writing style
+
+Documentation, comments and commit messages describe the current state of the code, not how it came to be. A reader arriving cold needs to know what is true now; the history is in the commit log where it belongs.
+
+## Reporting a problem
+
+Open an issue at [FormingWorlds/Morrigan/issues](https://github.com/FormingWorlds/Morrigan/issues). For a physics problem, the most useful report contains the settings file, the seed, and what you expected instead, because a single system is a statistical realisation and the seed is what makes it reproducible.

README.md

@@ -26,8 +26,6 @@ Settings live in a `.toml` file; `initialise.toml` in the repository root is a w
 morrigan -c initialise.toml
 ```
 
-This replaces `python run_model.py`. If you have a launcher script of your own that still calls the old path, that is the line to change.
-
 Keeping several settings files side by side and pointing at whichever you want is the reason for the `-c` flag. The repository ignores `*.toml` apart from `initialise.toml`, so a settings file you want to keep alongside the results it produced has to be added to git explicitly.
 
 Results are written under the `save_directory` named in the settings file. A relative `save_directory` is taken from the directory you run the command in, not from wherever the settings file happens to live, so the run prints the full path it is writing to:
@@ -63,4 +61,4 @@ The suite is tiered (unit and smoke on every pull request, seed-ensemble statist
 
 ## Reproducibility
 
-Each system is seeded from `random_seed` in the settings file plus its own index, so a given settings file reproduces the same systems exactly.
+Each system's seed is mixed from `random_seed` in the settings file and the system's own index, so a given settings file reproduces the same systems exactly and two ensembles with neighbouring seeds are independent of each other.

docs/Community/CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+{!../CODE_OF_CONDUCT.md!}

docs/Community/CONTRIBUTING.md

@@ -0,0 +1 @@
+{!../CONTRIBUTING.md!}

docs/Community/contact.md

@@ -0,0 +1,11 @@
+# Contact
+
+We encourage you to reach out. Choose the most appropriate channel below.
+
+| Channel | Use for |
+|---------|---------|
+| [Forming Worlds Discussions](https://github.com/orgs/FormingWorlds/discussions) | Questions, installation help, feature suggestions |
+| [GitHub Issues](https://github.com/FormingWorlds/Morrigan/issues) | Bug reports, specific feature requests |
+| [proteus_dev@formingworlds.space](mailto:proteus_dev@formingworlds.space) | General enquiries |
+
+Morrigan implements the model of Kimura et al. (2025); questions about the model itself, as opposed to this implementation of it, are best directed to the authors of that paper.

docs/Explanations/code_architecture.md

@@ -0,0 +1,80 @@
+# Code architecture
+
+Eleven source files under `src/morrigan/`, laid out so that each stage of the physics has one home. This page maps them onto what the [model overview](model.md) describes.
+
+## The call graph
+
+```
+   morrigan -c settings.toml
+        |
+        v
+   driver.cli                       console-script entry point
+        |
+        v
+   driver.main                      read settings, parallel over systems
+        |
+        v
+   driver.run_once                  ONE system, start to finish
+        |
+        +-- allocate_a              lay out embryos by mutual Hill spacing
+        |
+        +-- while t <= max_time:
+        |     |
+        |     +-- sort_planet       drop the dead, re-sort by orbit
+        |     |
+        |     +-- secular_solution  eccentricities between events
+        |     |
+        |     +-- crossing_pair     which pair crosses next, and when
+        |     |     |
+        |     |     +-- interaction_timescales   viscous and collision times
+        |     |
+        |     +-- orbit_cross_K25   resolve the event
+        |           |
+        |           +-- merge_embryo         if they collide
+        |           +-- (scatter in place)   if they do not
+        |           +-- (ejection branch)    if one is excited past e = 1
+        |
+        +-- write tables / return records
+```
+
+`run_system` is the in-process entry point beside `main`. It drives the same `run_once` core but returns the records in memory instead of writing files, which is what PROTEUS consumes.
+
+## What each file owns
+
+| File | Owns | Physics or plumbing |
+| --- | --- | --- |
+| `driver.py` | Orchestration: settings, layout, the event loop, the record schema, survivor selection, output | physics |
+| `crossing_pair.py` | Which adjacent pair goes unstable next and when | physics |
+| `interaction_timescales.py` | Viscous stirring and collision timescales, the stability criterion | physics |
+| `secular_solution.py` | Laplace-Lagrange eigenmodes between events | physics |
+| `orbit_cross_K25.py` | Resolving a crossing into a merger, a scattering or an ejection | physics |
+| `merge_embryo.py` | Merger bookkeeping: masses, orbits, eccentricities | physics |
+| `helper_functions.py` | Kepler period, Hill radius, escape eccentricity, Rayleigh draws | physics |
+| `sort_planet.py` | Dead-planet removal and re-sorting | plumbing |
+| `constants.py` | Physical constants and unit conversions | plumbing |
+| `__init__.py` | Public API: `run_system` | plumbing |
+| `_version.py` | Generated from git tags | plumbing |
+
+The split matters for testing: every physics file must carry a test that pins it against a published value, an analytical limit or a cross-implementation check, recorded under [Validation anchors](../Validation/index.md). Plumbing files are exempt from that requirement but not from the rest of the test contract.
+
+## State and where it lives
+
+There is no state object. A system is a set of parallel numpy arrays, one entry per body, threaded through the loop as arguments:
+
+`a` (semi-major axes), `masses`, `ecc`, `Rp` (radii), `live_status`, `interact`, `densities`, `planet_id`.
+
+They are mutated in place by the event functions, which is why `sort_planet` can drop the dead bodies from all of them in one shared permutation, and why a test that reads an input array after calling an event function is reading post-mutation state.
+
+`planet_id` is the identity that survives sorting: array positions change as bodies die and the system is re-sorted, so it is the id, not the index, that appears in the output records.
+
+## Randomness
+
+All Monte Carlo draws go through numpy's global random state, seeded once per system at the top of `run_once`. The seed is mixed from the settings-file seed and the system's index, so a batch's systems are independent of each other and two batches with neighbouring seeds do not overlap.
+
+`run_system` additionally saves and restores the caller's random state around its own draws, so running a system in-process does not perturb an embedding program's sequence. That matters in a coupled run, where several modules share the same global state.
+
+## Units
+
+SI internally: kg, m, s. The settings file is read in Earth masses, AU, degrees and Gyr, converted once in `driver.py`. The returned records are SI apart from times, which are in years using the model's own 365-day year.
+
+Unit conversions and universal physical constants belong in `constants.py`; one appearing as a literal in a function body instead is a defect. Coefficients fitted to a specific published result are the exception and stay beside the equation they belong to, where the citation can sit with them: the crossing-time fit in `interaction_timescales.py` and the N-body crossing threshold in `crossing_pair.py` both carry their numbers inline for that reason.