CranPM Studio end-to-end pipeline schematic

Open-source software · v1.0 · lead author

CranPM Studio

An open-source Python package and live web demo for high-resolution (1 km) PM2.5 forecasting over Europe.

← All projects

CranPM Studio is the open-source software release of CRAN-PM: a multi-scale Vision Transformer that downscales 25 km ERA5/CAMS reanalysis fields to 1 km daily PM2.5 forecasts over Europe, through a cross-resolution attention bridge with wind-guided ordering and an elevation-aware attention bias.

The model reaches RMSE = 6.85 µg/m³ at T+1 against 2,971 EEA ground stations (4.7–10.7% lower than the best deep-learning baseline), and generalises zero-shot to 8 out-of-distribution regions including India, China and the USA.

Beyond accuracy, the package is built for reproducibility and accessibility: a stable Python API and command-line interface, training and inference workflows, dual support for NVIDIA CUDA and AMD ROCm, container images, a HuggingFace model repository, and a Gradio web demonstrator that anyone can run with no setup.

6.85

RMSE µg/m³
T+1, 2971 EEA stations

8

Zero-shot regions
India, China, USA…

1 km

Resolution
daily, across Europe

CUDA
+ROCm

GPU portable
NVIDIA & AMD

What ships in the package

  1. Stable Python API & CLI. Import the model in a notebook or run forecasts from the command line, with documented training and inference workflows.
  2. Dual GPU backends. Runs on NVIDIA CUDA and AMD ROCm, the same code path validated on both vendors (including the LUMI MI250X stack).
  3. Container images. Reproducible environments for HPC and cloud, no dependency hell.
  4. HuggingFace model repository. Pre-trained weights hosted and versioned, downloadable in one line.
  5. Gradio live demo. Pick coordinates anywhere in Europe and a date in 2022; the back-end runs a genuine CRAN-PM forward pass on cached ERA5/CAMS/GHAP inputs and renders the 1 km T+1 forecast, scored against EEA stations. No setup, runs on HuggingFace Spaces.

Try the live demo

Enter any coordinates in Europe, pick a date in the 2022 test year, and get a real 1 km next-day PM2.5 forecast scored against ground stations. Runs in the browser on HuggingFace Spaces (~60 s/inference, free CPU tier).

Open the live demo → CranPM Studio site

Figures

Training and zero-shot domains Training & zero-shot domains Wind-following patch reordering Wind-guided patch ordering (animated) Elevation-aware attention Elevation-aware attention slicer Physics-informed ablations Physics-informed ablations Saharan dust case study Case study: Saharan dust GPU benchmarks CUDA vs ROCm GPU benchmarks: CUDA vs ROCm

Resources

CranPM Studio site Live demo GitHub repo CRAN-PM paper (arXiv) CRAN-PM research page

Credits

Lead author & maintainer
Ammar Kheder (corresponding)
Authors
A. Kheder, W. Peng, H. Toropainen, Z.-S. Liu, M. Boy
Affiliations
LUT University, AMC-Lahti, and INAR (University of Helsinki)
Stack
PyTorch, dual CUDA / ROCm, Docker, HuggingFace Hub & Spaces, Gradio
Status
Open source v1.0 on GitHub

← Back to all projects