How the Icosahedral Mesh GNN Processes Atmospheric Data in WeatherNext

The icosahedral mesh GNN in WeatherNext converts atmospheric data into a hierarchical triangular mesh graph, then applies a typed message‑passing neural network that respects spherical geometry to learn spatio‑temporal weather patterns.

WeatherNext, the open‑source weather forecasting system from Google DeepMind, processes atmospheric data using a graph neural network (GNN) built on an icosahedral mesh—a geodesic tiling of the sphere. This architecture replaces traditional latitude‑longitude grids with a uniform triangular discretization that avoids polar singularities and enables efficient, geometry‑aware learning. The following sections break down exactly how raw atmospheric fields transform into mesh‑based graph features and flow through the GNN pipeline.

Building the Icosahedral Mesh Hierarchy

The foundation of WeatherNext's GNN is a multi‑resolution mesh hierarchy constructed through iterative subdivision of a regular icosahedron. In weathernext/utils/icosahedral_mesh.py, the function get_hierarchy_of_triangular_meshes_for_sphere (or its labeled variant get_hierarchy_of_labeled_triangular_meshes_for_sphere) generates this sequence at lines 998–1034.

Each subdivision splits every triangular face into four smaller triangles, quadrupling the resolution. The splits_list parameter controls the refinement level at each hierarchy layer:

from weathernext.utils.icosahedral_mesh import (
    get_hierarchy_of_labeled_triangular_meshes_for_sphere,
)

meshes = get_hierarchy_of_labeled_triangular_meshes_for_sphere(
    splits_list=[2, 2, 2],          # three refinements → 4× resolution per level

    pole_parallel_faces=True,       # align faces near poles for stability

    finest_mesh_first=False,        # coarse-to-fine ordering

)

The finest mesh (meshes[-1].mesh) serves as the primary computational grid for the GNN.

Converting Meshes to Graphs with Sparse Adjacency

WeatherNext treats the mesh as a directed graph where vertices are nodes and edges encode neighborhood relationships. The conversion happens in faces_to_edges (lines 666–689 in icosahedral_mesh.py), which splits each triangle into three directed edges:

from weathernext.utils.icosahedral_mesh import get_sparse_adjacency_matrix

mesh = meshes[-1].mesh
adjacency = get_sparse_adjacency_matrix(mesh)   # scipy.sparse CSR matrix

For efficient message passing, get_sparse_adjacency_matrix (lines 402–410) assembles these edges into a CSR‑format sparse matrix. This enables constant‑time neighbor lookups and memory‑efficient storage for the typically millions of vertices in high‑resolution forecasts.

Optimizing Memory Locality with Banded Ordering

Message‑passing performance depends heavily on memory access patterns. At lines 412–424, get_permutation_to_banded computes a Reverse Cuthill‑McKee (RCM) ordering that clusters adjacent vertices close together in memory:

# Applied internally within the GNN initialization

permutation = get_permutation_to_banded(adjacency)   # banded matrix structure

This reordering minimizes the bandwidth of the sparse adjacency matrix, improving cache efficiency during the matrix‑vector operations that dominate GNN training and inference.

Sampling Atmospheric Data onto Mesh Vertices

Raw atmospheric variables—temperature, wind components, humidity, geopotential—arrive on irregular latitude‑longitude grids. The utilities in weathernext/utils/data_utils.py interpolate these fields onto the mesh's vertex coordinates:

import xarray as xr
from weathernext.utils.data_utils import sample_to_mesh

# Load ERA5 temperature field

temp = xr.open_dataset("era5_temperature.nc")["t2m"]  # dims: (time, lat, lon)

# Interpolate to mesh vertices → node feature vector

node_features = sample_to_mesh(temp, mesh.vertices)   # shape: (num_vertices,)

Each atmospheric variable becomes one channel of the node feature tensor, with shape (V, C) where V is the number of mesh vertices and C is the number of physical variables.

Typed Graph Neural Network: Message Passing on the Sphere

The core learning engine is TypedGraphNet in weathernext/utils/typed_graph_net.py. Unlike standard GNNs that treat all edges identically, this architecture recognizes edge types—distinguishing between, for example, north‑south, east‑west, and diagonal connections on the mesh:

import jax.numpy as jnp
from weathernext.utils.typed_graph_net import TypedGraphNet

# Initialize GNN: 4 message-passing steps, 64-dimensional hidden states

gnn = TypedGraphNet(num_message_steps=4, hidden_dim=64)

# Prepare inputs: convert CSR to edge list

senders, receivers = adjacency.nonzero()
node_feats = jnp.asarray(node_features)[:, None]   # shape: (V, 1)

# Forward pass through the icosahedral mesh GNN

output = gnn(node_feats, senders, receivers)       # shape: (V, out_dim)

During each message‑passing step, the GNN:

1. Computes messages from each vertex to its neighbors along typed edges, applying learned linear transformations.
2. Aggregates messages at each vertex using permutation‑invariant reductions (typically sum or mean).
3. Updates vertex states by combining aggregated messages with the previous state through a non‑linear activation.

