Skip to content

Usage

This page shows the two canonical calling patterns for CALLIOPE: solving from an elemental inventory, and solving from a prescribed initial-pressure atmosphere. Both use the same equilibrium_atmosphere() entry point.

For an end-to-end runnable example with explanations, see the First run tutorial. For the schema of each input field, see Configuration.

Pattern 1 - solve from elemental inventory

This is the workflow PROTEUS uses. You specify the total mass of H, C, N, S in the planet, plus the magma ocean state, and CALLIOPE returns the equilibrium speciation.

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

# 1. Build ddict (planet + magma + inclusion flags)
ddict = {
    'M_mantle': 4.03e24,
    'gravity': 9.81,
    'radius': 6.371e6,
    'Phi_global': 1.0,
    'T_magma': 2500.0,
    'fO2_shift_IW': 0.0,
    # elemental-budget inputs for get_target_from_params
    'hydrogen_earth_oceans': 1.0,    # 1 Earth ocean of H
    'CH_ratio': 0.1,
    'nitrogen_ppmw': 2.0,            # primitive Earth mantle estimate
    'sulfur_ppmw': 200.0,
}
for sp in volatile_species:
    ddict[f'{sp}_included'] = 1
    ddict[f'{sp}_initial_bar'] = 0.0

# 2. Build target from elemental budget
target = get_target_from_params(ddict)

# 3. Solve
result = equilibrium_atmosphere(target, ddict, print_result=True)

# 4. Read out
print(f"Surface pressure  : {result['P_surf']:.2f} bar")
print(f"Atmosphere mass   : {result['M_atm']:.2e} kg")
print(f"H2O bar           : {result['H2O_bar']:.2f}")
print(f"H2O VMR           : {result['H2O_vmr']:.3f}")
print(f"CO2 bar           : {result['CO2_bar']:.2f}")
print(f"H2  VMR           : {result['H2_vmr']:.3f}")

The result dictionary contains, for every species s in volatile_species:

  • s_bar: surface partial pressure, bar
  • s_vmr: volume mixing ratio (== mole fraction)
  • s_kg_atm: atmospheric column mass, kg
  • s_kg_liquid: dissolved mass, kg
  • s_kg_solid: 0.0 (solid partitioning is handled by the caller, not CALLIOPE)
  • s_kg_total: sum of atmosphere + liquid (it excludes the core when a metal reservoir is on)

and per-element totals H_kg_atm, C_kg_atm, ..., S_res (mass-balance residual in kg). fallback (a bool) is True when the returned state misses the tolerance of an element and a warning was logged. fO2_model names the IW buffer the solve used (a string); set it as ddict['fO2_model'] to evaluate a state with get_partial_pressures, atmosphere_mass or dissolved_mass on the same buffer. With metal_mass above zero in ddict the result also carries the metal reservoir keys <e>_kg_core, w_<e>_core, <e>_D_metal, <e>_D_out_of_range and dIW_eq (metal reservoir).

Pattern 2 - solve from initial partial pressures

Use this when you know the initial composition of the atmosphere and want to back out the consistent total inventory plus the equilibrium update.

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

ddict = {
    'M_mantle': 4.03e24,
    'gravity': 9.81,
    'radius': 6.371e6,
    'Phi_global': 1.0,
    'T_magma': 2500.0,
    'fO2_shift_IW': 0.0,
}
for sp in volatile_species:
    ddict[f'{sp}_included'] = 1
    ddict[f'{sp}_initial_bar'] = 0.0

# Specify the initial atmosphere by its primary-species partial pressures
ddict['H2O_initial_bar'] = 220.0    # bar
ddict['CO2_initial_bar'] = 100.0
ddict['N2_initial_bar']  = 1.0
ddict['S2_initial_bar']  = 0.01

target = get_target_from_pressures(ddict)
result = equilibrium_atmosphere(target, ddict, print_result=True)

