Public release, 2025-10 (#46)

Updates the codebase to a recent commit on `full-model` (`3ef085c`), with squash-merged git history.

Author: brianhenn

.github/workflows/docs.yaml

@@ -8,6 +8,21 @@ on:
     branches:
       - main
 
+  # Add a button to manually trigger the workflow
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -22,19 +37,27 @@ jobs:
       - uses: actions/cache@v4
         with:
           path: ${{ env.pythonLocation }}
-          key: v1-${{ env.CURRENT_WEEK }}-${{ env.pythonLocation }}-${{ hashFiles('requirements.txt') }}-${{ hashFiles('docs/requirements.txt') }}-${{ hashFiles('constraints.txt') }}
+          key: v1-${{ env.CURRENT_WEEK }}-${{ env.pythonLocation }}-${{ hashFiles('requirements.txt') }}-${{ hashFiles('docs/requirements.txt') }}-${{ hashFiles('requirements-healpix.txt') }}-${{ hashFiles('constraints.txt') }}
       - name: Install dependencies
         run: |
           python -m pip install uv
-          uv pip install --system -c constraints.txt -e .[docs]
+          # can't use --system here because it doesn't work with --no-build-isolation and a healpix dependency
+          uv venv --python 3.11
+          uv pip install -c constraints.txt -e .[docs]
+          uv pip install --no-build-isolation -c constraints.txt -e .[docs,healpix]
       - name: Build docs
         run: |
+          source .venv/bin/activate
           cd docs && make doctest html
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
-        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+      - name: Upload to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
         with:
-          publish_branch: gh-pages
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/_build/
-          force_orphan: true
+          path: docs/_build/html
+  deploy:
+    runs-on: ubuntu-latest
+    # Only deploy on manual trigger or push to main
+    if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main') }}
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.github/workflows/tests.yaml

@@ -22,15 +22,19 @@ jobs:
       - uses: actions/cache@v4
         with:
           path: ${{ env.pythonLocation }}
-          key: v1-${{ env.CURRENT_WEEK }}-${{ env.pythonLocation }}-${{ hashFiles('requirements.txt') }}-${{ hashFiles('requirements-dev.txt') }}-${{ hashFiles('constraints.txt') }}
+          key: v1-${{ env.CURRENT_WEEK }}-${{ env.pythonLocation }}-${{ hashFiles('requirements.txt') }}-${{ hashFiles('requirements-dev.txt') }}-${{ hashFiles('requirements-healpix.txt') }}-${{ hashFiles('constraints.txt') }}
       - name: Install dependencies
         run: |
           python -m pip install uv
-          uv pip install --system -c constraints.txt -e .[dev]
+          # can't use --system here because it doesn't work with --no-build-isolation and a healpix dependency
+          uv venv --python 3.11
+          uv pip install -c constraints.txt -e .[dev]
+          uv pip install --no-build-isolation -c constraints.txt -e .[dev,healpix]
       - name: Run pytest with code coverage
         run: |
+          source .venv/bin/activate
           make test_cov
-  cpu-very-fast:
+  cpu-very-fast-no-healpix:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -50,4 +54,4 @@ jobs:
           uv pip install --system -c constraints.txt -e .[dev]
       - name: Run pytest
         run: |
-          make test_very_fast
+          make test_very_fast

.gitignore

@@ -1,4 +1,5 @@
 docs/available_modules.rst
+docs/available_steps.rst
 docs/_build
 
 .vscode

.pre-commit-config.yaml

@@ -10,6 +10,10 @@ repos:
     hooks:
     - id: check-added-large-files
       args: [--maxkb=250]
+      exclude: |
+        (?x)^(
+        fme/ace/aggregator/inference/testdata/.*-regression.pt
+        )$
     - id: trailing-whitespace
     - id: file-contents-sorter
       files: |

Makefile

@@ -15,12 +15,12 @@ build_docker_image:
 enter_docker_image: build_docker_image
 	docker run -it --rm $(IMAGE):$(VERSION) bash
 
-
 # recommended to deactivate current conda environment before running this
 create_environment:
 	conda create -n $(ENVIRONMENT_NAME) python=3.11 $(CONDA_PACKAGES)
 	conda run --no-capture-output -n $(ENVIRONMENT_NAME) python -m pip install uv
 	conda run --no-capture-output -n $(ENVIRONMENT_NAME) uv pip install -c constraints.txt -e .[dev,docs]
+	conda run --no-capture-output -n $(ENVIRONMENT_NAME) uv pip install --no-build-isolation -c constraints.txt -r requirements-healpix.txt
 	conda run --no-capture-output -n $(ENVIRONMENT_NAME) uv pip install -r analysis-deps.txt
 
 test:

PACKAGE_README.md

@@ -1,8 +1,11 @@
 [![Docs](https://readthedocs.org/projects/ai2-climate-emulator/badge/?version=latest)](https://ai2-climate-emulator.readthedocs.io/en/latest/)
-[![PyPI](https://img.shields.io/pypi/v/fme.svg)](https://pypi.org/project/fme/)
 
 # FME: Weather/Climate Model Emulation
-This package contains code to train and evaluate weather/climate model emulators.
+This package contains code to train and evaluate weather/climate model emulators as seen in
+"ACE: A fast, skillful learned global atmospheric model for climate prediction" ([arxiv:2310.02074](https://arxiv.org/abs/2310.02074))
+and "Application of the Ai2 Climate Emulator to E3SMv2's global atmosphere model, with a focus on precipitation fidelity"
+([JGR-ML](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2024JH000136)).
+
 
 ## Installation
 

README.md

@@ -11,8 +11,8 @@ This repo contains code accompanying five papers describing ACE models:
 - "ACE: A fast, skillful learned global atmospheric model for climate prediction" ([link](https://arxiv.org/abs/2310.02074))
 - "Application of the Ai2 Climate Emulator to E3SMv2's global atmosphere model, with a focus on precipitation fidelity" ([link](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2024JH000136))
 - "ACE2: Accurately learning subseasonal to decadal atmospheric variability and forced responses" ([link](https://www.nature.com/articles/s41612-025-01090-0))
-- "ACE2-SOM: Coupling to a slab ocean and learning the sensitivity of climate to changes in CO2" ([link](https://arxiv.org/abs/2412.04418))
-- "Applying the ACE2 Emulator to SST Green's Functions for the E3SMv3 Global Atmosphere Model" ([link](https://arxiv.org/abs/2505.08742))
+- "ACE2-SOM: Coupling an ML Atmospheric Emulator to a Slab Ocean and Learning the Sensitivity of Climate to Changed CO<sub>2</sub>" ([link](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2024JH000575))
+- "Applying the ACE2 Emulator to SST Green's Functions for the E3SMv3 Global Atmosphere Model" ([link](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2025JH000774))
 
 ## Installation
 
@@ -26,4 +26,25 @@ See complete documentation [here](https://ai2-climate-emulator.readthedocs.io/en
 
 ## Model checkpoints
 
-Pretrained model checkpoints, and datasets to run them, are available in the [ACE Hugging Face](https://huggingface.co/collections/allenai/ace-67327d822f0f0d8e0e5e6ca4) collection.
+Pretrained model checkpoints are available in the [ACE Hugging Face](https://huggingface.co/collections/allenai/ace-67327d822f0f0d8e0e5e6ca4) collection.
+
+## Available datasets
+Two versions of the complete dataset described in [arxiv:2310.02074](https://arxiv.org/abs/2310.02074)
+are available on a [requester pays](https://cloud.google.com/storage/docs/requester-pays) Google Cloud Storage bucket:
+```
+gs://ai2cm-public-requester-pays/2023-11-29-ai2-climate-emulator-v1/data/repeating-climSST-1deg-zarrs
+gs://ai2cm-public-requester-pays/2023-11-29-ai2-climate-emulator-v1/data/repeating-climSST-1deg-netCDFs
+```
+The `zarr` format is convenient for ad-hoc analysis. The netCDF version contains our
+train/validation split which was used for training and inference.
+
+The datasets used in the [ACE2 paper](https://arxiv.org/abs/2411.11268) are available at:
+```
+gs://ai2cm-public-requester-pays/2024-11-13-ai2-climate-emulator-v2-amip/data/c96-1deg-shield/
+gs://ai2cm-public-requester-pays/2024-11-13-ai2-climate-emulator-v2-amip/data/era5-1deg-1940-2022.zarr/
+```
+
+The dataset used in the [ACE2-SOM paper](https://arxiv.org/abs/2412.04418) is available at:
+```
+gs://ai2cm-public-requester-pays/2024-12-05-ai2-climate-emulator-v2-som/SHiELD-SOM-C96
+```

docker/Dockerfile

@@ -21,6 +21,8 @@ ENV FORCE_CUDA_EXTENSION=1
 # install python deps
 COPY requirements.txt /tmp/requirements.txt
 RUN python3 -m pip install -r /tmp/requirements.txt
+COPY requirements-healpix.txt /tmp/requirements-healpix.txt
+RUN python3 -m pip install --no-build-isolation -r /tmp/requirements-healpix.txt
 
 FROM base AS production
 

docs/api.rst

@@ -15,3 +15,9 @@ fme.ace
 
 .. automodule:: fme.ace
    :members:
+
+fme.coupled
+===========
+
+.. automodule:: fme.coupled
+   :members:

docs/builder.rst

@@ -11,6 +11,7 @@ The Builder Pattern is a design pattern that lets user configuration change the
 Those objects are then used by the code, without that code ever knowing about or handling user configuration.
 
 At its core, the builder pattern contains two components:
+
 - A class that represents the configuration, called the Config, which has a build method returning a built instance.
 - A class built by the configuration, called the Product or the "instance".