WeatherNext Example Notebooks: Complete Guide to Running the Official Demos

WeatherNext provides five ready-to-run Jupyter notebooks located in the docs/ folder that demonstrate end-to-end workflows for WeatherNext 2, GraphCast, GenCast, and cyclone tracking.

Google DeepMind's WeatherNext repository ships with fully self-contained example notebooks designed to get you running forecasts within minutes. These notebooks import the weathernext package directly, handle data preparation through built-in utilities, and visualize results with Matplotlib and Cartopy. This guide walks through each notebook's purpose, key code patterns, and how to launch them locally or on cloud infrastructure.

---

Where to Find the WeatherNext Example Notebooks

All official notebooks live inside the docs/ directory of the repository, organized by model family. You can browse them directly on GitHub or clone the repository for local execution.

Notebook Locations and Purposes

Model Family	Notebook Path	What It Demonstrates
WeatherNext 2 (WN2)	docs/weathernext2/wn2_demo.ipynb	End-to-end inference with the second-generation FGN model: data loading, model instantiation, prediction, and field visualization
GraphCast (WeatherNext 1 Graph)	docs/weathernext1_graph/graphcast_demo.ipynb	Graph neural network forecasts on sample data, with skill metric evaluation
GenCast (CPU-friendly)	docs/weathernext1_gen/gencast_mini_demo.ipynb	Lightweight generative forecasting on a minimal dataset that runs without GPU
GenCast (Cloud VM)	docs/weathernext1_gen/gencast_demo_cloud_vm.ipynb	Production deployment on Google Cloud VM: provisioning, data preparation, and execution
Cyclone Tracking	docs/cyclones/demo_gridding_and_tracking.ipynb	Gridding raw observations, trajectory tracking, and visualization with tracker_utils

Each notebook includes !pip install cells for optional dependencies—tensorflow, xarray, cartopy—ensuring they function in fresh environments without manual setup.

---

How to Run the WeatherNext Example Notebooks Locally

The fastest path to running these notebooks requires cloning the repository, installing the package in editable mode, and launching Jupyter.

git clone https://github.com/google-deepmind/weathernext.git
cd weathernext
pip install -e .                    # installs the weathernext package

jupyter lab docs/weathernext2/wn2_demo.ipynb   # substitute any notebook path

The -e . flag installs the package in development mode, allowing imports like import weathernext.weathernext2 as wn2 to resolve correctly from the notebook's working directory.

---

WeatherNext 2 Demo: Core Code Patterns

The wn2_demo.ipynb notebook showcases the FGN (Forecast Generative Network) architecture defined in weathernext/weathernext2/architecture.py. Below is the essential pattern you'll find and adapt.

import weathernext.weathernext2 as wn2
import xarray as xr

# Load sample test case (small netCDF bundled with notebook)

ds = xr.open_dataset("sample_test_case.nc")

# Initialize model from YAML configuration

model = wn2.FGN(config_path="configs/wn2_fgn.yaml")

# Run inference: returns (time, lat, lon, variables) array

forecast = model.predict(ds)

# Visualize predicted temperature field

import matplotlib.pyplot as plt
forecast.temperature.isel(time=0).plot()
plt.title("Predicted Temperature (t+0)")
plt.show()

The FGN class in architecture.py implements the forward pass, loss computation, and training utilities. The notebook demonstrates inference-only usage; extending to fine-tuning requires importing the training loop from the same module.

---

GraphCast Demo: Graph Neural Network Forecasting

The graphcast_demo.ipynb notebook imports from weathernext/weathernext1_graph/graphcast.py, which defines the GraphCast model—a graph neural network operating on spherical meshes.

from weathernext.weathernext1_graph import graphcast
import weathernext.utils.data_utils as du

# Load synthetic graph-structured data provided in notebook

inputs = du.load_fake_graph_data()

# Build model from config

model = graphcast.GraphCast(config_path="configs/graphcast.yaml")
outputs = model(inputs)

# Plot geopotential height predictions

import matplotlib.pyplot as plt
outputs.geopotential_height.isel(time=0).plot()
plt.show()

Key helper functions reside in weathernext/utils/data_utils.py, which handles normalization, batching, and format conversion across all WeatherNext model families.

---

GenCast Demos: Generative Forecasting at Two Scales

WeatherNext provides two GenCast notebooks targeting different compute environments.

Mini Demo (CPU-Friendly)

The gencast_mini_demo.ipynb runs the diffusion-based generative model from weathernext/weathernext1_gen/gencast.py on a reduced dataset:

from weathernext.weathernext1_gen import gencast
import weathernext.utils.data_utils as du

