Skip to content

Accretion

The [accretion] section configures protoplanet growth by giant impacts: which model supplies the impact history, what each impactor carries, and how much atmosphere a collision removes.

Submodule documentation: Morrigan. See also Model description and the coupling loop.

Accretion [accretion]

Parameter Type Default Description
module str or none none Accretion module to use. A "timeline" or "morrigan" history is borrowed from its dynamical bodies: impactor masses, collision loss fractions and impact energies are theirs, not rescaled to this planet. A warning is logged when the timeline's target mass differs from the planet mass by more than 10 %, a round threshold (about 3.5 % in escape speed, which scales as M^0.36), at load and per impact. Choices: none, "dummy", "timeline", "morrigan".
time_offset float 0.0 Offset applied to every impact time when mapping the timeline onto the PROTEUS time axis [yr]. A dynamical model measures time from disk dispersal, while PROTEUS measures it from the start of its own evolution. Impacts that still land at or before the start of the run are discarded with a warning, and their mass is not applied anywhere: the configured planet mass and orbit define the initial state on their own.
impactor_volatiles str "dry" Where each impactor's volatile content comes from. Choices: "dry" (impactors carry rock and iron only), "match_planet" (every impactor carries the planet's own initial fractional volatile abundances, scaled to the impactor mass, on the assumption that all embryos co-formed from the same disk material), "ppmw" (the per-element impactor_<e>_ppmw budgets below). The content is split into an atmospheric and a dissolved part by mirroring the planet's own partitioning at impact time; the atmospheric part loses the same collision fraction that strips the target's atmosphere and the remainder of the content is delivered. Choices: "dry", "match_planet", "ppmw".
impactor_H_ppmw float 0.0 Hydrogen carried by each impactor [ppmw of impactor mass]. Must be >= 0.
impactor_C_ppmw float 0.0 Carbon carried by each impactor [ppmw of impactor mass]. Must be >= 0.
impactor_N_ppmw float 0.0 Nitrogen carried by each impactor [ppmw of impactor mass]. Must be >= 0.
impactor_S_ppmw float 0.0 Sulfur carried by each impactor [ppmw of impactor mass]. Must be >= 0.
impactor_O_ppmw float 0.0 Oxygen carried by each impactor [ppmw of impactor mass]. With CALLIOPE or atmodeller at a fixed fO2 (planet.fO2_source = 'user_constant') the outgassing derives the O budget, so the delivered part counts as rock; otherwise it joins the O budget. Must be >= 0.
atmloss_module str or none none How impact atmosphere loss is computed. Choices: None (no impact atmosphere loss at all: the target keeps its atmosphere and a volatile-bearing impactor delivers its whole content), "constant" (the fixed fraction below), "zephyrus" (the giant-impact erosion scaling laws evaluated by zephyrus.collision.impact_loss from each impact's collision parameters). One fraction governs both bodies at each impact: the target loses that fraction of its atmosphere, and a volatile-bearing impactor loses the same fraction of its atmospheric part and delivers the remainder. PROTEUS itself ships no impact loss physics. Choices: none, "constant", "zephyrus".
atmloss_law str "roche2026" Which erosion scaling law to evaluate when atmloss_module = 'zephyrus'. Choices: "roche2026" (Roche et al. 2026, arXiv:2610.06077, parameterized by impact angle, mass ratio, contact velocity, target mass, radius ratio, and target atmospheric fraction), "kegerreis2020" (Kegerreis et al. 2020, doi:10.3847/2041-8213/abb5fb, parameterized by impact angle, contact velocity, mass ratio, radii, and bulk densities). The default is "roche2026". Both laws are calibrated on H2-He atmospheres (Kegerreis et al. 2020 used the HM80 equation of state; Roche et al. 2026, Sect. 2.1). For atmospheres of higher mean molecular weight (H2O, CO2, O2), the shock-driven loss is an upper limit for a given envelope mass (Roche et al. 2026, Sect. 4.3). The law covers the immediate shock- and vapour-plume-driven loss only; it neglects later thermally driven loss (an outflow driven by heat from the post-impact interior, Biersteker & Schlichting 2021), so for primordial H2-He envelopes the total loss can be higher (Roche et al. 2026, Sect. 4.1); that later loss becomes negligible for envelopes of higher mean molecular weight. Conversely, envelope miscibility may lead to overestimating loss from massive young envelopes (Roche et al. 2026, Sect. 4.1). The atmospheric mass fraction f_atm is computed from the running planet state as the sum of <e>_kg_atm over M_planet across all elements including rock vapour. Rock vapour adds to the envelope mass the scaling law sees, but PROTEUS does not debit stripped rock vapour because its inventory re-equilibrates with the magma ocean at each step. With roche2026, an airless target (m_atm = 0) returns f_loss = 0 so an impactor delivers its full volatile content. An atmosphere with f_atm between 1e-6 and below 0.0099 (1 % tolerance) is flagged and extrapolated without a clamp; f_atm below the 1e-6 stability bound is evaluated at 1e-6, and the resulting fraction depends on the collision parameters. When parameters are clamped, only the fit terms use the clamped value while v_esc, Q'_R, and the mass ratio use the raw collision state. When the far-field term predicts loss without impact energy, the 'X_FF_zero_energy' flag is set; this flag can fire inside the fitted range (for high gamma at f_atm 0.01 to 0.1) and is common below f_atm 0.01. Choices: "kegerreis2020", "roche2026".
atmloss_frac float 0.0 Fraction of the atmosphere removed by each impact when atmloss_module = "constant" [0-1]. Applies to the target's atmosphere and to the impactor's atmospheric part alike. Must be >= 0 and <= 1.

One loss fraction governs both bodies at each impact: the target loses that fraction of its atmosphere, and a volatile-bearing impactor loses the same fraction of its atmospheric part and delivers the remainder. PROTEUS ships no impact-loss physics of its own; the "zephyrus" module evaluates either the Roche et al. (2026) 2 scaling law (the default, atmloss_law = "roche2026") or the Kegerreis et al. (2020) 3 scaling law (atmloss_law = "kegerreis2020").

The mantle re-melt after an impact is a thermodynamic reset rather than an energy deposition: it raises the mantle to the run's planet.temperature_mode initial condition, and parts of the mantle that are already hotter keep their state, so the re-melt never cools the mantle. How molten the result is follows that condition. Only liquidus_super is fully molten for any planet mass and melting curve.

Accretion requires an interior module that can be re-melted and that can be stepped onto the moment of an impact, so interior_energetics.module = "spider" and "boundary" are both refused at configuration load: SPIDER has no supported re-melt path, and the boundary interior does not forward its state to the time-stepper, so the step cannot be capped to land on the collision. Furthermore, interior_struct.module = "spider" is refused because SPIDER structure solves do not support non-thermal structure updates during giant impacts. It is also refused together with outgas.vapourise = true: rock vapour adds rock-forming mass to the atmosphere that the whole-planet mass does not track, while an impact sizes its atmospheric stripping and its volatile delivery from budgets that are tracked, and the two accountings are not reconciled.

Morrigan [accretion.morrigan]

Evolves a system of embryos after disk dispersal with the semi-analytical Monte Carlo model of Kimura et al. (2025) 1 and reports the impacts experienced by one selected survivor. The host star mass is taken from star.mass, so the dynamical model and the rest of PROTEUS cannot disagree about it.

Note

Morrigan is an optional module and is not installed with PROTEUS by default. Install it with pip install "fwl-proteus[morrigan]" before setting accretion.module = "morrigan", or as an editable checkout with tools/get_morrigan.sh. See Installation: optional modules.

Parameter Type Default Description
seed int 1 Random seed for the Monte Carlo. Fixing it makes an impact history reproducible; sweeping it samples the outcome distribution. Must be >= 0.
num_planets int 10 Number of embryos the system starts with. Must be >= 2.
masses list [] Initial embryo masses [M_earth], one per embryo. An empty list starts every embryo at mass_equal.
mass_equal float 0.5 Initial mass of every embryo [M_earth], used when masses is empty. Must be > 0.
eccentricity_init float 0.01 Initial eccentricity shared by all embryos. Must be >= 0 and < 1.
inner_edge float 0.1 Semi-major axis of the innermost embryo [AU]. Must be > 0.
spacing float 10.0 Initial separation between adjacent embryos, in mutual Hill radii. Typical values are 5 to 15; beyond roughly 30 the system does not go unstable within any useful evolution time, so the run finishes with no impacts. Capped at 50 purely to catch an order-of-magnitude mistake at configuration load. The cap is not the physical limit and does not track it. The layout condition has a pole where the requested gap approaches the span it is measured across, and its position scales with the embryo masses and with the cube root of the stellar mass: near 74 mutual Hill radii for a pair of ten-Earth-mass embryos around a solar-mass star, but near 34 for the same pair around a 0.1-solar-mass host. A spacing this validator accepts can therefore still be too wide for a compact, low-mass-host system. The dynamical model applies the exact condition and refuses such a layout by name, so that check, not this cap, is what guarantees a valid layout. Must be > 0 and <= 50.0.
density float 5500.0 Uniform bulk density used to convert embryo mass to radius [kg m-3]. Must be > 0.
impact_angle float 45.0 Impact angle [deg]. The impact parameter is its sine. Must be >= 0 and <= 90.
evolution_time float 1.0 Duration of the dynamical evolution [Gyr]. Must be > 0.
inner_cutoff float 0.005 Perihelion inside which an embryo counts as lost to the star [AU]. Must be > 0.
selector str "match_config" Which survivor's impact history PROTEUS follows. 'match_config' picks the survivor whose initial mass and orbit are closest to the PROTEUS configuration, 'mass' the most massive survivor, 'semimajoraxis' the survivor whose final orbit is nearest selector_value [AU], and 'id' the embryo with index selector_value. Choices: "match_config", "mass", "semimajoraxis", "id".
selector_value float or int or none none Target value for the 'semimajoraxis' and 'id' selectors. Ignored otherwise. The field converter parses numeric strings to numbers.

Typical spacing values are 5 to 15 mutual Hill radii; beyond roughly 30 the system does not go unstable within a useful evolution time and the run finishes with no impacts. The 50 accepted here only catches an order-of-magnitude mistake at configuration load: the layout condition the dynamical model applies depends on the embryo masses and the host mass, and it refuses a layout that is too wide by name.

Timeline [accretion.timeline]

Applies a pre-written sequence of impacts instead of deriving one. Every impact consequence is computed exactly as for a model-derived history, so this reproduces a published impact history, drives PROTEUS from a history computed elsewhere, or applies a hand-written sequence for a controlled experiment.

Parameter Type Default Description
timeline_path str or none none Path to the impact timeline file. Environment variables and ~ are expanded.

Dummy accretion [accretion.dummy]

Builds an accretion history from scaling laws rather than by integrating a system of embryos. The planet approaches an asymptotic mass exponentially, impacts are placed at evenly spaced times, and each delivers the mass the law accretes over its interval, so the increments decay with time and the largest impact is the first. Radii follow the Noack & Lasbleis (2020) mass-radius scaling 4, collision velocities combine the pair's mutual escape velocity with an encounter velocity set by eccentricity, and each merged orbit follows from conserving linear momentum.

Parameter Type Default Description
timeline_path str or none none Not a parameter of this module. Present only to reject a configuration that sets it here, which asks to replay a file and would otherwise be served a generated timeline at default settings. Use accretion.module = "timeline" and accretion.timeline.timeline_path.
mass_accreted float 0.1 Total mass delivered over the whole timeline [M_earth]. The growth law sets how this is distributed in time and between impacts; the increments are scaled so they sum to exactly this value. Must be > 0.
num_impacts int 3 Number of impacts in the timeline. Must be >= 1.
timescale float 1000000.0 E-folding time of the accretion law [yr]. Short compared with time_last concentrates the mass in the first impacts; long compared with it spreads the mass evenly. Must be > 0.
time_last float 5000000.0 Time of the final impact [yr]. Impacts are spaced evenly from time_last / num_impacts up to this time. Must be > 0.
eccentricity float 0.05 Encounter eccentricity [1], setting both the approach velocity that adds to the mutual escape velocity and the impactor's orbit. Must be >= 0 and < 1.
impact_parameter float 0.5 Impact parameter of every collision [1], the sine of the impact angle. Zero is head-on, one is grazing. Must be >= 0 and <= 1.

timeline_path is accepted here but is not a parameter of this module: setting it is refused at configuration load, because it asks to replay a file and would otherwise be served a generated timeline at default settings. To replay a file, set accretion.module = "timeline" and put the path in accretion.timeline.timeline_path.

Example

[accretion]
    module = "morrigan"
    impactor_volatiles = "match_planet"
    atmloss_module = "zephyrus"
    atmloss_law = "roche2026"

    [accretion.morrigan]
        seed = 1
        num_planets = 10
        mass_equal = 0.5
        inner_edge = 0.1
        spacing = 10.0
        evolution_time = 1.0
        selector = "match_config"

Constraints

Cross-field constraints enforced when the config file loads:

  • Refuse a timeline path aimed at the module that generates its own.
  • The timeline accretion module requires a path to an impact timeline file.
  • Refuse a volatile budget that exceeds the impactor's own mass.
  • Refuse ppmw budgets that the selected content mode would ignore.
  • The Morrigan module requires as many embryo masses as planets, all positive, and a valid selector value when the selector is a semi-major axis or planet id.

  1. Kimura, T., Hoshino, H., Kokubo, E., Matsumoto, Y. & Ikoma, M., Semi-analytical model for the dynamical evolution of planetary systems via giant impacts, The Astrophysical Journal, 989, 109, 2025. ↩

  2. Roche, M.J., Lock, S.J., Carter, P.J. & Leinhardt, Z.M., Giant impacts preferentially remove low-mass atmospheres: a generalised scaling law for impact-driven atmospheric loss, accepted to The Astrophysical Journal Letters, arXiv:2610.06077, 2026. ↩

  3. Kegerreis, J.A., Eke, V.R., Catling, D.C., Massey, R.J., Teodoro, L.F.A. & Zahnle, K.J., Atmospheric erosion by giant impacts onto terrestrial planets: a scaling law for any speed, angle, mass, and density, The Astrophysical Journal Letters, 901, L31, 2020. ↩

  4. Noack, L. & Lasbleis, M., Parameterisations of interior properties of rocky planets, Astronomy & Astrophysics, 638, A129, 2020. SciX. ↩