# Core Components of the WeatherNext Project: Architecture and Implementation

> Discover the core components of the WeatherNext project, including GraphCast, GenCast, and WN2. Explore its architecture, implementation, and modular utilities.

- Repository: [Google DeepMind/weathernext](https://github.com/google-deepmind/weathernext)
- Tags: architecture
- Published: 2026-08-10

---

**The core components of the WeatherNext project include three distinct model families—WeatherNext 1 Graph (GraphCast), WeatherNext 1 Generative (GenCast), and WeatherNext 2 (WN2)—alongside modular utilities for icosahedral mesh processing, sparse transformers, and specialized cyclone tracking.**

The `google-deepmind/weathernext` repository provides a research-grade framework for high-resolution, data-driven weather forecasting built on JAX. Understanding the core components of the WeatherNext project reveals how DeepMind combines graph neural networks, diffusion models, and sparse transformers to predict atmospheric conditions globally. This article examines the source code structure, key modules, and practical implementation patterns found in the official implementation.

## WeatherNext Model Architectures

The framework centers on three primary model implementations that share common mesh-based representations but differ in their predictive mechanisms.

### WeatherNext 2 (WN2) Sparse-Transformer Backbone

The newest generation, implemented in [`weathernext/weathernext2/architecture.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture.py), utilizes a sparse-transformer backbone operating on an icosahedral mesh. This architecture combines learned graph networks with transformer attention mechanisms to predict multiple atmospheric fields simultaneously. Supporting files like [`weathernext/weathernext2/fgn.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/fgn.py) (Flexible Graph Network) and [`weathernext/weathernext2/architecture_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture_utils.py) provide the building blocks for mesh-based feature extraction and multi-scale processing.

### WeatherNext 1 Graph (GraphCast) Message-Passing Network

The first-generation GraphCast model, defined in [`weathernext/weathernext1_graph/graphcast.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext1_graph/graphcast.py), treats Earth's surface as a graph of mesh cells connected via message-passing edges. It employs a Message-Passing Neural Network (MPNN) to propagate atmospheric information across the graph structure, enabling efficient global forecasts at fine spatial resolution. The `GraphCastModel` class encapsulates the full forward pass logic, handling input conditioning and output generation for deterministic weather prediction.

### WeatherNext 1 Generative (GenCast) Diffusion Model

For probabilistic forecasting, [`weathernext/weathernext1_gen/gencast.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext1_gen/gencast.py) implements GenCast as a diffusion-based generative model. The architecture iteratively denoises latent variables on the icosahedral mesh using components defined in [`weathernext/weathernext1_gen/denoiser.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext1_gen/denoiser.py) and [`weathernext/weathernext1_gen/transformer.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext1_gen/transformer.py). The `GenCastModel` class provides sampling methods for generating ensemble forecasts that capture prediction uncertainty through learned denoisers and custom transformer encoder/decoder blocks.

## Core Utilities and Infrastructure

Shared infrastructure components abstract hardware-specific operations and provide reusable primitives for all model families.

### Mesh Handling and Sparse Transformers

The [`weathernext/utils/icosahedral_mesh.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/icosahedral_mesh.py) module defines the geometric primitives for representing Earth as a hierarchical icosahedral mesh. Complementing this, [`weathernext/utils/sparse_transformer.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/sparse_transformer.py) implements attention mechanisms optimized for sparse graph structures, enabling efficient computation on the mesh topology. These utilities ensure model-agnostic support for CPU, GPU, and TPU execution while maintaining distributed training compatibility.

### Data Processing Pipeline

Data ingestion and output formatting are handled by [`weathernext/utils/data_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/data_utils.py) and [`weathernext/utils/model_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/model_utils.py). The `load_dataset()` function converts atmospheric reanalysis data into the icosahedral mesh format required by the models, while `save_forecast()` and `save_ensemble()` handle normalization and NetCDF/xarray conversion. These modules make the core components of the WeatherNext project agnostic to underlying data sources while standardizing the forecast interface.

## Specialized Cyclone Tracking System

The cyclone tracking subsystem extends the framework for tropical cyclone prediction through modules in `weathernext/cyclones/`. The [`direct_tracker.py`](https://github.com/google-deepmind/weathernext/blob/main/direct_tracker.py) file implements `track_cyclones()`, a data-driven tracker that ingests IBTrACS cyclone data via [`ibtracs_processing_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/ibtracs_processing_utils.py) and predicts trajectories and intensities. Base functionality resides in [`tracker_base.py`](https://github.com/google-deepmind/weathernext/blob/main/tracker_base.py), which defines shared interfaces for feature extraction from forecast outputs. This demonstrates how WeatherNext's modular design supports specialized meteorological phenomena beyond general weather prediction.

## Implementation Examples

The following patterns illustrate typical interactions with the WeatherNext core components.

Running GraphCast deterministic forecasts:

```python
from weathernext.weathernext1_graph import graphcast
from weathernext.utils import data_utils, model_utils

# Load reanalysis data onto icosahedral mesh

inputs = data_utils.load_dataset('path/to/reanalysis')

# Initialize GraphCast model

model = graphcast.GraphCastModel(
    mesh=model_utils.get_icosahedral_mesh(),
    hidden_dim=256,
    num_layers=12,
)

# Generate 6-hour forecast

forecast = model(inputs)
data_utils.save_forecast(forecast, 'forecast_6h.nc')

```

Generating probabilistic forecasts with GenCast:

```python
from weathernext.weathernext1_gen import gencast
from weathernext.utils import data_utils, model_utils

# Prepare conditioning data

cond = data_utils.load_dataset('path/to/condition')

# Initialize generative model

generator = gencast.GenCastModel(
    mesh=model_utils.get_icosahedral_mesh(),
    diffusion_steps=1000,
    transformer_cfg={'d_model': 256, 'nhead': 8},
)

# Sample ensemble forecast

samples = generator.sample(cond, num_samples=10)
data_utils.save_ensemble(samples, 'gencast_ensemble.nc')

```

Tracking cyclones on forecast outputs:

```python
from weathernext.cyclones import direct_tracker, ibtracs_processing_utils
from weathernext.utils import data_utils

# Load existing forecast

forecast = data_utils.load_dataset('forecast_6h.nc')

# Extract and track cyclone candidates

tracks = direct_tracker.track_cyclones(forecast)

# Export for visualization

ibtracs_processing_utils.save_tracks(tracks, 'cyclone_tracks.csv')

```

## Summary

- **WeatherNext** comprises three model families: WN2 (sparse-transformer), GraphCast (message-passing graph), and GenCast (diffusion-based generative).
- **Mesh infrastructure** in `weathernext/utils/` provides icosahedral representations and sparse attention primitives shared across all models.
- **Data utilities** standardize input/output processing, converting between atmospheric reanalysis formats and mesh-based tensors.
- **Cyclone tracking** extends the framework via `weathernext/cyclones/` for specialized tropical storm prediction.
- **Modular architecture** allows mixing components (e.g., using `data_utils` with any model variant) while maintaining hardware-agnostic execution.

## Frequently Asked Questions

### What is the difference between WeatherNext 1 and WeatherNext 2?

WeatherNext 1 encompasses two distinct approaches: GraphCast uses deterministic message-passing neural networks for single-trajectory forecasting, while GenCast employs diffusion models for probabilistic ensemble generation. WeatherNext 2 (WN2) represents the next generation, replacing the MPNN backbone with a sparse-transformer architecture that combines graph connectivity with attention mechanisms for improved multi-field prediction.

### How does the icosahedral mesh improve weather forecasting?

The icosahedral mesh, implemented in [`weathernext/utils/icosahedral_mesh.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/icosahedral_mesh.py), approximates Earth's spherical geometry with uniform resolution across the globe. Unlike latitude-longitude grids that cluster points at the poles, the mesh provides consistent spatial sampling that enables efficient graph-based message passing and sparse attention operations required by the WeatherNext models.

### Can WeatherNext components be used independently?

Yes. The utilities in `weathernext/utils/` are model-agnostic, allowing researchers to use `data_utils` for preprocessing or [`sparse_transformer.py`](https://github.com/google-deepmind/weathernext/blob/main/sparse_transformer.py) primitives in custom architectures. Similarly, the cyclone tracker in `weathernext/cyclones/` can process forecasts from external models provided they conform to the expected xarray/NetCDF structure.

### What hardware does WeatherNext support?

According to the source code in `weathernext/utils/`, all core components abstract hardware details through JAX primitives, enabling seamless execution on CPU, GPU, and TPU architectures. The sparse transformer implementations specifically optimize for TPU pod configurations while maintaining compatibility with single-device training.