Stacked layers enable information to propagate across the entire sphere—local weather patterns in one region influence distant forecasts through successive neighborhood expansions.

Projecting Forecasts Back to Physical Space

After processing, mesh‑based predictions require conversion back to standard geographic grids for verification and downstream applications. weathernext/utils/mesh_transformer.py provides mesh_to_grid for this inverse mapping:

from weathernext.utils.mesh_transformer import mesh_to_grid

# Convert node embeddings to lat-lon grid for evaluation

forecast_grid = mesh_to_grid(output, mesh)   # shape: (lat, lon, out_dim)

This interpolation completes the pipeline: raw data → mesh sampling → GNN processing → physical forecast.

Complete Pipeline Example

The following runnable example combines all stages for a single atmospheric variable:

from weathernext.utils.icosahedral_mesh import (
    get_hierarchy_of_labeled_triangular_meshes_for_sphere,
    get_sparse_adjacency_matrix,
)
from weathernext.utils.data_utils import sample_to_mesh
from weathernext.utils.typed_graph_net import TypedGraphNet
from weathernext.utils.mesh_transformer import mesh_to_grid
import xarray as xr
import jax.numpy as jnp

# 1. Build mesh hierarchy and select finest level

meshes = get_hierarchy_of_labeled_triangular_meshes_for_sphere(
    splits_list=[2, 2, 2]
)
mesh = meshes[-1].mesh

# 2. Create sparse adjacency matrix

adjacency = get_sparse_adjacency_matrix(mesh)

# 3. Load and sample atmospheric data

temp = xr.open_dataset("era5_temperature.nc")["t2m"]
node_features = sample_to_mesh(temp, mesh.vertices)

# 4. Initialize and run TypedGraphNet

gnn = TypedGraphNet(num_message_steps=4, hidden_dim=64)
senders, receivers = adjacency.nonzero()
node_feats = jnp.asarray(node_features)[:, None]
embeddings = gnn(node_feats, senders, receivers)

# 5. Project back to lat-lon grid

forecast = mesh_to_grid(embeddings, mesh)

Key Source Files for the Icosahedral Mesh GNN

File	Purpose
weathernext/utils/icosahedral_mesh.py	Mesh generation, subdivision, edge creation, sparse adjacency, and banded ordering (functions at lines 402–424, 666–689, 998–1034).
weathernext/utils/typed_graph_net.py	TypedGraphNet class implementing typed message‑passing GNN layers.
weathernext/utils/data_utils.py	sample_to_mesh and related utilities for interpolating atmospheric fields onto mesh vertices.
weathernext/utils/mesh_transformer.py	mesh_to_grid for converting mesh predictions back to regular latitude‑longitude grids.
weathernext/weathernext1_graph/graphcast.py	High‑level forecast model combining the mesh GNN with temporal encoding and autoregressive rollout.

Summary

• Icosahedral meshes provide uniform spherical discretization without polar distortion, constructed via repeated subdivision in get_hierarchy_of_triangular_meshes_for_sphere.
• Graph conversion produces directed edges from triangular faces using faces_to_edges, assembled into efficient CSR sparse adjacency matrices.
• Reverse Cuthill‑McKee ordering in get_permutation_to_banded optimizes memory locality for GNN operations.
• Atmospheric data is interpolated onto mesh vertices through sample_to_mesh, creating node feature tensors.
• TypedGraphNet processes these features through typed message passing, learning distinct transformations for different edge orientations on the mesh.
• Inverse mapping via mesh_to_grid returns forecasts to standard geographic coordinates for evaluation.

Frequently Asked Questions

What advantages does an icosahedral mesh offer over latitude‑longitude grids for weather forecasting?

Latitude‑longitude grids concentrate grid points near the poles, creating numerical instabilities and variable resolution. The icosahedral mesh provides uniform spacing across the entire sphere, eliminating polar singularities and enabling consistent spatial resolution that the GNN can exploit for stable, efficient learning.

Why does WeatherNext use typed edges in its graph neural network?

Typed edges allow the GNN to learn direction‑specific atmospheric dynamics. Weather patterns exhibit different correlations along meridional (north‑south) versus zonal (east‑west) directions; by distinguishing edge types, TypedGraphNet applies specialized transformations that capture these anisotropic relationships more accurately than untyped alternatives.

How does the sparse adjacency matrix improve computational efficiency?

The CSR (Compressed Sparse Row) format stores only nonzero entries of the adjacency matrix, reducing memory usage from O(V²) to O(E) where E is the number of edges. For a typical high‑resolution mesh with millions of vertices but bounded node degree (6 neighbors per vertex), this enables scalable training and inference on accelerators without dense matrix materialization.

Can the icosahedral mesh GNN handle variables at different vertical levels?

Yes. WeatherNext processes multi‑level atmospheric fields by treating each vertical level as an additional feature channel or by constructing three‑dimensional meshes that extend the icosahedral tiling radially outward. The same TypedGraphNet architecture applies, with edge types now distinguishing horizontal from vertical connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}