ecmwf/anemoi-graphs

Structural Verdict

How Data Flows Through the System

Configuration drives instantiation of node builders and edge builders, which populate a PyTorch Geometric HeteroData graph structure

1. Config Loading — Parse YAML configuration using Hydra and DotDict
2. Node Generation — Instantiate node builders to create spherical tessellation points (config: nodes)
3. Edge Generation — Instantiate edge builders to create connectivity patterns (config: edges)
4. Graph Assembly — Combine nodes and edges into HeteroData structure
5. Serialization — Save graph as PyTorch .pt file

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Control Points

• Resolution Level (env-var) — Controls: Icosahedral refinement depth affecting node density
• K Value (env-var) — Controls: Number of nearest neighbors in KNN edge builders
• Area Mask Radius (threshold) — Controls: Geographic extent of limited area meshes. Default: 100 km
• Earth Radius (runtime-toggle) — Controls: Distance calculations and spherical geometry. Default: 6371.0 km

Technology Stack

Key Components

• GraphCreator (class) — Main orchestrator that builds graphs from YAML configuration using Hydra src/anemoi/graphs/create.py
• KNNEdges (class) — Builds edges between nodes using k-nearest neighbor connectivity src/anemoi/graphs/edges/builder.py
• HexNodes (class) — Creates hexagonal tessellation nodes using H3 library on icosahedron src/anemoi/graphs/nodes/builders/from_refined_icosahedron.py
• create_hex_nodes (function) — Generates hexagonal mesh nodes at specified resolution using H3 library src/anemoi/graphs/generate/hex_icosahedron.py
• create_tri_nodes (function) — Generates triangular mesh nodes from refined icosahedron using trimesh src/anemoi/graphs/generate/tri_icosahedron.py
• KNNAreaMaskBuilder (class) — Creates spatial masks for limiting graph area using k-nearest neighbors src/anemoi/graphs/generate/masks.py
• GraphDescriptor (class) — Analyzes and describes graph structure, sizes, and properties src/anemoi/graphs/describe.py
• directional_edge_features (function) — Computes directional features for edges on spherical surfaces src/anemoi/graphs/edges/directional.py
• ICONTopologicalProcessorEdges (class) — Builds edges using ICON mesh topology for processor-to-processor connections src/anemoi/graphs/edges/builder.py
• BaseEdgeAttribute (class) — Abstract base for computing edge attributes with normalization support src/anemoi/graphs/edges/attributes.py

Science Pipeline

1. Coordinate Generation — Generate lat-lon coordinates from icosahedral tessellation src/anemoi/graphs/generate/hex_icosahedron.py
2. Coordinate Transformation — Convert between Cartesian and spherical coordinates [(N, 3) or (N, 2) → (N, 2) or (N, 3)] src/anemoi/graphs/generate/transforms.py
3. Spatial Indexing — Build KNN index for nearest neighbor searches [(N, 3) → (N, K)] src/anemoi/graphs/edges/builder.py
4. Edge Attribute Computation — Calculate distances and directional features between connected nodes [(E, 2) → (E, F)] src/anemoi/graphs/edges/attributes.py
5. Graph Assembly — Combine nodes and edges into HeteroData structure [various tensors → HeteroData] src/anemoi/graphs/create.py

Assumptions & Constraints

• [warning] Assumes input coordinates are in radians with shape (N, 2) for lat-lon pairs (shape)
• [info] Assumes points have shape (num_points, 3) but assertion only checks second dimension (shape)
• [info] Fixed Earth radius of 6371 km may not be accurate for all use cases or coordinate systems (value-range)
• [warning] Assumes spherical distance calculations are appropriate for all geographic projections (dependency)

Related Weather Climate Repositories

Frequently Asked Questions

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.