GraphCast: Running AI Global Weather Forecasts

Atmospheric researchers, climatologists, and computational scientists use GraphCast to generate skillful 10-day global weather forecasts directly from historical reanalysis data. Developed by Google DeepMind and published in Science, GraphCast operates on Graph Neural Networks (GNNs) to predict hundreds of atmospheric variables at 0.25° resolution in under one minute. This guide details how to install the official JAX framework, ingest ECMWF ERA5 inputs, execute autoregressive forecast rollouts, and analyze multi-level atmospheric outputs within scientific computing workflows.

What it is used for in research

GraphCast provides research institutions with an open-source, machine-learning-based alternative to traditional Numerical Weather Prediction (NWP) systems. Conventional operational weather forecasting relies on supercomputers solving non-linear partial differential equations of fluid dynamics and thermodynamics (such as ECMWF’s High-Resolution Forecast, HRES). GraphCast replaces equation-based grid solvers with a data-driven model trained on 39 years of ECMWF ERA5 historical reanalysis data (1979–2017).

In atmospheric and computational research, GraphCast is applied across four primary domains:

Medium-Range Synoptic Forecasting: Predicting global geopotential height, temperature, specific humidity, and wind vectors across 37 vertical pressure levels (from 1000 hPa up to 1 hPa) out to 240 hours (10 days) at 6-hour intervals.
Severe Weather and Extreme Event Detection: Tracking tropical cyclone trajectories with higher precision and longer lead times than conventional NWP systems, as well as mapping atmospheric rivers and extreme temperature anomalies.
Scientific Machine Learning (SciML) Benchmarking: Serving as a standard baseline for evaluating novel physical inductive biases, neural operator architectures, and data-driven atmospheric simulations.
Climate Sensitivity and Downscaling Experiments: Providing high-speed surrogate model rollouts to evaluate how perturbations in surface boundary conditions influence global circulation patterns.

At its core, GraphCast uses an encode-process-decode architecture implemented on a multi-mesh graph. The spatial domain wraps around the Earth via a refined icosahedral mesh (refinement levels 2 through 6). The encoder maps regular 0.25° latitude-longitude grid points onto the multi-mesh graph; the processor performs 16 layers of message-passing across graph edges to capture long-range atmospheric teleconnections; and the decoder maps latent graph features back onto the 0.25° grid. Incorporating these models into reproducible pipelines aligns with institutional standards for computational reproducibility in scientific computing.

Install or access (official source only)

GraphCast is accessible through two official pathways: Google DeepMind’s open-source repository and the European Centre for Medium-Range Weather Forecasts (ECMWF) ai-models runner. Running GraphCast locally requires a high-performance Linux environment with an NVIDIA GPU supporting CUDA 12 (minimum 32 GB VRAM for 0.25° resolution with 37 pressure levels, or 16 GB VRAM for the smaller 1.0° test checkpoint) or access to Google Cloud TPU accelerators.

Method 1: Direct Installation from Google DeepMind Repository

Install the standalone package using Python 3.10 or higher. Configure a dedicated virtual environment, install the hardware-appropriate JAX accelerator wheels, and fetch the package directly from Google DeepMind’s GitHub repository:

# Create and activate a clean virtual environment
python3 -m venv graphcast-env
source graphcast-env/bin/activate

# Upgrade packaging tools
pip install --upgrade pip setuptools wheel

# Install JAX with CUDA 12 accelerator support
pip install --upgrade "jax[cuda12]" -f https://storage.googleapis.com/jax-releases/jax_cuda_releases.html

# Install GraphCast from official repository archive
pip install --upgrade https://github.com/google-deepmind/graphcast/archive/master.zip

Method 2: Operational Wrapper via ECMWF ai-models

For research teams running operational workflows against Copernicus Climate Data Store (CDS) or MARS archives, ECMWF provides a production plugin:

pip install ai-models ai-models-graphcast

Downloading Official Model Checkpoints

