mahf708/e3smv3-lr-hist-samudrace

E3SMv3 LR historical coupled emulators (prerelease)

Prerelease for testing. Files and history may change. Please get in touch (see Feedback) before publishing results that use these models.

Coupled atmosphere-ocean emulators of one E3SMv3 historical simulation, trained by the E3SM team. They use the ACE atmosphere and Samudra ocean architectures, coupled through fme.coupled as in SamudrACE. Not an Ai2 release, and not endorsed by the ACE or Samudra developers.

Flavors

Flavor	CO2	Aerosol	Config
C0A0	–	–	configs/C0A0.yaml
C1A0	✓	–	configs/C1A0.yaml
C1A1	✓	✓	configs/C1A1-{60mo,12mo,01mo}.yaml

C = CO2 input, A = aerosol input; the checkpoint is checkpoints/<flavor>.tar. Every flavor reads SOLIN, PHIS and LANDFRAC; C1 adds global_mean_co2; A1 adds the EAM aerosol diagnostics aerindexall and colccn.3, in one of three 6-hourly versions:

Aerosol option	Construction
60mo	5-year centred calendar-month means + mean diurnal cycle
12mo	centred 12-month running mean + 5-year mean seasonal and diurnal cycles
01mo	that year's monthly means (interpolated) + mean diurnal cycle

All flavors predict the same 38 atmosphere and 80 ocean variables (sea ice included). The atmosphere is stochastic: configs set seed: 0.

Data

Source	E3SMv3 v3.LR.historical_0101, rerun with online emulator output
Grid	1° Gaussian (180 × 360); EAM from ne30pg2, MPAS from IcoswISC30E3r5 (bilinear)
Time	atmosphere 6-hourly, ocean 5-day means; 1 coupled step = 5 days; noleap
Forcing	1940–2064, one file per year and kind in forcing_data/
Initial conditions	1985-01-01 and 2015-01-01 in initial_conditions/; E3SM restarts for 1940-01-01 in examples/

Quick start

Colab (GPU runtime): install, download, a 40-day run from the repo's initial conditions, then the same from E3SM restart files.

Local setup with uv. If you don't have uv yet (uv --version fails), install it and open a new shell:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then make a project folder with fme and the Hugging Face CLI:

mkdir samudrace && cd samudrace
uv init --bare --python 3.12
uv python pin 3.12
uv add "fme @ git+https://github.com/E3SM-Project/ace@e3smv3-lr-hist-samudrace-rc1" huggingface_hub click scipy

uv run <command> runs a command in this environment, from this folder or any folder below it.

Smoke test (about 8 GB): runs each flavor for 10 days, twice, and checks that the runs finish, repeat bitwise and keep NaNs only where the initial condition has them (needs only uv).

uv run https://huggingface.co/mahf708/e3smv3-lr-hist-samudrace/resolve/rc1/scripts/smoke_test.py

Walkthrough 1: from the initial conditions in this repo

1. Download a checkpoint, the configs, the initial conditions and 1985–1995 forcing (about 4.4 GB):

   uv run hf download mahf708/e3smv3-lr-hist-samudrace --revision rc1 --local-dir e3smv3 \
       --include "checkpoints/C1A0.tar" --include "configs/*" --include "initial_conditions/*" \
       --include "forcing_data/*-forcing-198[5-9].nc" --include "forcing_data/*-forcing-199[0-5].nc"
   

2. Run 4 coupled steps (20 days) from inside the folder; config paths are relative to it:

   cd e3smv3
   uv run python -m fme.coupled.inference configs/C1A0.yaml --override n_coupled_steps=4 coupled_steps_in_memory=1
   

3. Outputs: monthly means in results/C1A0/{atmosphere,ocean}/monthly_mean_predictions.nc, final state in restart.nc. Units follow EAM and MPAS, except sst (K) and precipitation (kg m⁻² s⁻¹).

Notes:

