From 116be05074648fd92e403fcfe012cb3ad9fc5537 Mon Sep 17 00:00:00 2001 From: Mariah Pope Date: Wed, 22 Oct 2025 12:47:16 -0400 Subject: [PATCH 1/5] initial docs commit --- .readthedocs.yaml | 34 ++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + src/README.md | 1 - tests/README.md | 1 - 4 files changed, 35 insertions(+), 2 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/index.rst delete mode 100644 src/README.md delete mode 100644 tests/README.md diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..ea2f74d --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,34 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-24.04 + tools: + python: "3.12" + # You can also specify other tool versions: + # nodejs: "20" + # rust: "1.70" + # golang: "1.20" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs + # builder: "dirhtml" + # Fail on all warnings to avoid broken references + # fail_on_warning: true +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +# python: +# install: +# - requirements: docs/requirements.txt diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..6e3153c --- /dev/null +++ b/docs/index.rst @@ -0,0 +1 @@ +Welcome to Eagle documentation! diff --git a/src/README.md b/src/README.md deleted file mode 100644 index f87f5c1..0000000 --- a/src/README.md +++ /dev/null @@ -1 +0,0 @@ -# TODO \ No newline at end of file diff --git a/tests/README.md b/tests/README.md deleted file mode 100644 index f87f5c1..0000000 --- a/tests/README.md +++ /dev/null @@ -1 +0,0 @@ -# TODO \ No newline at end of file From 5d6fb76163266bdd8280c1224a19f05bcc0c48aa Mon Sep 17 00:00:00 2001 From: Mariah Pope Date: Wed, 22 Oct 2025 13:28:09 -0400 Subject: [PATCH 2/5] some readthedocs necessary items --- docs/Makefile | 20 +++++++++++++++ docs/conf.py | 63 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++ environment.yaml | 19 +++++++++++++++ 4 files changed, 137 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/make.bat create mode 100644 environment.yaml diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..2428df9 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ + # Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..708239f --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,63 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = "eagle" +copyright = "2025, eagle contributors " +author = "eagle contributors" + + +# -- General configuration --------------------------------------------------- +# -- General configuration + +extensions = [ + "sphinx.ext.duration", + "sphinx.ext.doctest", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", +] + +intersphinx_mapping = { + "rtd": ("https://docs.readthedocs.io/en/stable/", None), + "python": ("https://docs.python.org/3/", None), + "sphinx": ("https://www.sphinx-doc.org/en/master/", None), +} +intersphinx_disabled_domains = ["std"] + +templates_path = ["_templates"] + +# -- Options for EPUB output +epub_show_urls = "footnote" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..b4f380c --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd \ No newline at end of file diff --git a/environment.yaml b/environment.yaml new file mode 100644 index 0000000..1d983a4 --- /dev/null +++ b/environment.yaml @@ -0,0 +1,19 @@ +name: eagle +channels: + - conda-forge + - defaults +dependencies: + - python=3.11 + - ufs2arco + - pip + - pip: + - torch<2.7 + - anemoi-datasets==0.5.26 + - anemoi-graphs==0.6.4 + - anemoi-models==0.9.2 + - anemoi-training==0.6.2 + - anemoi-inference==0.7.1 + - anemoi-utils==0.4.35 + - anemoi-transform==0.1.16 + - flash-attn<2.8 --no-build-isolation + - eagle-tools From 6b53377ca2c13d4b956f20eff8d97cf4735ac554 Mon Sep 17 00:00:00 2001 From: Mariah Pope Date: Wed, 22 Oct 2025 13:59:52 -0400 Subject: [PATCH 3/5] initial bare bones --- docs/getting_started.rst | 19 +++++++++++++++++++ docs/index.rst | 6 +++++- docs/inference.rst | 9 +++++++++ docs/nested-eagle.rst | 5 +++++ docs/training.rst | 12 ++++++++++++ docs/ufs2arco.rst | 9 +++++++++ docs/verification.rst | 9 +++++++++ 7 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 docs/getting_started.rst create mode 100644 docs/inference.rst create mode 100644 docs/nested-eagle.rst create mode 100644 docs/training.rst create mode 100644 docs/ufs2arco.rst create mode 100644 docs/verification.rst diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 0000000..7df2ac3 --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,19 @@ +================= +Getting Started +================= + +Learn how to use the full `ufs2arco + Anemoi + wxvx` pipeline. + +You will learn how to: +1) Use `ufs2arco` to create training and validation datasets with NOAA Replay reanalysis + - 1 year of data for training and 0.25 years for validation + - 1-degree global data +2) Use `anemoi-core` modules to train a graph-based model +3) Use `anemoi-inference` to run inference +4) Use `wxvx` to verify a forecast + +------------- +Ursa +------------- + +Insert instructions for Ursa \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 6e3153c..42d78e7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1 +1,5 @@ -Welcome to Eagle documentation! +================= +Welcome to Eagle! +================= + +Enter overview of Eagle project....? \ No newline at end of file diff --git a/docs/inference.rst b/docs/inference.rst new file mode 100644 index 0000000..fa53024 --- /dev/null +++ b/docs/inference.rst @@ -0,0 +1,9 @@ +================= +Inference +================= + +We use the anemoi-inference package to create a forecast. + +Helpful quick tips for using anemoi-inference + +See `anemoi-inference documentation `_documentation for further information: \ No newline at end of file diff --git a/docs/nested-eagle.rst b/docs/nested-eagle.rst new file mode 100644 index 0000000..2ff134a --- /dev/null +++ b/docs/nested-eagle.rst @@ -0,0 +1,5 @@ +================= +Nested Eagle +================= + +Overview of Nested-Eagle \ No newline at end of file diff --git a/docs/training.rst b/docs/training.rst new file mode 100644 index 0000000..f1f26b0 --- /dev/null +++ b/docs/training.rst @@ -0,0 +1,12 @@ +================= +Train a Graph-Based Model +================= + +We use the anemoi-core modules to train a graph-baed model. + +Helpful quick tips for using Anemoi + +See Anemoi documentation for further information: +- `anemoi-graphs `_ +- `anemoi-training `_ +- `anemoi-models `_ diff --git a/docs/ufs2arco.rst b/docs/ufs2arco.rst new file mode 100644 index 0000000..21ecceb --- /dev/null +++ b/docs/ufs2arco.rst @@ -0,0 +1,9 @@ +================= +Create Training, Validation, and Test Datasets +================= + +We use ufs2arco to generate our datasets. + +Helpful quick tips for ufs2arco + +See `ufs2arco `_ for further information. \ No newline at end of file diff --git a/docs/verification.rst b/docs/verification.rst new file mode 100644 index 0000000..fba89d2 --- /dev/null +++ b/docs/verification.rst @@ -0,0 +1,9 @@ +================= +Validation +================= + +We use wxvx for forecast verification. + +Helpful quick tips for using wxvx. + +See `wxvx `_ for further information. \ No newline at end of file From 9534872401f35fa68c8d9f7e9c5e550bdeec1fe5 Mon Sep 17 00:00:00 2001 From: Mariah Pope Date: Wed, 22 Oct 2025 14:11:15 -0400 Subject: [PATCH 4/5] typos :) --- docs/getting_started.rst | 3 +-- docs/inference.rst | 2 +- docs/training.rst | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 7df2ac3..6c339cd 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -5,9 +5,8 @@ Getting Started Learn how to use the full `ufs2arco + Anemoi + wxvx` pipeline. You will learn how to: + 1) Use `ufs2arco` to create training and validation datasets with NOAA Replay reanalysis - - 1 year of data for training and 0.25 years for validation - - 1-degree global data 2) Use `anemoi-core` modules to train a graph-based model 3) Use `anemoi-inference` to run inference 4) Use `wxvx` to verify a forecast diff --git a/docs/inference.rst b/docs/inference.rst index fa53024..ee02810 100644 --- a/docs/inference.rst +++ b/docs/inference.rst @@ -6,4 +6,4 @@ We use the anemoi-inference package to create a forecast. Helpful quick tips for using anemoi-inference -See `anemoi-inference documentation `_documentation for further information: \ No newline at end of file +See `anemoi-inference documentation `_ documentation for further information: \ No newline at end of file diff --git a/docs/training.rst b/docs/training.rst index f1f26b0..899f0af 100644 --- a/docs/training.rst +++ b/docs/training.rst @@ -2,7 +2,7 @@ Train a Graph-Based Model ================= -We use the anemoi-core modules to train a graph-baed model. +We use the anemoi-core modules to train a graph-based model. Helpful quick tips for using Anemoi From c895979b7e7474c764ce6954d04a5bb6ae74af3a Mon Sep 17 00:00:00 2001 From: Mariah Pope Date: Thu, 23 Oct 2025 11:55:59 -0400 Subject: [PATCH 5/5] bring back post processors in graph --- nested_eagle/scientific_workflow/training/config.yaml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/nested_eagle/scientific_workflow/training/config.yaml b/nested_eagle/scientific_workflow/training/config.yaml index 6927e7b..6006081 100644 --- a/nested_eagle/scientific_workflow/training/config.yaml +++ b/nested_eagle/scientific_workflow/training/config.yaml @@ -241,11 +241,9 @@ graph: _target_: anemoi.graphs.edges.attributes.EdgeDirection norm: unit-std - #post_processors: - #- _target_: anemoi.graphs.processors.SortEdgeIndexByTargetNodes - # descending: True # optional, defaults to true -# commenting the post-processors out for right now because I think there may be a bug in Anemoi-Models -# I'll circle back to this at some point. + post_processors: + - _target_: anemoi.graphs.processors.SortEdgeIndexByTargetNodes + descending: True # optional, defaults to true hardware: num_gpus_per_model: 1