# formingworlds/proteus architecture

> Architecture diagram of the GitHub repository formingworlds/proteus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/formingworlds/proteus
- Repository: https://github.com/formingworlds/proteus

## Overview

##### Project type and purpose
- PROTEUS is an open-source, modular Python framework for simulating coupled evolution of rocky-planet and exoplanet atmospheres and interiors.
- It’s invoked as a CLI tool (`proteus`), ingests user configurations (TOML), orchestrates multiple physics modules, calls external binaries (e.g., VULCAN, JANUS, PHOENIX), and produces outputs and plots.

##### File structure
- Top-level:
– `src/proteus/cli.py` & `src/proteus/proteus.py`: CLI entrypoints
– `src/proteus/config`: configuration parsing and validation
– `src/proteus/[atmos_chem, atmos_clim, escape, interior, orbit, outgas, observe, star]`: domain modules with wrappers to external tools
– `src/proteus/grid`: grid-management utilities
– `src/proteus/inference`: Bayesian/global optimization and analysis
– `src/proteus/plot`: plotting routines for coupled model outputs
– `src/proteus/utils`: shared helpers (I/O, logging, termination, etc.)
- External-tool wrappers: each domain subpackage has a `wrapper.py` to launch compiled executables.
- Tests cover each module, integration tests under `tests/`.
- CI, Dockerfile, docs, examples, and cluster guides show automated build, test, and deployment.

##### README and docs
- Describes a modular pipeline: configuration → coupling → physics modules → outputs & plots.
- Points to detailed docs on model, installation, usage, cluster deployment.

##### Elements
- Orange for data stores

##### Detailed capture of essential architecture
- Don’t simply list modules—illustrate how they connect via the Coupler and wrappers.
- Sequence of calls and data artifacts (e.g., “atmosphere.nc → interior.nc → escape.csv → plots”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Invocation
    User["User"]:::external -->|invokes| CLI["proteus CLI"]:::python
    click CLI "https://github.com/formingworlds/proteus/blob/main/src/proteus/cli.py"

    %% Configuration Layer
    subgraph "Configuration Layer"
        ConfigParser["TOML Parser & Validator"]:::python
    end
    CLI -->|reads config| ConfigParser
    click ConfigParser "https://github.com/formingworlds/proteus/blob/main/src/proteus/config/_config.py"

    %% Orchestrator / Coupler
    subgraph "Orchestrator / Coupler"
        Coupler["Coupler"]:::python
        Entrypoint["proteus.py"]:::python
    end
    ConfigParser -->|produces Config object| Coupler
    click Coupler "https://github.com/formingworlds/proteus/blob/main/src/proteus/utils/coupler.py"
    click Entrypoint "https://github.com/formingworlds/proteus/blob/main/src/proteus/proteus.py"

    %% Grid Management
    Grid["Grid Manager"]:::python
    Coupler -->|generates grid| Grid
    click Grid "https://github.com/formingworlds/proteus/blob/main/src/proteus/grid/manage.py"

    %% Physics Modules
    subgraph "Physics Modules"
        AtmosChem["AtmosChem Module"]:::python
        AtmosClim["AtmosClim Module"]:::python
        Escape["Escape Module"]:::python
        Interior["Interior Module"]:::python
        Orbit["Orbit Module"]:::python
        Outgas["Outgas Module"]:::python
        Observe["Observe Module"]:::python
        Star["Star Module"]:::python
    end
    Grid --> AtmosChem
    AtmosChem --> AtmosClim
    AtmosClim --> Escape
    Escape --> Interior
    Interior --> Orbit
    Orbit --> Outgas
    Outgas --> Observe
    Observe --> Star

    click AtmosChem "https://github.com/formingworlds/proteus/blob/main/src/proteus/atmos_chem/wrapper.py"
    click AtmosClim "https://github.com/formingworlds/proteus/blob/main/src/proteus/atmos_clim/wrapper.py"
    click Escape "https://github.com/formingworlds/proteus/blob/main/src/proteus/escape/wrapper.py"
    click Interior "https://github.com/formingworlds/proteus/blob/main/src/proteus/interior/wrapper.py"
    click Orbit "https://github.com/formingworlds/proteus/blob/main/src/proteus/orbit/wrapper.py"
    click Outgas "https://github.com/formingworlds/proteus/blob/main/src/proteus/outgas/wrapper.py"
    click Observe "https://github.com/formingworlds/proteus/blob/main/src/proteus/observe/wrapper.py"
    click Star "https://github.com/formingworlds/proteus/blob/main/src/proteus/star/wrapper.py"

    %% External Binaries
    subgraph "External Binaries"
        VULCAN["VULCAN"]:::external
        JANUS["JANUS"]:::external
        SPIDER["SPIDER"]:::external
        CALLIOPE["CALLIOPE"]:::external
        LOVEPY["LOVEPY"]:::external
        PLATON["PLATON"]:::external
        PHOENIX["PHOENIX"]:::external
    end
    AtmosChem -->|spawns| VULCAN
    AtmosClim -->|spawns| JANUS
    Interior -->|spawns| SPIDER
    Outgas -->|spawns| CALLIOPE
    Orbit -->|spawns| LOVEPY
    Observe -->|spawns| PLATON
    Star -->|spawns| PHOENIX

    %% Data Storage
    DataStore["File System (NetCDF/CSV/PDF)"]:::datastore
    Star -->|writes results| DataStore

    %% Plotting & Reporting
    Plot["Plotting & Reporting"]:::python
    DataStore -->|reads outputs| Plot
    click Plot "https://github.com/formingworlds/proteus/blob/main/src/proteus/plot/__init__.py"

    %% Inference Engine
    subgraph "Inference Engine"
        Inference["Inference Engine"]:::python
    end
    DataStore -->|analysis| Inference
    Inference -->|optimizes| Coupler
    click Inference "https://github.com/formingworlds/proteus/blob/main/src/proteus/inference/inference.py"

    %% Utilities
    Utilities["Utilities"]:::python
    Coupler --> Utilities
    click Utilities "https://github.com/formingworlds/proteus/blob/main/src/proteus/utils/archive.py"

    %% CI and Deployment
    CI["CI / Docker / Docs"]:::external

    %% Styles
    classDef python fill:#D0E1F9,stroke:#1E3A8A,color:#1E3A8A;
    classDef external fill:#D1FAE5,stroke:#047857,color:#047857,stroke-dasharray: 5 5;
    classDef datastore fill:#FEF3C7,stroke:#92400E,color:#92400E;
    class Utilities,Grid,ConfigParser,Coupler,Entrypoint,CLI,Plot,Inference python
    class User,CI external
    class DataStore datastore
```
