---
license: mit
tags:
  - climate
  - super-resolution
  - swin2sr
  - downscaling
  - pytorch
  - fastapi
pipeline_tag: image-to-image
---

# ATMOS — AI Climate Downscaling System

AI-powered 4x super-resolution downscaling of ERA5 temperature reanalysis
data over India. Increases spatial resolution from 0.25° (28 km/px) to
0.0625° (7 km/px) using a Swin2SR ensemble with physics-aware improvements.

## Model

| Component | Detail |
|---|---|
| Architecture | Swin2SR Transformer (ECCV 2022) |
| Ensemble | realworld (BSRGAN-PSNR) + classical (bicubic), averaged |
| Parameters | 12.1M × 2 = 24.2M total, both INT8 quantized |
| Input | ERA5 0.25° (129×121 grid, India) |
| Output | 0.0625° (516×484 grid, 4× SR) |
| Source | caidas/swin2SR on HuggingFace |

## Four Improvements Over Baseline

**1. Ensemble** — Two Swin2SR variants averaged pixel-by-pixel.
The realworld model handles texture; the classical model handles
clean bicubic degradation (closer to ERA5). Their average cancels
each model's noise while preserving genuine fine-scale structure.
Result: sharpness gain doubled from +10.8% to +21.3%.

**2. Physics anomaly pre-processing** — Subtract the ERA5 temporal
mean field before inference, add it back after. The model sees
temperature anomalies (~±2K) rather than absolute values (~250-310K).
This frees the model's attention capacity from reproducing the
large-scale India temperature gradient and focuses it on fine structure.

**3. Elevation lapse rate correction** — Apply a 6.5K/1000m lapse
rate correction post-inference using a DEM proxy derived from the
ERA5 mean field Laplacian. Fixes the known cold bias at Himalayan
and Western Ghats mountain edges. Correction range: -1.09K to +1.67K.

**4. Land-sea mask** — AI enhancement applied only to land pixels.
Ocean pixels (Bay of Bengal, Arabian Sea, Indian Ocean) are passed
through directly from ERA5. Swin2SR has no ocean knowledge and would
hallucinate fine-scale SST structure that doesn't exist physically.
Land: 7651/15609 pixels (49%) in the India bounding box.

## Performance

| Metric | Value |
|---|---|
| Live inference (first call) | ~12,000ms (ensemble × 2 models) |
| Cached inference | ~28ms |
| Sharpness gain vs bilinear | +21.3% |
| PSD gain @ 27km wavelength | +4.58 dB |
| RAM at runtime | ~13-14GB (79-85% of 16.5GB) |
| CPU threads | 12 logical (Ryzen 5 5600H) |

## Data

- **Source**: ERA5 Reanalysis 2020, 2m Temperature (`t2m`)
- **Region**: India (6°N–38°N, 68°E–98°E)
- **Period**: 2020-01-01 to 2020-12-31, hourly (8784 timesteps)
- **File**: `data/raw/era5_real_2020-01-01_2020-12-31.nc`

**Note:** this NetCDF file isn't bundled in this repo. To run ATMOS, bring your own — see below.

## Bringing Your Own Data

This repo ships code only, not the data file. To test it, you need a NetCDF
file matching what the pipeline expects:

- **Source**: ERA5 hourly reanalysis, 2m temperature (`t2m`) — downloadable
  free via the [Copernicus Climate Data Store](https://cds.climate.copernicus.eu/)
- **Region**: India, 6°N to 38°N, 68°E to 98°E
- **Resolution**: 0.25° native ERA5 grid (129×121 points)
- **Path**: save it as `data/raw/era5_real_2020-01-01_2020-12-31.nc` — that
  exact filename is currently hardcoded in `dashboard_backend/main.py`

Using a different region or variable will also need matching changes in
`config/default.yaml` (region bounds) and `dashboard_frontend/index.html`
(the `BOUNDS`/`CENTER` constants), since the land-sea mask and elevation
correction are both built against this specific India grid.

## Usage

```powershell
.\run.bat
```

Opens `http://127.0.0.1:8080` automatically.

**To pre-compute all 8784 frames** (optional, makes every frame instant):
Click the **Build Cache** button in the dashboard bottom bar.
Estimated time: ~2 hrs (2 workers) or ~1 hr (4 workers).
RAM during build: ~85%. CPU: ~90%.

## Project Structure

```
project/
├── dashboard_backend/main.py     FastAPI backend, all 4 improvements
├── dashboard_frontend/index.html ATMOS dashboard (Leaflet, Canvas)
├── src/models/downscaler.py      Swin2SR ensemble + physics + elevation
├── src/models/land_mask.py       Land-sea mask builder
├── src/data/netcdf_loader.py     ERA5 NetCDF loader
├── src/data/preprocessor.py      Z-score normalisation
├── checkpoints/swin2sr/          HuggingFace cached model weights (downloaded on first run, not bundled)
├── data/raw/                     ERA5 NetCDF file
├── serve.py                      Local (Windows) entry point
└── run.bat                       Windows launcher
```

## Hardware Requirements

- RAM: 14GB+ recommended (16GB ideal)
- CPU: 6+ cores (12 logical threads used)
- GPU: Not required (CPU-only, INT8 quantized)
- Python: 3.11+, PyTorch 2.0+