fwl-calliope 26.5.10

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, 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), CALLIOPE returns the surface partial pressures of eleven volatile species, the dissolved volatile masses, and the atmospheric mass.

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.
• First-run tutorial — Earth-like solve with a Δ-IW redox sweep.
• How-to guides — install, configure, run, couple to PROTEUS, test, release.
• Explanations — model overview, equilibrium chemistry, solubility laws, oxygen fugacity, mass balance, code architecture.
• API reference — every public function with NumPy-style docstrings.

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 three 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. [ADS] [DOI]
• 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. [ADS] [DOI]
• Nicholls, H., Lichtenberg, T., Bower, D.J., & Pierrehumbert, R. (2024). Magma ocean evolution at arbitrary redox state. JGR Planets 129, e2024JE008576. [ADS] [DOI] [arXiv]

License

Apache License 2.0. CALLIOPE is part of the Forming Worlds Lab PROTEUS framework.