Skip to content

Document the PROTEUS coupling and average the hydrostatic anchor - #47

Merged
maraattia merged 6 commits into
mainfrom
ma/proteus-coupling-docs
Nov 14, 2026
Merged

maraattia merged 6 commits into
mainfrom
ma/proteus-coupling-docs

Conversation

@maraattia

Copy link
Copy Markdown
Contributor

Description

This branch prepares ZEPHYRUS for the PROTEUS coupling of the dispatcher (part of FormingWorlds/PROTEUS#1038). It rewrites the "ZEPHYRUS in PROTEUS" page for the dispatcher and changes one default of the hydrostatic branch.

Changes:

  • The hydrostatic upper structure now starts from the log-pressure mean temperature of the top 3 pressure decades of the profile, set by the new DispatchSettings.T_anchor_decades (default 3.0, and 0 restores the topmost level). The exobase floor compares against the same mean. The top layers of a radiative-convective column are optically thin, and their temperature in a coupled AGNI column scatters by hundreds of K with the number of levels.
  • Vanadium gets its mass in composition.py (50.942), since PROTEUS tracks V in its rock vapour.
  • docs/Explanations/proteus.md is rewritten for the dispatcher. It covers the two schemes, the config keys and their exceptions (T_exo, Pxuv, kappa_photo), the helpfile columns with their codes, the frozen-mantle debit, the column top, and the case of an envelope too weakly bound for a hydrostatic column. The regimes, parameters, results, and validation pages carry the anchor change, and the dispatch tutorial now describes the coupled run in the present tense.
  • The spelling rule in AGENTS.md now covers the docs pages only, without a rule for code and pull-request text.

Physics impact. The anchor change moves hydrostatic rates only where the top of the profile is not isothermal. On an isothermal profile the mean equals the top level and nothing changes. On the column of test_a_hot_top_spike_no_longer_sets_the_thermosphere (a 200 K column with a 1200 K top level, Mars mass, prescribed T_exo 1000 K), the anchor goes from 1200 K to 242 K. The hydrogen rate then goes from 0.575 to 0.946 of the rate of the same column with a quiet 200 K top. On the first AGNI solves of a water and CO2 atmosphere at 30 to 120 levels, the 3-decade mean spans 230 to 408 K, where the top level spans 208 to 1731 K.

Config changes: one new setting, T_anchor_decades, validated as finite and at or above 0. Breaking changes: none to the API. The default anchor changes as above.

Validation of changes

On Linux 6.8 with Python 3.12.12:

  • pytest -n 8 -m "unit or smoke" --cov=zephyrus: 310 passed, coverage 99%. The full suite gives 314 passed.
  • python tools/check_test_quality.py --check: 0 violations.
  • ruff check src tests: clean.

New tests pin the anchor as the trapezoidal mean in log pressure on an uneven grid, its window when an edge falls between levels, the rate change above, the setting's validation, and the vanadium mass.

Checklist

  • I have followed the contributing guidelines
  • My code follows the style guidelines of this project
  • I have performed a self-review of my code
  • My changes generate no new warnings or errors
  • I have checked that the tests still pass on my computer
  • I have updated the docs, as appropriate
  • I have added tests for these changes, as appropriate
  • I have checked that all dependencies have been updated, as required

Relevant people

The Coupling to PROTEUS page describes the two schemes PROTEUS calls, the dispatcher (its default) and EL_escape: the inputs PROTEUS passes, the atmosphere column it reads, the pxuv reservoir, the debit of a frozen atmosphere, and the helpfile columns. The regimes page and the dispatch tutorial say that PROTEUS supplies the profile. The spelling rule of AGENTS.md covers the documentation only.
PROTEUS now reaches 1e-10 bar by default, which keeps the wind base inside its column for most planets. A hot, light envelope that is too weakly bound for a hydrostatic column gives a photospheric radius, and so a boil-off rate, that depends on the resolution of the column.
The hydrostatic branch built its Bates thermosphere from the temperature of the topmost profile level and floored the exobase temperature there. The optically thin top layers of a climate model carry a poorly constrained temperature, which in coupled AGNI columns scatters by hundreds of K with the number of levels, so a single hot top level could floor the exobase and move the Jeans rate. The structure now starts from the log-pressure mean of the top three decades of the profile (T_anchor_decades, 0 for the topmost level), and the floor compares against that mean. Profiles that are isothermal near the top are unchanged.
Vanadium takes its standard atomic weight, so an atmosphere holding V or VO from rock vapour no longer stops on the mean particle mass. The PROTEUS coupling page names the settings that differ from ZEPHYRUS (T_exo, Pxuv, kappa_photo, the two polytropic shapes), describes "extend" as the Bates upper structure, gives the rate branch of an L1 transfer win and the new column-source codes. The floored-exobase flag compares against the averaged anchor, as the results page now says. The anchor tests add an uneven grid and a window narrower than one cell.
Test that a quarter-decade window returns a top level distinct from the
level below, and that a window edge between two levels averages the
levels inside without interpolating to the edge. The docstring says so.
The coupling page lists the -1 and 0 values PROTEUS writes on a skipped
escape step, the step cap on a frozen mantle, and the short column it builds
for an envelope unbound at its surface.
@maraattia
maraattia marked this pull request as ready for review November 14, 2026 15:51
@maraattia
maraattia merged commit f9599f4 into main Nov 14, 2026
8 checks passed
@maraattia
maraattia deleted the ma/proteus-coupling-docs branch November 14, 2026 17:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant