# WeatherNext Example Notebooks: Complete Guide to Running the Official Demos

> Explore WeatherNext example notebooks to run official demos of GraphCast, GenCast, and cyclone tracking. Get started with these end-to-end workflow guides.

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

---

**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.

```bash
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`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture.py). Below is the essential pattern you'll find and adapt.

```python
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`](https://github.com/google-deepmind/weathernext/blob/main/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`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext1_graph/graphcast.py), which defines the **GraphCast** model—a graph neural network operating on spherical meshes.

```python
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`](https://github.com/google-deepmind/weathernext/blob/main/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`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext1_gen/gencast.py) on a reduced dataset:

```python
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`](https://github.com/google-deepmind/weathernext/blob/main/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`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/cyclones/tracker_utils.py) and [`weathernext/cyclones/ibtracs_processing_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/cyclones/ibtracs_processing_utils.py).

```python
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`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext2/architecture.py) | `wn2.FGN` class—model definition, forward pass, loss functions |
| [`weathernext/weathernext1_graph/graphcast.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext1_graph/graphcast.py) | `graphcast.GraphCast` class—graph neural network construction |
| [`weathernext/weathernext1_gen/gencast.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/weathernext1_gen/gencast.py) | `gencast.GenCast` class—diffusion sampling for probabilistic forecasts |
| [`weathernext/utils/data_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/utils/data_utils.py) | Universal helpers: `load_fake_graph_data()`, `load_mini_dataset()`, normalization |
| [`weathernext/cyclones/tracker_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/weathernext/cyclones/tracker_utils.py) | `track_cyclones()`—trajectory extraction from gridded observations |
| [`weathernext/cyclones/ibtracs_processing_utils.py`](https://github.com/google-deepmind/weathernext/blob/main/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`](https://github.com/google-deepmind/weathernext/blob/main/architecture.py), [`graphcast.py`](https://github.com/google-deepmind/weathernext/blob/main/graphcast.py), [`gencast.py`](https://github.com/google-deepmind/weathernext/blob/main/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`](https://github.com/google-deepmind/weathernext/blob/main/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`](https://github.com/google-deepmind/weathernext/blob/main/configs/wn2_fgn.yaml), [`configs/graphcast.yaml`](https://github.com/google-deepmind/weathernext/blob/main/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.