fwl-morrigan 26.7.25

Accretion and dynamical evolution of a system of protoplanets via giant impacts.

Morrigan

Morrigan is the protoplanet accretion module of the PROTEUS coupled atmosphere-interior evolution framework. It follows a system of protoplanets, the planetary embryos of the post-disk stage, through the giant impacts and gravitational scattering by which they accrete, tracking how each collision changes the masses and orbits of the bodies that survive. It implements the semi-analytical Monte Carlo model of Kimura et al. (2025).

Named after Morrigan, a shapeshifting figure from Irish mythology thought to represent the dynamical nature of existence.

Installation

git clone [e-mail]:FormingWorlds/Morrigan.git
cd Morrigan
pip install -e .

Running a model

Settings live in a .toml file; initialise.toml in the repository root is a worked example covering the number of systems, the embryo masses, the stellar mass, and how long to evolve for.

morrigan -c initialise.toml

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:

Path	Contents
data/full_systems/	State of every planet through time
data/mergers/	One row per collision: the bodies involved and the collision velocity
data/survivors/	Final mass, orbit, and eccentricity of each surviving planet
batch_summary.csv	Runtime and surviving-planet count for each system

To plot the results of a run, point the plotting script at the same settings file:

pip install -e ".[plot]"
python plot.py -c initialise.toml

plot.py is a script kept in the repository rather than part of the installed package, so it is run from a checkout. Its plotting dependencies (matplotlib, scipy) are in the plot extra, which keeps them out of the way of anything that only wants to import the model.

Documentation

The full documentation, including the model physics, the PROTEUS coupling contract, and the per-source validation anchors, lives at proteus-framework.org/Morrigan. Build it locally with pip install -e ".[docs]" and zensical serve.

Testing

pip install -e ".[develop]"
pytest -m "(unit or smoke) and not skip"

The suite is tiered (unit and smoke on every pull request, seed-ensemble statistics nightly) and every physics routine is pinned against a published value, an analytical limit, or a cross-implementation check; see the documentation's testing guide for the full contract.

Reproducibility

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.