Skip to content

PROTEUS code architecture

Overview

PROTEUS is organised as a collection of modular scientific components, located as directories inside src/proteus/. Each module handles one physical domain of a coupled planetary evolution simulation:

  • interior_energetics/: thermal evolution of the mantle and core (Aragog, SPIDER, boundary, dummy)
  • interior_struct/: hydrostatic structure and planet radius (Zalmoxis, dummy)
  • atmos_clim/: radiative-convective atmosphere (AGNI, JANUS, dummy)
  • atmos_chem/: atmospheric photochemistry (VULCAN, dummy)
  • escape/: atmospheric mass loss (ZEPHYRUS, dummy)
  • outgas/: volatile partitioning (CALLIOPE, atmodeller, dummy)
  • orbit/: orbital evolution and tides (Obliqua/LovePy, dummy)
  • star/: stellar evolution and spectra (MORS, dummy)

Most modules follow a common pattern: a wrapper.py defining the dispatch interface, a common.py with shared helpers and data structures, and one file per backend implementation (for example, aragog.py, spider.py, boundary.py, and dummy.py inside interior_energetics/).

The central orchestrator, proteus.py, couples these modules together and advances the simulation, with modules exchanging information at each timestep through the hf_row dictionary. See Coupling loop for details on the execution order and data flow.

Supporting directories

Beyond the physics modules, the source tree contains:

  • config/: TOML configuration parsing and validation (attrs-based dataclasses)
  • utils/: shared utilities (data download, logging, constants, plotting helpers)
  • plot/: diagnostic and publication-quality plot routines
  • grid/: parameter grid sweep management
  • inference/: Bayesian optimisation and inference workflows
  • cli.py: command-line interface entry points

Architecture diagram

The diagram below gives a high-level view of the PROTEUS code architecture. Click any module to jump to its source on the main branch, or any loop block to jump to the relevant section of proteus.py.

Organising changes for parallel development

PROTEUS is edited by many contributors at once, so the structure is chosen to keep changes local. The source tree is sliced vertically by physical domain: a change to atmospheric escape lives in escape/, a change to outgassing lives in outgas/, and the two rarely touch the same file. Within a module, the wrapper.py / <backend>.py / common.py split means adding or modifying one backend leaves the others untouched.

The files that every contributor must touch are the coupling glue: the main loop in proteus.py, the shared helpers in utils/, and the central registries of output columns and configuration fields. These are the places where parallel edits are most likely to collide. Keeping individual functions small, adding new loop steps as named stage functions, and writing shared registries one entry per line (grouped by module) keeps most additions on distinct lines, so independent work merges without conflict. The practical targets are in Development standards.