# Minimal data loading for rapid experimentation

inputs = du.load_mini_dataset()   # ~100 MB, CPU memory resident

model = gencast.GenCast(config_path="configs/gencast_mini.yaml")
samples = model.sample(inputs, num_samples=4)  # probabilistic forecasts

Cloud VM Demo

The gencast_demo_cloud_vm.ipynb provides infrastructure-as-code patterns for Google Cloud deployment, covering:

• VM provisioning with appropriate GPU attachmen
• Bulk data preparation using weathernext.utils.data_utils
• Distributed sampling with the full GenCast checkpoint

Both notebooks rely on gencast.py, which implements diffusion-based sampling and conditioning on input atmospheric fields.

---

Cyclone Tracking Demo: Specialized Post-Processing

The demo_gridding_and_tracking.ipynb demonstrates utilities in weathernext/cyclones/tracker_utils.py and weathernext/cyclones/ibtracs_processing_utils.py.

from weathernext.cyclones.tracker_utils import track_cyclones
import weathernext.cyclones.ibtracs_processing_utils as ib

# Load IBTrACS sample (CSV format, included in repository)

cyclone_df = ib.load_ibtracs_csv("ibtracs_sample.csv")

# Run tracking algorithm

tracks = track_cyclones(cyclone_df)

# Visualize with Cartopy projection

import cartopy.crs as ccrs
import matplotlib.pyplot as plt

fig = plt.figure()
ax = plt.axes(projection=ccrs.PlateCarree())
ax.coastlines()
ax.plot(tracks.lon, tracks.lat, "-o", transform=ccrs.PlateCarree())
plt.title("Tracked Cyclone Path")
plt.show()

This workflow converts irregular cyclone observations into gridded trajectory data, enabling statistical analysis of forecast skill for tropical cyclone intensity and track prediction.

---

Key Source Files Referenced in the Notebooks

Understanding these underlying modules helps extend the notebook workflows:

File	Role in Notebooks
weathernext/weathernext2/architecture.py	wn2.FGN class—model definition, forward pass, loss functions
weathernext/weathernext1_graph/graphcast.py	graphcast.GraphCast class—graph neural network construction
weathernext/weathernext1_gen/gencast.py	gencast.GenCast class—diffusion sampling for probabilistic forecasts
weathernext/utils/data_utils.py	Universal helpers: load_fake_graph_data(), load_mini_dataset(), normalization
weathernext/cyclones/tracker_utils.py	track_cyclones()—trajectory extraction from gridded observations
weathernext/cyclones/ibtracs_processing_utils.py	load_ibtracs_csv()—IBTrACS format ingestion

These files form the API surface that all notebooks exercise; reading their docstrings (accessible via help(wn2.FGN) in any notebook) reveals additional configuration options.

---

Summary

• WeatherNext example notebooks live in docs/ with five specialized demos covering WN2, GraphCast, GenCast (two scales), and cyclone tracking.
• Launch locally via git clone, pip install -e ., and jupyter lab—no additional setup required beyond optional dependency cells in each notebook.
• Core patterns involve importing model classes (e.g., wn2.FGN, graphcast.GraphCast), loading data through weathernext.utils.data_utils, and visualizing with standard scientific Python tools.
• Extend workflows by consulting the underlying source files—architecture.py, graphcast.py, gencast.py—which define all configurable parameters the notebooks expose.

---

Frequently Asked Questions

Does WeatherNext include example data with the notebooks?

Yes. Each notebook bundles minimal sample data—netCDF files for atmospheric fields, synthetic graph data, IBTrACS CSV subsets—sufficient to execute all cells without external downloads. The weathernext.utils.data_utils module provides loaders for these bundled datasets.

Can I run the WeatherNext notebooks without a GPU?

Three of five notebooks run comfortably on CPU: gencast_mini_demo.ipynb, demo_gridding_and_tracking.ipynb, and wn2_demo.ipynb (with reduced batch sizes). The GraphCast demo and full GenCast cloud demo expect GPU acceleration for reasonable iteration times.

How do I adapt a notebook to my own weather data?

Replace the xr.open_dataset() or utility loader calls with your data source, then ensure variable names match the expected input schema—temperature, geopotential_height, u_component_of_wind, etc. The data_utils.py normalization functions accept custom statistics via their mean and std parameters.

Where are the notebook configuration files stored?

YAML configs referenced in notebooks (e.g., configs/wn2_fgn.yaml, configs/graphcast.yaml) reside in repository subdirectories corresponding to each model family. These specify architecture hyperparameters, checkpoint paths, and inference settings that the notebook model classes consume at initialization.

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