get_target_from_pressures() computes the implied total elemental masses by summing atmospheric column mass (Bower et al. (2019) 3 Eq. 2) and dissolved mass (Henry's law) across every included species at the prescribed initial pressures.

Pattern 3 - add a metal reservoir

Start from the ddict and target of Pattern 1. Add metal_mass (kg) above zero and the conditions of the metal-melt equilibrium, and the same call solves gas, melt and metal together:

ddict_metal = {
    **ddict,
    'metal_mass': 1.94e24,  # kg of metal in equilibrium with the present melt
    'P_eq': 50.0,  # GPa
    'T_eq': 3500.0,  # K
    'dIW_eq': -1.0,  # log10 units relative to the IW buffer
}
result = equilibrium_atmosphere(target, ddict_metal, print_result=False)
print(f"H in the metal: {result['H_kg_core']:.3e} kg, D_H = {result['H_D_metal']:.3g}")

With the input of Pattern 1 this prints H in the metal: 1.417e+20 kg, D_H = 22.1, together with the warnings that the metal reservoir tutorial explains.

The result adds, per element e, the mass in the metal <e>_kg_core (kg), the mass fraction w_<e>_core, the partition coefficient <e>_D_metal and the range flag <e>_D_out_of_range, plus dIW_eq and the FeO exchange keys. <e>_kg_total stays the gas plus the melt; the bulk inventory is <e>_kg_total + <e>_kg_core. The partition file reference lists every key, the metal reservoir tutorial runs the options step by step, and the explanation page gives the physics.

Warm-starting from a previous solve

For repeated calls (e.g. inside a time-evolution loop), pass the previous solution as the initial guess to dramatically reduce the number of fsolve iterations:

p_guess = {
    'H2O': result['H2O_bar'],
    'CO2': result['CO2_bar'],
    'N2':  result['N2_bar'],
    'S2':  result['S2_bar'],
}
result_new = equilibrium_atmosphere(target_new, ddict_new, p_guess=p_guess, print_result=False)

This is exactly what the PROTEUS wrapper does. With a good warm start, convergence typically takes 1 to 3 fsolve iterations; without one, CALLIOPE may need 20+ Monte-Carlo restarts before it lands on a plausible basin.

Choosing solubility laws

To override the default solubility law for a species, instantiate the law explicitly and pass it through your own wrapper rather than calling equilibrium_atmosphere() directly. The defaults are:

Species Default class Default composition Source
H\(_2\)O SolubilityH2O peridotite Sossi et al. (2023) 7
CO\(_2\) SolubilityCO2 basalt_dixon Dixon et al. (1995) 5
CO SolubilityCO mafic_armstrong Armstrong et al. (2015) 2
CH\(_4\) SolubilityCH4 basalt_ardia Ardia et al. (2013) 1
N\(_2\) SolubilityN2 dasgupta (in dissolved_mass) Dasgupta et al. (2022) 4
S\(_2\) SolubilityS2 gaillard Gaillard et al. (2022) 6

Alternative compositions (e.g. SolubilityH2O('basalt_dixon'), SolubilityH2O('lunar_glass')) are documented in the API reference and discussed in Solubility laws.

Next step

For the science behind these laws and the equilibrium constants, head to Equilibrium chemistry and Solubility laws. For the PROTEUS-side TOML recipe, head to Coupling to PROTEUS. If you have an oxygen budget to enforce rather than a buffer offset to apply, switch to the authoritative-O recipe.


  1. P. Ardia, M. M. Hirschmann, A. C. Withers, B. D. Stanley, Solubility of CH\(_4\) in a synthetic basaltic melt, with applications to atmosphere-magma ocean-core partitioning of volatiles and to the evolution of the Martian atmosphere, Geochimica et Cosmochimica Acta, 114, 52–71, 2013. SciX. ↩

  2. L. S. Armstrong, M. M. Hirschmann, B. D. Stanley, E. G. Falksen, S. D. Jacobsen, Speciation and solubility of reduced C-O-H-N volatiles in mafic melt: implications for volcanism, atmospheric evolution, and deep volatile cycles in the terrestrial planets, Geochimica et Cosmochimica Acta, 171, 283–302, 2015. SciX. ↩

  3. D. J. Bower, D. Kitzmann, A. S. Wolf, P. Sanan, C. Dorn, A. V. Oza, Linking the evolution of terrestrial interiors and an early outgassed atmosphere to astrophysical observations, Astronomy & Astrophysics, 631, A103, 2019. SciX. ↩

  4. R. Dasgupta, E. Falksen, A. Pal, C. Sun, The fate of nitrogen during parent body partial melting and accretion of the inner Solar System bodies at reducing conditions, Geochimica et Cosmochimica Acta, 336, 291–307, 2022. SciX. ↩

  5. J. E. Dixon, E. M. Stolper, J. R. Holloway, An experimental study of water and carbon dioxide solubilities in mid-ocean ridge basaltic liquids. Part I: Calibration and solubility models, Journal of Petrology, 36(6), 1607–1631, 1995. SciX. ↩

  6. F. Gaillard, F. Bernadou, M. Roskosz, M. A. Bouhifd, Y. Marrocchi, G. Iacono-Marziano, M. Moreira, B. Scaillet, G. Rogerie, Redox controls during magma ocean degassing, Earth and Planetary Science Letters, 577, 117255, 2022. SciX. ↩

  7. P. A. Sossi, P. M. E. Tollan, J. Badro, D. J. Bower, Solubility of water in peridotite liquids and the prevalence of steam atmospheres on rocky planets, Earth and Planetary Science Letters, 601, 117894, 2023. SciX. ↩