File size: 3,275 Bytes
43db412
 
 
 
 
 
 
de28ff5
43db412
 
 
 
 
 
13ac6d6
43db412
de28ff5
13ac6d6
43db412
13ac6d6
 
2898ec3
a83580d
 
43db412
43a1861
 
 
43db412
13ac6d6
 
 
43db412
13ac6d6
43db412
13ac6d6
 
 
 
 
43db412
13ac6d6
 
 
43db412
13ac6d6
43db412
 
 
 
 
 
 
e79f01b
13ac6d6
43db412
 
13ac6d6
a83580d
 
 
 
 
43db412
 
 
 
 
 
 
 
e79f01b
43a1861
43db412
 
13ac6d6
 
e79f01b
 
43db412
13ac6d6
43db412
44ca953
43db412
13ac6d6
43db412
 
13ac6d6
de28ff5
43db412
6cfdda9
43db412
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
---
license: cc-by-4.0
language:
  - en
library_name: pytorch
tags:
  - ocean-waves
  - wave-prediction
  - flow-matching
  - unstructured-mesh
  - coastal-hazard
  - hong-kong
---

# WaveFlow

**Probabilistic ocean-wave and water-level prediction on unstructured meshes**
· v1.0.0

WaveFlow is a conditional flow-matching model for ensemble prediction of
significant wave height, peak period, mean direction and water level on
unstructured coastal/global meshes, conditioned on atmospheric fields (ERA5
reanalysis for pretraining, IFS ensemble forecasts for prediction) and optional
tide phase.

This repository hosts the three final checkpoints and the mesh/statistics
assets. The model, training loop, sampling code and exact configs are in the
GitHub repository:

- **Code, training and deployment docs**:
  <https://github.com/Leroy-Xiong/WaveFlow>
- **Dataset DOI** (metadata + SHA256): <https://doi.org/10.5281/zenodo.24106732>

## Models

| File | Domain | Variables | Params | Epoch |
|---|---|---|---|---|
| `weights/waveflow-hk-4var-ep49.pt` | Hong Kong waters | Hs, Tp, Dm, water level | 45.7 M | 49 |
| `weights/waveflow-global-hs-ep99.pt` | global ocean | Hs | 465 M | 99 |
| `weights/waveflow-global-4var-ep199.pt` | global ocean | Hs, Tp, Dm, water level | 966 M | 199 |

All checkpoints store the **EMA weights baked into `model_state_dict`**, with
the non-EMA buffers preserved. Load them with
`training.use_ema=false` and `sampling.use_ema_for_sampling=false`.

## Quick start

```bash
git clone https://github.com/Leroy-Xiong/WaveFlow.git
cd WaveFlow
conda env create -f environment.yml
conda activate waveflow

python reproduce.py setup --download       # weights, assets and case forcing
python reproduce.py infer fig3f            # example: global Hs, 10 members
```

For your own inputs, run `main.py --mode sample` with the released config and
checkpoint; `-o sampling.atm_source=ens -o sampling.ens_dir=...` switches to
IFS ENS forecast forcing (see `TRAINING.md` for the per-member file layout).
See the GitHub `README.md` and `WEIGHTS.md` for the exact command, data layout
and GPU requirements. Training/fine-tuning on your own hindcast is documented
in `TRAINING.md`.

## Files and checksums

```
weights/waveflow-hk-4var-ep49.pt                 183.1 MB
weights/waveflow-global-hs-ep99.pt             1,881.0 MB
weights/waveflow-global-4var-ep199.pt          3,883.3 MB
assets.tar.gz                                     22.1 MB
forcing/waveflow-v1.0.0-forcing-cases.tar.gz       234 MB
MANIFEST.json / SHA256SUMS
```

Verify with `sha256sum -c SHA256SUMS`. `assets.tar.gz` restores the mesh
coordinates, patch clusters, normalization statistics and ocean boundary under
`data/`; the forcing archive restores the ERA5 case slices and the Ragasa IFS ENS
members used by the released recipes.

## Licence and citation

Weights: **CC BY 4.0**. Code: **MIT**. Third-party assets retain their own licences (see `THIRD_PARTY.md`).

If you use WaveFlow, please cite the manuscript and the dataset record:

```bibtex
@misc{waveflow2026,
  title  = {WaveFlow: probabilistic ocean-wave and water-level prediction on unstructured meshes},
  year   = {2026},
  doi    = {10.5281/zenodo.24106732},
  url    = {https://github.com/Leroy-Xiong/WaveFlow}
}
```