CLERO (CLimate Emulator for ROcky exoplanets)

What is it

CLERO is an exoGCM emulator that takes a hypothetical planet as input and outputs its 3D steady-state climate. It targets tidally locked ocean-covered rocky planets in or near the habitable zone; see SCOPE.md for detail on its scope of validity.

CLERO computes a probability distribution over climates: predict returns its mean (our best point estimate of the climate) and sample returns draws from the distribution (see UNCERTAINTY.md).

CLERO is based on Gaussian-process latent factor regression (GPLFR) and is trained on ThousandWorlds.

Worked examples in demos/.

Inputs

CO2 + CH4 <= 1; the rest of the atmosphere is N2. The validity ranges from SCOPE.md are available as clero.CORE_DOMAIN and clero.EXTENDED_DOMAIN.

GCM options

um, exocam (recommended — the two high-fidelity targets). exoplasim is a lower-fidelity exoGCM. exocam-pre2022 and lfric should be avoided at inference time — exocam-pre2022 is an older ExoCAM version, and lfric has few training simulations.

For predictions where self-consistency is important (e.g., spatially resolved plots), use a single emulated GCM. Where self-consistency is not needed (e.g., global means), one can average the emulated UM and ExoCAM predictions; this reduces dependence on either GCM's structural biases.

Outputs

The 3D variables (temperature, specific_humidity, cloud_fraction, u, v) are given on 10 pressure levels, level 0 closest to the surface and level 9 closest to the top of the atmosphere; clero.climate_analysis.pressure_levels(P0) returns the level pressures.

Install

pip install clero

Optional extras:

pip install "clero[gpu]"    # torch, for CUDA batch prediction
pip install "clero[demos]"  # jupyter, to run the notebooks in demos/

Quickstart

from clero import Emulator

emu = Emulator()
inputs = {
    "T_star": 3000.0,     # K
    "F_star": 1000.0,     # W/m^2
    "radius": 1.0,        # Earth radii
    "gravity": 9.8,       # m/s^2
    "P_rot": 10.0,        # days
    "P0": 1.0,            # bar
    "CO2": 4.0e-4,        # volume fraction
    "CH4": 0.0,           # volume fraction
    "GCM": "um",
}

# predict climate
mean = emu.predict(inputs)                           # CLERO's best point estimate of the climate
samples = emu.sample(inputs, n_samples=100, seed=0)   # draws from climate distribution

print(mean["surface_temperature"].shape)     # (32, 64)
print(samples["surface_temperature"].shape)  # (100, 32, 64)

Don't want to spell out every parameter? Start from a bundled preset and override what you need:

from clero import EARTH, M_EARTH, TRAPPIST1E
mean = emu.predict({**EARTH, "CO2": 1.0e-3})   # Earth-like planet, overriden to have 1000 ppm CO2
mean = emu.predict(M_EARTH)                    # Earth-like but around a 2600 K M dwarf (self-consistent 5 day rotation period)
mean = emu.predict({**TRAPPIST1E, "CO2": 0.0, "CH4": 0.0})    # TRAPPIST-1e with an N₂-only atmosphere 

There's also a walk-through notebook, demos/quickstart.ipynb.

API

Full reference (generated from the docstrings): https://edstevenson.github.io/clero/

Emulator (prediction):

Top-level helpers:

clero.climate_analysis (helper functions for analyzing climates):

e.g.,

from clero.climate_analysis import stack_levels
climate_mean = emu.predict(inputs)
T = stack_levels(climate_mean, "temperature")  # per-level fields -> one (10, 32, 64) array

Batches and GPU

predict/sample take a batch directly (list of dicts or a column dict). CPU stays pure NumPy:

mean, variance = emu.predict(
    inputs_list,                       # list of input dicts
    space="model",
    return_variance=True,
    fields=["surface_temperature"]     # subset of outputs
)

GPU needs torch with CUDA. Build the emulator with a device and the torch state is cached on first use:

emu = Emulator(device="cuda")
samples = emu.sample(inputs_list, n_samples=64)

Citation

If you use CLERO, please cite the paper:

// TODO: add correct CLERO paper citation here when available