README.md

---
license: cc-by-4.0
language:
- en
tags:
- OneScience
- Earth Science
- Storm Surge Modeling
- Random Forest
frameworks: PyTorch
---

<p align="center">
  <strong><span style="font-size: 30px;">GlobalSurgeML</span></strong>
</p>

# Model Introduction

GlobalSurgeML simulates daily maximum storm surge from wind fields, mean sea-level pressure, sea-surface temperature, and precipitation around tide gauges. It applies PCA to reduce multicollinearity in gridded predictors, then uses stepwise multiple linear regression or random forests to map station-level features to daily maximum non-tidal residuals in meters, providing a computationally efficient approach for long-period and large-scale storm-surge simulation.

Paper: Data-Driven Modeling of Global Storm Surges  
https://doi.org/10.3389/fmars.2020.00260

# Model Description

The method was proposed by researchers from the University of Central Florida and Universidad de Cantabria. The paper trained and validated models using GESLA-2 tide gauges, CCMP, 20CRV2c, Microwave OI SST, GPCP, ERA-Interim, and GTSR. It supports daily maximum storm-surge regression at quasi-global tide gauges, extreme-event evaluation, and comparison with the GTSR hydrodynamic reanalysis.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Daily maximum surge simulation | Estimate the daily maximum non-tidal residual from PCA features of meteorological and oceanographic predictors around a station. |
| Lagged forcing | Use 6-hourly inputs and wind/pressure information up to 30 hours before surge occurrence. |
| Method comparison | Compare stepwise linear regression, random forests, remote-sensing inputs, and ERA-Interim inputs across six configurations. |
| ModelScope/OneCode execution | Validate training, inference, evaluation, visualization, and checkpoint workflows in ModelScope or OneCode. |
| Multi-GPU training | Launch distributed data-parallel optimization of the linear models with `torchrun`. |

# Usage Instructions

## 1.OneCode

Experience intelligent, one-click AI4S programming through the OneCode online environment:

[Try intelligent, one-click AI4S programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Download and Installation

```bash
hf download OneScience-Group/GlobalSurgeML --local-dir ./GlobalSurgeML
cd GlobalSurgeML
```

### Environment Dependencies

**Hardware Requirements**

- A GPU or DCU is recommended.
- A CPU can be used for connectivity validation with the default small-sample configuration.
- DCU users must install DTK in advance. DTK 25.04.2 or later, or the OneScience-recommended version matching the current cluster, is recommended.

**DCU Environment**

```bash
# Activate DTK and Conda first
conda create -n onescience311 python=3.11 -y
conda activate onescience311
pip install onescience[earth-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
```

**GPU Environment**

```bash
# Activate Conda first
conda create -n onescience311 python=3.11 -y libstdcxx-ng=12 libgcc-ng=12 gcc_linux-64=12 gxx_linux-64=12
conda activate onescience311
pip install onescience[earth-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
```

### Training Data

This repository uses a small number of synthetic station-day records to validate the engineering workflow.

The synthetic data combines persistent weather states, a seasonal cycle, latitude effects, and nonlinear cyclone forcing to produce correlated features and surge targets rather than unrelated random noise. It preserves the approximate 50/300-dimensional configurations in paper Table 1. The paper also states that local raw grids may contain up to about 5,000 variables and generally retain 300 to 500 PCs at 90% explained variance, so no single fixed raw spatial tensor applies to every station. Synthetic results validate only the core method and engineering workflow; they do not represent the official data distribution or training scale.

```bash
python scripts/fake_data.py
```

### Training

```bash
python scripts/train.py
```

For multi-GPU training, use:

```bash
torchrun --nproc_per_node=8 --nnodes=1 --rdzv_id=1000 --rdzv_backend=c10d --max_restarts=0 --master_addr="localhost" --master_port=29500 scripts/train.py
```

The default engineering configuration preserves all four 50/300-dimensional inputs and the scalar output while reducing the sample count, maximum selected linear features, and random-forest depth. Formal experiments should rerun station-wise PCA, 10-fold cross-validation, and six-configuration majority-metric selection on complete real records.

```text
result/checkpoints/globalsurgeml.pt
result/training/metrics.json
```

### Trained Weights

No weights are bundled under `weight/`. The paper and its supplementary material do not provide a confirmed official model checkpoint. The generated checkpoint uses this independent PyTorch/scikit-learn engineering format and is not claimed to be compatible with external weights.

### Inference

```bash
python scripts/inference.py
```

Inference loads `globalsurgeml.pt`, restores all six configurations, and runs them on the four station-day PCA inputs. The complete numerical output includes six daily maximum surge predictions, observed targets, the GTSR baseline, timestamps, and station coordinates in `result/output/predictions.npz`.

### Evaluation and Visualization

```bash
python scripts/result.py
```

Evaluation follows the paper by computing Pearson correlation, RMSE, NSE, and relative RMSE, separately evaluating extreme surges above the observed 95th percentile and separating tropical from subtropical/extratropical samples by latitude. It saves `result/evaluation/metrics.json` and generates the surge-series and observed-versus-modeled plot `result/evaluation/comparison.png`. Synthetic-data results validate only the engineering workflow and do not represent paper performance on real test data.

# Official OneScience Information

| Platform | OneScience Main Repository | Skills Repository |
| --- | --- | --- |
| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |

# Citation and License

This repository is an independent engineering reproduction of the public GlobalSurgeML paper specifications.

Use of this repository's code, official model weights, and data remains subject to the licenses and terms of their respective projects.