Output format¶

PROTEUS writes simulation output to a directory inside output/. This page documents the structure of that directory and the contents of the main output files.

Directory structure¶

A completed PROTEUS run produces:

output/<run_name>/
    runtime_helpfile.csv    # Main time-series output (tab-separated)
    init_coupler.toml       # Copy of the configuration used
    status                  # Exit status code and description
    proteus_00.log          # Log file (subsequent resumes: proteus_01.log, ...)
    plots/                  # Generated diagnostic plots
        plot_global.png
        plot_escape.png
        plot_interior.png
        ...
    data/                   # Module-specific output files
        <iter>_atm.nc       # Atmosphere profiles (NetCDF, per snapshot)
        <iter>_int.nc       # Interior profiles (NetCDF, per snapshot)
        zalmoxis_output.dat # Zalmoxis structure profile (latest)
        <iter>_zalmoxis.dat # Zalmoxis structure profile saved with each snapshot of a Zalmoxis + Aragog run, restored on resume
        spider_eos/         # Cached EOS lookup tables (if Aragog/SPIDER)
        ...
    observe/                # Synthetic observations (if enabled)
        transit_<source>_synthesis.csv   # Transit depth spectra
        eclipse_<source>_synthesis.csv   # Eclipse depth spectra

<source> is outgas, profile, or offchem, depending on observe.source. With observe.source = "all" (default), PROTEUS writes one pair of files per available source.

Status codes¶

The status file contains a single integer followed by a human-readable description. The codes are:

Helpfile columns¶

The runtime_helpfile.csv is a tab-separated file with one row per coupling iteration. All quantities use SI units unless noted otherwise. The columns are grouped by category below.

The first line holds the column names, and every line ends with a newline (LF or CRLF). Each float is written in the shortest form that reads back as the same double, and a missing value as the token nan. read_helpfile_table in proteus.utils.coupler reads the file exactly and splits a tab-separated file on tabs. It raises HelpfileFormatError for a file whose content it cannot read: no header line, a row whose field count differs from the header, a last line without its newline, a NUL byte, a lone carriage return, bytes that are not UTF-8, text pandas cannot tokenise, a column of text, or fewer data rows than the caller needs (min_rows, which a resume leaves at 0 and the inference readers set to 1). A missing file or a directory in its place raises the operating system's error.

Each iteration carries the previous row forward and overwrites only the columns the active modules produce, so a column whose producer is not part of the current configuration keeps its previous value (initially zero) for the whole run. The "written when" column names the configuration that actually writes each column. The "Read by" column names modules that consume each column, and can over-approximate when consumers read keys through variable or template loops, or under-approximate when consumers read keys dynamically at runtime through computed keys. The "(possible)" label marks consumers in consumers_possible that read columns only conditionally, such as for specific species.

Model tracking¶

Orbital and spin parameters of planet¶

Satellite system¶

Planet structure¶

Temperatures¶

Planet energy fluxes¶

Planet interior properties¶

Energy-conservation columns¶

Host star properties¶

Planet observational properties¶

Atmospheric composition from outgassing¶

Solid-phase volatile trapping¶

Giant-impact accretion ledger¶

Gases from outgassing¶