VULCAN in PROTEUS

VULCAN serves as the atmospheric chemistry module within the PROTEUS framework, computing steady-state photochemical and thermochemical mixing-ratio profiles from the temperature–pressure structure produced by AGNI at each chemistry step. This page describes the data flow between PROTEUS and VULCAN: what inputs are prepared, how VULCAN is configured and invoked, and how the results are stored and passed back.

The source code for this coupling lives in the vulcan dispatcher (run_vulcan) and the outer chemistry wrapper (run_chemistry) inside PROTEUS. A description and flowchart of the broader PROTEUS architecture can be found here.

Step-by-step flow

The following flowchart describes each chemistry run in PROTEUS step-by-step. The source code for this diagram can be found in the VULCAN dispatcher in PROTEUS.

flowchart TD
    Start([<b>Start of chemistry step</b>])

    Guard1{"AGNI used?"}
    Abort1["<b>Abort</b> with warning"]

    PrepDir["Prepare output directory\n<code>output/offchem/</code>"]

    ReadAtmos["<b>Read atmosphere data:</b>\nRead <em>p</em>, <em>T</em>, <em>VMR</em>s, <em>Kzz</em>\nfrom AGNI output at <code>hf_row['Time']</code>"]

    WriteInputs["<b>Write VULCAN input files</b>:\n<code>star.dat</code> (stellar spectrum)\n<code>profile.dat</code> (<em>T</em>-<em>P</em>-<em>Kzz</em>)\n<code>vmrs.dat</code> (mixing ratios)"]

    BuildConfig["<b>Build VULCAN config:</b>\nSet network, species, boundary\nconditions, transport, convergence\nand time-stepping parameters"]

    MakeFuns{"<code>make_funs = true</code> <b>and</b> not already compiled?"}
    Compile["<b>vulcan.make_chem_funs.make_all</b>\n(skipped in online mode\nafter first snapshot)"]

    RunVULCAN["<b>vulcan.run_vulcan</b>\nIntegrate chemical kinetics to steady state"]

    CheckOutput{"Output pickle\nexists?"}
    Fail["<b>Fail</b> with warning"]

    ParseOutput["<b>Load pickle:</b>\nExtract <em>T</em>, <em>p</em>, <em>z</em>, <em>Kzz</em> and per-species <em>VMR</em> arrays"]

    WriteCSV["<b>Write human-readable CSV</b>\n<code>vulcan.csv</code> (offline)\n<code>vulcan_{year}.csv</code> (online)"]

    Done([<b>Success</b>])

    Start --> Guard1
    Guard1 -->|no| Abort1
    Guard1 -->|yes| PrepDir
    PrepDir --> ReadAtmos
    ReadAtmos --> WriteInputs
    WriteInputs --> BuildConfig
    BuildConfig --> MakeFuns
    MakeFuns -->|yes| Compile
    MakeFuns -->|no| RunVULCAN
    Compile --> RunVULCAN
    RunVULCAN --> CheckOutput
    CheckOutput -->|no| Fail
    CheckOutput -->|yes| ParseOutput
    ParseOutput --> WriteCSV
    WriteCSV --> Done

Inputs read from PROTEUS

At each call, the dispatcher reads the current atmospheric state produced by AGNI via read_atmosphere_data, requesting the following keys:

The stellar spectrum is read from the nearest-year .sflux file in output/data/ and scaled from the planet's orbital distance to the stellar surface (\(\times\)separation^2 / R_star^2) before being clipped and written to star.dat. VULCAN then re-scales it internally from the stellar surface to the orbital distance.

PROTEUS → VULCAN configuration

The dispatcher translates several PROTEUS config attributes into VULCAN config attributes. The key mappings are:

The background gas (vcfg.atm_base) is chosen automatically as the most abundant of H\(_2\), N\(_2\), O\(_2\), and CO\(_2\) in the current atmosphere.

Network options

Output files

All files are written to output/offchem/.

CSV column order

Columns appear in this order: tmp, p, z, Kzz, then one column per chemical species (excluding any species whose name contains _, i.e. condensates). Arrays are flipped to surface-first ordering to match AGNI's convention.

Online vs offline: key differences