Grow the planet by giant impacts: the accretion module and Morrigan

.github/workflows/ci-nightly.yml

@@ -217,12 +217,14 @@ jobs:
             files: >-
               tests/integration/test_slow_aragog_calliope.py
               tests/integration/test_slow_aragog_atmodeller.py
+              tests/integration/test_slow_accretion_resume.py
           - shard: aragog
             tier: critical
             os: macos-latest
             files: >-
               tests/integration/test_slow_aragog_calliope.py
               tests/integration/test_slow_aragog_atmodeller.py
+              tests/integration/test_slow_accretion_resume.py
           # ---- shard: zalmoxis-dummy (real Zalmoxis + dummy
           # everything else; Linux-only because the test is
           # skipif(darwin) on macOS) ----

.gitignore

@@ -93,6 +93,9 @@ Love.jl/
 BOREAS
 boreas
 Boreas
+morrigan
+Morrigan
+MORRIGAN
 
 # misc
 ######
@@ -335,3 +338,6 @@ src/proteus/_version.py
 # Local scratch directories (not part of the project)
 /.playwright-mcp/
 /platon/
+
+# Diagnostic dumps written by `proteus update` into the repo root.
+/proteus_update_*.log

CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-contact@formingworlds.space.
+dev@proteus-framework.org.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

docs/Community/CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-contact@formingworlds.space.
+dev@proteus-framework.org.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

docs/Explanations/code_architecture.md

