# @gaia/graphcast

GraphCast-class **deterministic spherical-GNN** medium-range forecasting (Phase
175.2). A real, trainable PyTorch implementation of the
encoder→processor→decoder architecture on an icosahedral multi-mesh.

| Module        | Phase        | Contents                                                                                                                       |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `mesh`        | 175.2.1.1    | Icosahedral multi-mesh generator (M0→M6, `10·4^L+2` nodes), per-level edge sets, multi-mesh edge union, exact spherical areas. |
| `grid`        | 175.2.1.2/.4 | Grid↔mesh geometry: radius-based grid→mesh bipartite edges and mesh-triangle containment for mesh→grid.                        |
| `layers`      | —            | MLP + interaction-network message passer (edge update → scatter-add aggregation → residual node update).                       |
| `encoder`     | 175.2.1.2    | Grid→Mesh encoder.                                                                                                             |
| `processor`   | 175.2.1.3    | 16-round bidirectional multi-mesh processor.                                                                                   |
| `decoder`     | 175.2.1.4    | Mesh→Grid **residual-tendency** decoder (adds learned Δ to input state).                                                       |
| `model`       | 175.2.1.5    | Assembly + autoregressive rollout (up to 40 × 6 h) with gradient checkpointing for multi-step fine-tuning.                     |
| `loss`        | 175.2.2.4    | cos(lat) area weighting + per-variable + per-level weights; linearly-decayed multi-step rollout loss.                          |
| `diagnostics` | 175.2.2.5    | Energy-conservation drift, zonal power spectrum, blur detector, and automatic early-stop on spectral collapse.                 |
| `ensemble`    | 175.2.2.3    | Reproducible 10-seed/leave-one-fold-out training plans and checkpoint-compatible member aggregation with mean/spread products. |

Training tasks 175.2.2.1–2 (300k-step runs on TPU-v5e/H100 pods reproducing the
published 0.25° skill) require accelerator clusters and the full ERA5 archive
and are **not** locally actionable; the architecture, loss, diagnostics, and
10-member ensemble baseline they would use are implemented and unit-tested here
— including an overfit-a-batch test that proves gradients flow end-to-end.

```bash
cd libs/gaia/graphcast && python3 -m pytest tests/ -q
```