• Without --override a run lasts 10 years (730 steps). Other overrides: initial_condition.start_indices.first=1 (2015 start), n_ensemble_per_ic=4, seed=1.
• Forcing must cover years Y to Y+N for an N-year run from year Y, contiguous, with the same first year for every kind.
• hf download takes one pattern per --include. For C1A1, add its checkpoint and one aerosol option, e.g. --include "forcing_data/aerosol/60mo/aerosol-198[5-9].nc".

Walkthrough 2: from E3SM restart files

The same steps work for any E3SMv3 LR restart set (*.eam.i.*, *.mpaso.rst.*, *.mpassi.rst.*). The example uses the 1940-01-01 restarts of v3.LR.historical_0101 in examples/restarts/.

1. From the samudrace folder, download the restarts (about 7.5 GB), the converter, a checkpoint, the configs and 1940–1950 forcing:

   cd ..                                       # only if you are still in e3smv3/ from walkthrough 1
   uv run hf download mahf708/e3smv3-lr-hist-samudrace --revision rc1 --local-dir e3smv3-1940 \
       --include "examples/restarts/*" --include "scripts/*" --include "checkpoints/C1A0.tar" --include "configs/*" \
       --include "forcing_data/*-forcing-194[0-9].nc" --include "forcing_data/*-forcing-1950.nc"
   cd e3smv3-1940
   

2. Convert the restarts; this writes my_initial_conditions/restart-ic-1940_{atmosphere,ocean}_ic.nc:

   uv run python scripts/ic_recipe/create_e3sm_restart_ic.py --config scripts/ic_recipe/restart-ic-1940.yaml
   

3. Check the result (prints PASS):

   uv run python scripts/check_ic.py my_initial_conditions/restart-ic-1940_atmosphere_ic.nc \
       my_initial_conditions/restart-ic-1940_ocean_ic.nc forcing_data/ocean-forcing-1940.nc
   

4. Run 4 coupled steps from it:

   uv run python -m fme.coupled.inference configs/C1A0.yaml --override n_coupled_steps=4 coupled_steps_in_memory=1 \
       initial_condition.atmosphere.path=my_initial_conditions/restart-ic-1940_atmosphere_ic.nc \
       initial_condition.ocean.path=my_initial_conditions/restart-ic-1940_ocean_ic.nc
   

Notes:

• Steps 1–4 as one command: uv run https://huggingface.co/mahf708/e3smv3-lr-hist-samudrace/resolve/rc1/scripts/ic_recipe/example_1940.py.
• For your own restarts: one folder per date, a copy of restart-ic-1940.yaml with restart_glob, output_directory and output_prefix changed, and forcing that starts in the IC's year.
• The converter is vendored from E3SM-Project/ace PR #17; see scripts/ic_recipe/README.md.

Files

Path	Contents
checkpoints/	one coupled checkpoint per flavor (EMA weights, 2.2 GB each)
configs/	10-year inference configs
forcing_data/	forcing per year; aerosol options in forcing_data/aerosol/<option>/
initial_conditions/	1985-01-01 and 2015-01-01 states
examples/restarts/	E3SM restart files at 1940-01-01
notebooks/	Colab quick start
scripts/	smoke test, forcing builder, IC converter and check, remap files
MANIFEST.md	every file with its size

Feedback

Please report problems, questions and results as an issue on E3SM-Project/ace, with e3smv3-lr-hist-samudrace and the flavor in the title. Issues there are public. For anything else, contact @mahf708.

License

BSD 3-Clause. The code that runs these models (fme) is licensed separately by its authors.

Attribution

These models are trained on output of the Energy Exascale Earth System Model (E3SM), developed by the U.S. Department of Energy (DOE). The E3SM simulation that produced the training data was run on Crux at the Argonne Leadership Computing Facility (ALCF), a DOE Office of Science User Facility at Argonne National Laboratory. The models were trained and evaluated on the Perlmutter system of the National Energy Research Scientific Computing Center (NERSC), a DOE Office of Science User Facility at Lawrence Berkeley National Laboratory. The architectures and training code come from the open-source ACE / fme and Samudra projects; we thank their developers and the E3SM team.