@@ -12,6 +12,7 @@ coupled planetary evolution simulation:
 - [`atmos_chem/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/atmos_chem): atmospheric photochemistry (VULCAN, dummy)
 - [`escape/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/escape): atmospheric mass loss (ZEPHYRUS, dummy)
 - [`outgas/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/outgas): volatile partitioning (CALLIOPE, atmodeller, dummy)
+- [`accretion/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/accretion): protoplanet growth by giant impacts (Morrigan, timeline, dummy)
 - [`orbit/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/orbit): orbital evolution and tides (Obliqua/LovePy, dummy)
 - [`star/`](https://github.com/FormingWorlds/PROTEUS/tree/main/src/proteus/star): stellar evolution and spectra (MORS, dummy)
 

docs/Explanations/coupling_loop.md

@@ -42,47 +42,58 @@ upstream modules.
    melt fraction, and heat flux using the chosen solver (Aragog, SPIDER,
    boundary, or dummy). Advances simulation time by the interior timestep.
 
-2. **Structure update** (`update_structure_from_interior`): If Zalmoxis is
+2. **Giant impacts** (`apply_impact`): Applies every impact whose time falls
+   within the step just taken. The impactor's rock is added to the planet and
+   the interior structure is re-solved at the new mass, its volatiles are
+   delivered while part of the target's atmosphere is stripped, the mantle is
+   re-melted by re-applying the run's temperature-mode initial condition, and
+   the orbit takes the impact's change in semi-major axis and eccentricity.
+   How molten the re-melt leaves the mantle follows that initial condition:
+   only `planet.temperature_mode = "liquidus_super"` is fully molten for any
+   planet mass and melting curve. Runs only when an accretion module is
+   configured and an impact is due.
+
+3. **Structure update** (`update_structure_from_interior`): If Zalmoxis is
    active and a structure update is triggered (by elapsed time, melt fraction
    change, or temperature change exceeding configured thresholds), recomputes
    the hydrostatic density profile and planet radius.
 
-3. **Orbit and tides** (`run_orbit`): Updates orbital elements (semi-major
+4. **Orbit and tides** (`run_orbit`): Updates orbital elements (semi-major
    axis, eccentricity) and computes tidal heating rates. Tidal power is
    distributed radially and passed to the interior module for the next
    iteration.
 
-4. **Stellar evolution** (`update_stellar_quantities`): Interpolates the
+5. **Stellar evolution** (`update_stellar_quantities`): Interpolates the
    stellar mass, radius, effective temperature, and luminosity from
    pre-computed evolutionary tracks at the current stellar age. Recomputes
    the instellation flux and XUV flux. The stellar spectrum is updated on a
    separate, longer cadence controlled by `params.dt.starspec`.
 
-5. **Atmospheric escape** (`run_escape`): Computes mass loss rates for each
+6. **Atmospheric escape** (`run_escape`): Computes mass loss rates for each
    element (H, C, N, S, O) based on the XUV flux, planet mass, and current
    atmospheric composition. Updates element inventories by debiting the
    escaped mass. Only active after the initialisation stage.
 
-6. **Outgassing** (`run_outgassing`): Given the updated element inventories,
+7. **Outgassing** (`run_outgassing`): Given the updated element inventories,
    mantle temperature, and melt fraction, computes the thermodynamic
    equilibrium partitioning of volatiles between atmosphere, melt, and solid.
    Writes partial pressures, mixing ratios, and atmospheric mass to `hf_row`.
    Also calls `update_planet_mass` and `assert_mass_conservation` to verify
    the whole-planet mass budget.
 
-7. **Atmosphere climate** (`run_atmosphere`): Solves the radiative-convective
+8. **Atmosphere climate** (`run_atmosphere`): Solves the radiative-convective
    structure of the atmosphere using the chosen backend (AGNI, JANUS, or
    dummy). Takes the interior heat flux and atmospheric composition as input;
    returns the surface temperature, outgoing longwave radiation, and Bond
    albedo.
 
-8. **Atmospheric chemistry** (`run_chemistry`): If configured for online mode,
+9. **Atmospheric chemistry** (`run_chemistry`): If configured for online mode,
    runs photochemical kinetics (VULCAN) to compute steady-state mixing ratios.
    Most configurations skip this step or run it offline after the simulation.
 
-9. **Housekeeping**: Updates iteration counters, checks convergence criteria,
-   writes the helpfile row to `hf_all`, generates plots and archives if
-   scheduled.
+10. **Housekeeping**: Updates iteration counters, checks convergence criteria,
+    writes the helpfile row to `hf_all`, generates plots and archives if
+    scheduled.
 
 ## Initialisation stage
 

docs/Explanations/model.md

@@ -46,6 +46,7 @@ atmosphere), enabling hierarchical model intercomparison.
 | Escape | [ZEPHYRUS](https://github.com/FormingWorlds/ZEPHYRUS), dummy | Atmospheric escape |
 | Outgassing | [CALLIOPE](https://proteus-framework.org/CALLIOPE/), [atmodeller](https://github.com/djbower/atmodeller), dummy | Volatile exchange between interior and atmosphere |
 | Orbit | [Obliqua](https://github.com/FormingWorlds/Obliqua), dummy | Orbital evolution and tidal heating |
+| Accretion | [Morrigan](https://proteus-framework.org/Morrigan/), timeline, dummy | Protoplanet growth by giant impacts |
 | Observations | [petitRADTRANS](https://petitradtrans.readthedocs.io/), none | Synthetic transit and eclipse spectra |
 
 Each module is maintained in its own repository and can be used as a standalone package outside of PROTEUS. The following sections describe each module's physical role and how PROTEUS couples to it.
@@ -195,6 +196,18 @@ Some notable consequences of step 3:
 
 Config section: `[orbit]`. Reference: [Star and orbit configuration](../Reference/config/star_orbit.md).
 
+## Accretion: Morrigan
+
+The accretion module supplies the giant impacts a planet experiences after the disk disperses, and PROTEUS applies each one to the planet it is evolving.
+
+**[Morrigan](https://proteus-framework.org/Morrigan/)** (Python) follows a system of planetary embryos through the secular eccentricity oscillations, orbit crossings, scatterings, ejections and giant impacts by which they accrete, until the system settles into a Hill-stable configuration. It implements the semi-analytical Monte Carlo model of Kimura et al. (2025) [^cite-kimura2025], which predicts when a system goes unstable and resolves each instability with prescriptions calibrated against N-body simulations, rather than integrating the orbits. That makes one system cheap enough to run inside a coupled framework, at the cost of any single history being a statistical realisation rather than a trajectory: ensemble statistics are the meaningful comparison. PROTEUS follows one survivor of that system, chosen by the configured selector, and takes its impact history.
+
+Each impact is applied at the timestep it falls in. The impactor's rock grows the planet and the interior structure is re-solved at the new mass, so radius, gravity and the core-mantle split follow the growth. The impactor's volatiles are delivered while the same collision fraction strips the target's atmosphere and the impactor's own, so a small impactor striking a heavily-clothed planet can leave it lighter than before. The mantle is re-melted by re-applying the run's temperature-mode initial condition, and the orbit takes the collision's change in semi-major axis and eccentricity, clamped to a bound orbit.
+
+Two further implementations take an impact history rather than derive one. `timeline` replays a table of impacts from a file, which reproduces a published history or drives PROTEUS from one computed elsewhere. `dummy` builds a history from scaling laws: the planet approaches an asymptotic mass exponentially, impacts are evenly spaced in time, and each delivers the mass the law accretes over its interval, so the increments decay and the largest impact is the first. With no accretion module selected the impact list is empty and the planet's mass is set by its initial condition alone.
+
+Config section: `[accretion]`. Reference: [Accretion configuration](../Reference/config/accretion.md).
+
 ## Synthetic observations: petitRADTRANS
 
 **[petitRADTRANS](https://petitradtrans.readthedocs.io/)** (Python) is a radiative transfer code for computing exoplanet transmission and emission spectra. PROTEUS uses petitRADTRANS as a forward model to synthesise what an observer would measure given the simulated atmospheric state.
@@ -241,9 +254,12 @@ architecture and for quick parameter exploration.
 | Escape | Constant bulk mass loss rate (user-specified kg/s), distributed proportionally across elements |
 | Outgassing | Melt-fraction-dependent volatile partitioning with fixed stoichiometry, no equilibrium chemistry |
 | Orbit | Fixed semi-major axis and eccentricity; configurable parameterised tidal heating |
+| Accretion | Exponential approach to an asymptotic mass, delivered as evenly spaced impacts; Noack & Lasbleis (2020) [^cite-noack2020] radii and momentum-conserving mergers |
 
-The [Quick start tutorial](../Tutorials/quick_start_dummy.md) runs PROTEUS
-with all modules set to dummy.
+The [Quick start tutorial](../Tutorials/quick_start_dummy.md) runs PROTEUS with
+every physics module set to dummy. Accretion is left out of that configuration,
+so the planet keeps the mass its initial condition gives it; add an
+`[accretion]` section with `module = "dummy"` to let it grow.
 
 ---
 
@@ -296,3 +312,5 @@ Only the interior and star modules have an explicit notion of time-evolution. Al
  [^cite-baraffe2015]: Baraffe, I., Homeier, D., Allard, F. & Chabrier, G., *[New evolutionary models for pre-main sequence and main sequence low-mass stars down to the hydrogen-burning limit](https://doi.org/10.1051/0004-6361/201425481)*, Astronomy & Astrophysics, 577, A42, 2015. [SciX](https://scixplorer.org/abs/2015A%26A...577A..42B/abstract).
 
  [^cite-noack2020]: Noack, L. & Lasbleis, M., *[Parameterisations of interior properties of rocky planets](https://doi.org/10.1051/0004-6361/202037723)*, Astronomy & Astrophysics, 638, A129, 2020. [SciX](https://scixplorer.org/abs/2020A%26A...638A.129N/abstract).
+
+ [^cite-kimura2025]: Kimura, T., Hoshino, H., Kokubo, E., Matsumoto, Y. & Ikoma, M., *[Semi-analytical model for the dynamical evolution of planetary systems via giant impacts](https://doi.org/10.3847/1538-4357/ade992)*, The Astrophysical Journal, 989, 109, 2025.

docs/How-to/config.md

@@ -10,6 +10,7 @@ For topic-specific parameter guides, see the **configuration reference** pages:
 - [Interior structure and energetics](../Reference/config/interior.md)
 - [Atmosphere and chemistry](../Reference/config/atmosphere.md)
 - [Escape and outgassing](../Reference/config/escape_outgas.md)
+- [Accretion](../Reference/config/accretion.md)
 - [Synthetic observations](../Reference/config/observe.md)
 
 For worked examples, see the [Tutorials](../Tutorials/quick_start_dummy.md).

docs/How-to/optionalmodules_installation.md

@@ -142,3 +142,31 @@ bash tools/get_vulcan.sh
 !!! warning "License"
     VULCAN is distributed under the GPL-3.0 license; review its terms
     before installing.
+
+## Protoplanet accretion (Morrigan)
+
+Morrigan is an optional giant-impact accretion module, selected with
+`accretion.module = "morrigan"`. It evolves a system of planetary embryos
+through orbital crossings and collisions and returns the impact history
+that the coupled run replays. It is not required for a standard PROTEUS
+run. Install it from PyPI:
+
+```console
+pip install "fwl-proteus[morrigan]"
+```
+
+For local development, install as an editable checkout instead:
+
+```console
+bash tools/get_morrigan.sh
+```
+
+An accretion run needs an interior module that can re-melt the mantle
+after an impact. Aragog is the production choice; SPIDER is refused at
+configuration load because it has no re-melt path.
+
+Two accretion modules need no installation at all. `accretion.module =
+"dummy"` builds an impact history from scaling laws, and `accretion.module
+= "timeline"` replays one from a file, which is how a published or
+externally computed impact history drives a run. Both apply the same
+impact physics as the dynamical model.

docs/How-to/update_module_pins.md

@@ -18,7 +18,7 @@ module is distributed.
 | Pin type | Where it lives in `pyproject.toml` | Pin value | Modules |
 |----------|------------------------------------|-----------|---------|
 | PyPI floor | `[project] dependencies` | Minimum version bound, e.g. `fwl-aragog>=26.05.13` | fwl-janus, fwl-mors, fwl-calliope, fwl-zephyrus, fwl-aragog, fwl-zalmoxis |
-| PyPI floor (optional) | `[project.optional-dependencies]` | Minimum version bound on an optional backend | fwl-vulcan, atmodeller |
+| PyPI floor (optional) | `[project.optional-dependencies]` | Minimum version bound on an optional backend | fwl-vulcan, atmodeller, fwl-morrigan |
 | Git ref | `[tool.proteus.modules.<name>]` | Exact commit SHA, tag, or branch in a `ref` field | AGNI, SOCRATES, SPIDER, BOREAS, LovePy |
 
 A third entry, PETSc, is pinned in `[tool.proteus.modules.petsc]` by the SHA-256
@@ -169,11 +169,12 @@ When in doubt, pin to a commit SHA. A branch pin is a deliberate choice to
 follow upstream, not a default.
 
 !!! info "Some modules deliberately have no git entry"
-    VULCAN, like fwl-aragog and fwl-zalmoxis, is a single-source PyPI package, so
-    it is pinned only by its floor in `[project.optional-dependencies]`. Its
-    setup script checks out the git tag matching that floor, so the editable
-    checkout and the published release cannot diverge. Do not add a second pin
-    for these in `[tool.proteus.modules]`.
+    VULCAN and Morrigan, like fwl-aragog and fwl-zalmoxis, are single-source
+    PyPI packages, so they are pinned only by their floor in
+    `[project.optional-dependencies]`. Their setup scripts check out the git tag
+    matching that floor, so the editable checkout and the published release
+    cannot diverge. Do not add a second pin for these in
+    `[tool.proteus.modules]`.
 
 ## Propagating the change to other developers