atmodeller 0.4.0

Volatile partitioning between a rocky interior and atmosphere

Atmodeller

About

Atmodeller is a Python package that leverages JAX to compute the partitioning of volatiles between a planetary atmosphere and its rocky interior. It is released under The GNU General Public License v3.0 or later.

Documentation will eventually be available on readthedocs, but for the time being you can access the latest manual here

Current development team:

• Dan J. Bower (lead developer, ETH Zurich)
• Maggie A. Thompson (ETH Zurich/Carnegie)
• Kaustubh Hakim (KU Leuven/Royal Observatory of Belgium)
• Meng Tian (LMU Munich)
• Paolo A. Sossi (ETH Zurich)

Citation

If you use Atmodeller please cite (prior to manuscript submission, check back to see if this reference has been updated):

• Bower, D. J., Thompson, M. A., Hakim, K., Tian, M., and Sossi P. A. (2025), Diversity of rocky planet atmospheres in the C-H-O-N-S-Cl system with interior dissolution, non-ideality and condensation: Application to TRAPPIST-1e and sub-Neptunes, The Astrophysical Journal, submitted.

Basic usage

There are Jupyter notebooks in notebooks/ that provide code snippets for how to perform single and batch calculations, as well as include Atmodeller into a time integration.

from atmodeller import (
    InteriorAtmosphere,
    Planet,
    Species,
    SpeciesCollection,
    earth_oceans_to_hydrogen_mass,
)
from atmodeller.solubility import get_solubility_models

solubility_models = get_solubility_models()
# Get the available solubility models
print("solubility models = ", solubility_models.keys())

H2_g = Species.create_gas("H2_g")
H2O_g = Species.create_gas("H2O_g", solubility=solubility_models["H2O_peridotite_sossi23"])
O2_g = Species.create_gas("O2_g")

species = SpeciesCollection((H2_g, H2O_g, O2_g))
planet = Planet()
interior_atmosphere = InteriorAtmosphere(species)

oceans = 1
h_kg = earth_oceans_to_hydrogen_mass(oceans)
o_kg = 6.25774e20
mass_constraints = {
    "H": h_kg,
    "O": o_kg,
}

# If you do not specify an initial solution guess then a default will be used
# Initial solution guess number density (molecules/m^3)
initial_log_number_density = 50

interior_atmosphere.solve(
    planet=planet,
    initial_log_number_density=initial_log_number_density,
    mass_constraints=mass_constraints,
)
output = interior_atmosphere.output

# Quick look at the solution
solution = output.quick_look()

# Get complete solution as a dictionary
solution_asdict = output.asdict()
print("solution_asdict =", solution_asdict)

# Write the complete solution to Excel
output.to_excel("example_single")

Installation

Atmodeller is a Python package that can be installed on a variety of platforms (e.g. Mac, Windows, Linux).

Quick install

If you want to use a GUI to install the code, particularly if you are a Windows or Spyder user, see here. Otherwise, follow the instructions below to install the code using the terminal on a Mac or Linux system.

1. Obtain the source code

Navigate to a location on your computer and obtain the source code. To clone using ssh, where you must use a password-protected SSH key:

git clone [e-mail]:ExPlanetology/atmodeller.git
cd atmodeller

Instructions for connecting to GitHub with SSH are available here.

If you do not have SSH keys set up, instead you can clone using HTTPS:

git clone https://github.com/ExPlanetology/atmodeller.git
cd atmodeller

2. Create a Python environment

The basic procedure is to install Atmodeller into a Python environment. For example, if you are using a Conda distribution to create Python environments (e.g. Anaconda), create a new environment to install Atmodeller. Atmodeller requires Python >= 3.10:

conda create -n atmodeller python
conda activate atmodeller

3. Install into the environment

Install Atmodeller into the environment using either (a) Poetry or (b) pip. If you are a developer you will probably prefer to use Poetry and if you are an end-user you will probably prefer to use pip. This Gist provides further information.

3a. Option 1: Poetry

This requires that you have you have Poetry installed:

poetry install

3b. Option 2: pip

Alternatively, use pip, where you can include the -e option if you want an editable install .

pip install .

If desired, you will need to manually install the dependencies for testing and documentation (these are automatically installed by Poetry but not when using pip). See the additional dependencies to install in pyproject.toml.

Developer install

See this developer setup guide to set up your system to develop Atmodeller using VS Code and Poetry.

Examples

Several examples are provided in notebooks/.