Atmodeller is a Python package for thermochemical equilibrium modelling of planetary interiors and atmospheres, built on JAX. It can also be used as a generic thermochemical equilibrium engine for other applications.
Atmodeller computes the chemical equilibrium between a planet's interior and atmosphere, solving gas-phase speciation, condensate stability and volatile solubility in silicate melt together, with real-gas equations of state for high pressures. It is designed for researchers in planetary science, exoplanet science and geochemistry who need these calculations, either standalone or as one component of a larger model. Applications include magma oceans, volcanic outgassing, and the atmospheres of super-Earths and sub-Neptunes. Users assemble a model from the species, solubility laws and equations of state they need, so the effect of each modelling choice can be explored. Because it is built on JAX, a batch of conditions is solved in one call and derivatives of the solution with respect to its inputs are available, which supports parameter sweeps, Monte Carlo sampling and gradient-based Bayesian inference.
It is released under the Apache License, Version 2.0.
The documentation is available online, with options to download it in EPUB or PDF format:
https://atmodeller.readthedocs.io/en/latest/
Atmodeller is a Python package that can be installed on a variety of platforms (e.g. Mac, Windows, Linux). It is recommended to install Atmodeller in a dedicated Python environment. Before installation, create and activate the environment, then run:
pip install atmodeller
Downloading the source code is also recommended if you'd like access to the example notebooks in notebooks/examples/.
If you use Atmodeller, or data from Atmodeller, please cite:
- Bower, D. J., Thompson, M. A., Hakim, K., Tian, M., and Sossi, P. A. (2025), Diversity of low-mass planet atmospheres in the C–H–O–N–S–Cl system with interior dissolution, nonideality and condensation: Application to TRAPPIST-1e and sub-Neptunes, The Astrophysical Journal, 995(1), 59, doi: https://www.doi.org/10.3847/1538-4357/ae1479. ArXiv e-print 2507.00499.
The data from the above study are also available for download at https://doi.org/10.17605/OSF.IO/PC5TD.
You are welcome to use the Atmodeller logo in presentations, posters, and other materials. The logo is available to download here: logo1200x1200.png.
Unlike the source code, the logo is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). Citing Atmodeller (see Citation) satisfies the attribution requirement, so no separate credit is needed for the logo.
Several Jupyter notebooks providing examples are in the notebooks/examples/ directory. A simple example of how to use Atmodeller is provided below:
import logging
from atmodeller import (
ChemicalSpecies,
EquilibriumModel,
Parameters,
Planet,
ReservoirSpecies,
debug_logger,
earth,
get_solubility_models,
)
# Log to the console (use logging.DEBUG for more output)
logger = debug_logger()
logger.setLevel(logging.INFO)
# Get the available solubility models
solubility_models = get_solubility_models()
print("solubility models =", solubility_models.keys())
# Gas species
H2_g = ChemicalSpecies.create_gas("H2")
H2O_g = ChemicalSpecies.create_gas("H2O")
O2_g = ChemicalSpecies.create_gas("O2")
# H2O dissolved in the silicate melt
H2O_d = ReservoirSpecies.create_dissolved(
"H2O", solubility=solubility_models["H2O_peridotite_sossi23"]
)
planet = Planet.from_species((H2_g, H2O_g, O2_g), silicate_melt_species=(H2O_d,))
oceans = 1
h_kg = earth.oceans_to_hydrogen_mass(oceans)
o_kg = 6.25774e20
mass_constraints = {"H": h_kg, "O": o_kg}
parameters = Parameters(planet, mass_constraints=mass_constraints)
model = EquilibriumModel(parameters)
# Solve with the default initial guess
output = model.solve_with_default()
# Check the solve was successful
output.solver_stats_to_logger()
# Quick look at the solution
output.quick_look()
# Get the complete solution as a nested dictionary
solution = output.to_dict(to_numpy=True)
print("H2O partial pressure (bar) =", solution["gas"]["species"]["partial_pressure"]["H2O_g"])
# Write the complete solution to Excel
output.to_excel("example_single")Community development of Atmodeller is strongly encouraged, and bug fixes and new features are welcome. Please open an issue to report a bug or request a feature. For questions, ideas, or to share how you are using Atmodeller, start a thread in Discussions. To submit changes, see CONTRIBUTING.md.
Atmodeller was created as part of a SERI-funded ERC Starting grant '2ATMO' granted to P. Sossi (Contract no. MB22.00033), with additional funding provided through a Swiss National Science Foundation (SNSF) Eccellenza Professorship (#203668).
M. Thompson was supported by NASA through the NASA Hubble Fellowship grant #HST-HF2-51545 awarded by the Space Telescope Science Institute, United States, which is operated by the Association of Universities for Research in Astronomy, Inc., for NASA under contract NAS5-26555.
K. Hakim acknowledges the FED-tWIN research programme STELLA (Prf-2021-022) funded by the Belgian Science Policy Office (BELSPO) and the research grant G014425N funded by the Research Foundation Flanders (FWO).