fwl-calliope 26.6.1

Planetary accretion and volatile delivery model

CALLIOPE

CALLIOPE is the equilibrium outgassing solver of the PROTEUS coupled atmosphere-interior evolution framework. It computes the partitioning of volatile elements (H, C, N, O, S) between a partially molten silicate mantle and an overlying gas-phase atmosphere, assuming both reservoirs are in thermochemical equilibrium at the planetary surface.

Given an elemental inventory, a magma ocean temperature, a melt fraction, and an oxygen fugacity (specified as a log₁₀ shift from the iron-wüstite buffer, defaulting to the Fischer et al. 2011 parameterisation), CALLIOPE returns the surface partial pressures of eleven volatile species, the dissolved volatile masses, and the atmospheric mass.

Two solver modes are available: equilibrium_atmosphere takes fO₂ as a control variable and derives O from the buffered chemistry, while equilibrium_atmosphere_authoritative_O takes total O mass as input and inverts to recover fO₂. The buffered mode remains the default for standalone use; the authoritative-O mode is the chemistry side of whole-planet oxygen accounting on the PROTEUS side.

Named after the Greek muse of eloquence and epic poetry. Pronounced kal-IGH-uh-pee.

Supported species

H₂O, CO₂, N₂, S₂ (primary unknowns); H₂, CH₄, CO, NH₃, SO₂, H₂S, O₂ (derived from gas-phase equilibrium).

Documentation

Full documentation is at proteus-framework.org/CALLIOPE, including:

• Getting started: installation and a quick path to running.
• Tutorials: first run, Earth and Mars fiducials, two-mode round-trip, coupled-loop driver, speciation phase diagram.
• How-to guides: install, configure, run, couple to PROTEUS, use the authoritative-oxygen mode, test, release.
• Explanations: model overview, equilibrium chemistry, solubility laws, oxygen fugacity, mass balance, authoritative-oxygen mode, CALLIOPE-vs-atmodeller cross-backend comparison.
• API reference and validation anchors: every public function with NumPy-style docstrings, plus the per-source reference-pinned test inventory.

Installation

pip install fwl-calliope

Or, for development:

git clone https://github.com/FormingWorlds/CALLIOPE.git
cd CALLIOPE
pip install -e .[develop,docs]

The docs extra pulls in Zensical so you can build this documentation locally with zensical serve.

Quick start

from calliope.solve import equilibrium_atmosphere, get_target_from_params
from calliope.constants import volatile_species

ddict = {
    'M_mantle': 4.03e24,                      # kg
    'gravity': 9.81, 'radius': 6.371e6,
    'T_magma': 2500.0, 'Phi_global': 1.0,
    'fO2_shift_IW': 0.5,                      # log10 shift relative to IW
    'hydrogen_earth_oceans': 1.0, 'CH_ratio': 0.1,
    'nitrogen_ppmw': 2.0, 'sulfur_ppmw': 200.0,
}
for sp in volatile_species:
    ddict[f'{sp}_included'] = 1
    ddict[f'{sp}_initial_bar'] = 0.0

target = get_target_from_params(ddict)
result = equilibrium_atmosphere(target, ddict)
print(f"P_surf = {result['P_surf']:.1f} bar, "
      f"H2O = {result['H2O_bar']:.1f} bar")

See the first-run tutorial for the full walkthrough.

Citation

If you use CALLIOPE in published work, please cite the four methods papers below. The full reference list (chemistry constants, solubility laws, oxygen-fugacity buffers, applications) is on the Publications page.

• Bower, D.J., Kitzmann, D., Wolf, A.S., Sanan, P., Dorn, C., & Oza, A.V. (2019). Linking the evolution of terrestrial interiors and an early outgassed atmosphere to astrophysical observations. A&A 631, A103. [SciX] [DOI] [arXiv]
• Bower, D.J., Hakim, K., Sossi, P.A., & Sanan, P. (2022). Retention of water in terrestrial magma oceans and carbon-rich early atmospheres. PSJ 3, 93. [SciX] [DOI] [arXiv]
• Nicholls, H., Lichtenberg, T., Bower, D.J., & Pierrehumbert, R. (2024). Magma ocean evolution at arbitrary redox state. JGR Planets 129, e2024JE008576. [SciX] [DOI] [arXiv]
• Nicholls, H., Lichtenberg, T., Chatterjee, R.D., Guimond, C.M., Postolec, E., & Pierrehumbert, R.T. (2026). Volatile-rich evolution of molten super-Earth L 98-59 d. Nature Astronomy. [SciX] [DOI] [arXiv]

License

Apache License 2.0. CALLIOPE is part of the PROTEUS framework.