Pretrained neural network parameters are hosted in a public Google Cloud Storage bucket maintained by Google DeepMind (gs://dm_graphcast/params/). Researchers can retrieve the high-resolution 37-level model or the smaller 13-level model using the Google Cloud CLI or Python:

# Download the high-resolution (0.25° resolution, 37 vertical pressure levels) model weights
gcloud storage cp "gs://dm_graphcast/params/GraphCast - ERA5 1979-2017 - resolution 0.25 - pressure levels 37 - mesh 2to6 - precipitation input and output.npz" ./params/

# Or download the smaller 1.0° resolution model (13 vertical levels) for local test runs
gcloud storage cp "gs://dm_graphcast/params/GraphCast_small - ERA5 1979-2015 - resolution 1.0 - pressure levels 13 - mesh 2to5 - precipitation input and output.npz" ./params/

Step-by-step task

This workflow demonstrates loading ERA5 atmospheric initial conditions, instantiating the GraphCast predictor, executing a 10-day forward rollout, and saving the results. To manage large multidimensional datasets systematically across project milestones, teams frequently integrate Data Version Control (DVC) for research datasets and ML pipelines.

Verify JAX Hardware Acceleration: Confirm that JAX detects your CUDA-enabled GPU or TPU device before allocating memory.

import jax
print("Devices detected:", jax.devices())
assert jax.default_backend() in ["gpu", "tpu"], "Accelerator required for GraphCast inference"

Prepare Dual-Timestep ERA5 Inputs: GraphCast requires two consecutive atmospheric states spaced 6 hours apart ($t – 6text{h}$ and $t_0$) to calculate atmospheric tendencies. The input xarray Dataset must contain:
- Upper-air variables at specified pressure levels: temperature (temperature), specific humidity (specific_humidity), geopotential (geopotential), $u$-component of wind (u_component_of_wind), $v$-component of wind (v_component_of_wind), and vertical velocity (vertical_velocity).
- Surface dynamic variables: 2-meter temperature (2m_temperature), 10-meter $u$-wind (10m_u_component_of_wind), 10-meter $v$-wind (10m_v_component_of_wind), mean sea level pressure (mean_sea_level_pressure), and total precipitation (total_precipitation_6hr).
- Static surface variables: land-sea mask (land_sea_mask), surface geopotential (geopotential_at_surface), and top-of-atmosphere incident solar radiation (toa_incident_solar_radiation).

Load Pretrained Weights and Model Architecture:

from graphcast import checkpoint
from graphcast import graphcast
from graphcast import data_utils

# Open the downloaded checkpoint file
with open("params/GraphCast_small - ERA5 1979-2015 - resolution 1.0 - pressure levels 13 - mesh 2to5 - precipitation input and output.npz", "rb") as f:
    ckpt = checkpoint.load(f, graphcast.CheckPoint)

params = ckpt.params
state = {}
model_config = ckpt.model_config
task_config = ckpt.task_config

Instantiate the Predictor and Run Autoregressive Rollout:

from graphcast import rollout

# Build the wrapped predictor function
predictor = graphcast.GraphCast(model_config, task_config)

# Run autoregressive rollout over 40 steps (40 steps × 6 hours = 240 hours / 10 days)
eval_inputs, eval_targets, eval_forcings = data_utils.extract_inputs_targets_forcings(
    eval_dataset, target_lead_times=slice("6h", "240h"), **task_config
)

predictions = rollout.autoregressive_rollout(
    predictor,
    params=params,
    state=state,
    inputs=eval_inputs,
    targets_template=eval_targets * 0,
    forcings=eval_forcings
)

Export Model Forecast to NetCDF: Save the forecasted multi-dimensional trajectories into a standardized format adhering to FAIR data principles for data sharing.
```
predictions.to_netcdf("forecast_graphcast_10day.nc")
print("Forecast successfully generated and saved to forecast_graphcast_10day.nc")
```

Output and how to read it

GraphCast generates an xarray.Dataset containing gridded forecast trajectories across physical coordinate dimensions. Understanding coordinate ordering and physical units is critical for accurate meteorological interpretation:

time: The initial forecast reference timestamp ($t_0$).
lead_time: Forecast horizon coordinates ranging from 6 hours to 240 hours at 6-hour increments (e.g., [6h, 12h, 18h, ..., 240h]).
level: Vertical isobaric pressure levels expressed in hectopascals (hPa) or millibars (e.g., 1000, 925, 850, 700, 500, 300, 200, 50, 1).
lat: Latitude coordinates spaced at 0.25° increments from 90.0°N to -90.0°S (721 coordinate points).
lon: Longitude coordinates spaced at 0.25° increments from 0.0°E to 359.75°E (1440 coordinate points).

The following Python script illustrates how to inspect the generated NetCDF file, extract geopotential height at the 500 hPa level ($Z500$, commonly used to track mid-tropospheric ridges and troughs), and extract surface 2-meter temperature:

import xarray as xr
import numpy as np

# Load generated forecast dataset
ds = xr.open_dataset("forecast_graphcast_10day.nc")

# Inspect variables and dimensions
print(ds.info())

# Extract 500 hPa geopotential at lead time = 72 hours (Day 3 forecast)
# Divide geopotential (m^2 / s^2) by standard gravity (9.80665 m/s^2) to obtain geopotential height (dam or meters)
g = 9.80665
z500 = ds["geopotential"].sel(level=500, lead_time=np.timedelta64(72, "h")) / g

# Extract 2-meter surface temperature and convert from Kelvin to Celsius
t2m = ds["2m_temperature"].sel(lead_time=np.timedelta64(72, "h")) - 273.15

print(f"500 hPa Geopotential Height range: {float(z500.min()):.1f} m to {float(z500.max()):.1f} m")
print(f"2m Temperature range: {float(t2m.min()):.1f} °C to {float(t2m.max()):.1f} °C")

Troubleshooting

When running large-scale graph neural network inference on atmospheric datasets, researchers frequently encounter resource constraints. Consulting with dedicated research software engineering professionals can resolve high-performance computing deployment roadblocks:

CUDA Out-Of-Memory (OOM) During Rollout:
Cause: The 0.25° model with 37 pressure levels tracks 227 variables over 40 autoregressive time steps, requiring substantial GPU memory during graph evaluation.

Solution: Run autoregressive rollouts using jax.lax.scan rather than dynamic Python loops to eliminate tracing overhead. Alternatively, stream intermediate forecast states off GPU memory to system RAM (host memory) at each 6-hour interval using jax.device_get(), or initialize prototype pipelines with the 1.0° resolution model weights.
Dimension Ordering and Coordinate Inversions:
Cause: GraphCast expects latitude coordinates ordered strictly descending from 90° to -90° and longitude ordered ascending from 0° to 359.75°. Passing inverted coordinates causes spatial distortion.

Solution: Reindex ERA5 input arrays using ds.sortby('lat', ascending=False) and ensure longitudes are transformed from $[-180, 180]$ to $[0, 360)$ before passing data to the encoder.
JAX CUDA Library Version Mismatches:
Cause: University HPC clusters frequently have driver versions that do not align with prebuilt JAX CUDA 12 wheels, throwing ptxas fatal: Value 'sm_80' is not supported or cuDNN error.

Solution: Match the installed NVIDIA display driver to the appropriate JAX CUDA release, or execute the official Docker container provided in the Google DeepMind repository where CUDA dependencies and JAX are pre-configured.
Spectral Smoothing at Extended Lead Times:
Cause: GraphCast is trained using Mean Squared Error (MSE) loss. Minimizing MSE over multiple autoregressive steps naturally penalizes high-frequency variance, resulting in slight smoothing of fine-scale precipitation gradients beyond day 7.

Solution: For probabilistic precipitation extremes, use ensemble-based diffusion architectures (such as GenCast) or couple GraphCast synoptic forecasts with local numerical downscaling models.

Free alternatives

Researchers evaluating machine learning weather prediction models have several open-source, data-driven alternatives trained on atmospheric reanalysis data. These complement broader suites of free statistical software for research:

Model	Originating Organization	Neural Architecture	Spatial Resolution	Primary Input	Availability & Licensing
GraphCast	Google DeepMind	Graph Neural Network (Icosahedral Multi-Mesh)	0.25° (37 pressure levels)	ECMWF ERA5 (2 time slices)	Open Source (Apache 2.0 / CC-BY-4.0 weights)
FourCastNet	NVIDIA	Adaptive Fourier Neural Operator (AFNO)	0.25° (surface and upper-air)	ECMWF ERA5 (single time slice)	Open Source (Apache 2.0 on GitHub)
Pangu-Weather	Huawei Cloud	3D Earth-Specific Transformer (3DEST)	0.25° (13 pressure levels)	ECMWF ERA5 (hierarchical lead times)	Open Source code and weights
ClimaX	Microsoft Research	Vision Transformer (ViT) Foundation Model	Variable (5.625° to 1.4°)	CMIP6 Climate Data / ERA5	Open Source (MIT License on GitHub)
ECMWF AIFS	ECMWF	Graph Neural Network on Spherical Mesh	0.25° (operational vertical levels)	ECMWF Operational Analysis	Open Data and model weights

FAQ

How does GraphCast differ from traditional Numerical Weather Prediction?

Traditional Numerical Weather Prediction (NWP) systems solve physical equations governing atmospheric motion, thermodynamics, and radiative transfer on supercomputers, requiring hours of compute time per forecast cycle. GraphCast is a data-driven model trained on historical observations that learns the mapping between consecutive atmospheric states. Once trained, it generates global forecasts in under one minute on a single accelerator while achieving skill scores comparable to or exceeding top operational systems.

What hardware is required to run GraphCast inference?

Running the full 0.25° resolution model with 37 vertical pressure levels requires a high-memory accelerator such as an NVIDIA A100 (40 GB or 80 GB VRAM), NVIDIA H100, or Google Cloud TPU v4. For testing and development, the 1.0° resolution checkpoint with 13 vertical pressure levels can run on standard research workstations equipped with a 16 GB VRAM GPU.

Can GraphCast generate probabilistic ensemble forecasts?

GraphCast is fundamentally a deterministic forecasting model designed to predict the single most likely atmospheric state trajectory. To model uncertainty and produce probabilistic ensemble distributions, researchers run perturbed initial conditions or utilize diffusion-based ensemble models like GenCast.

How does GraphCast handle atmospheric boundaries at the poles?

Traditional latitude-longitude grids suffer from coordinate singularities and severe grid-cell convergence at the North and South Poles. GraphCast avoids polar distortion by mapping latitude-longitude coordinates onto a multi-scale icosahedral graph mesh where node density is quasi-uniform across the entire sphere, allowing unobstructed message-passing across polar regions.

Sources

Lam, R., Sanchez-Gonzalez, A., Willson, M., Wirnsberger, P., Fortunato, M., Alet, F., Ravuri, S., Ewalds, T., Eaton-Rosen, Z., Hu, W., Merose, A., Hoyer, S., Biscaro, C., Davy, P., Shen, X., Zhang, M., Mountain, O., Hall, P., Mohamed, S., and Battaglia, P. “Learning skillful medium-range global weather forecasting.” Science 382, no. 6677 (2023): 1416–1421. DOI: 10.1126/science.adi2336. Verified 2026-11-11.
Google DeepMind GraphCast Codebase and Model Checkpoints. GitHub Repository: https://github.com/google-deepmind/graphcast. Verified 2026-11-11.
European Centre for Medium-Range Weather Forecasts (ECMWF). “ECMWF AI Models Documentation and Benchmarks.” Confluence Documentation: https://confluence.ecmwf.int/display/FCST/AI+Models. Verified 2026-11-11.
ECMWF Lab. ai-models-graphcast: Plugin for ECMWF AI-Models Runner. GitHub Repository: https://github.com/ecmwf-lab/ai-models-graphcast. Verified 2026-11-11.