OneScience-Group/GlobalSurgeML

GlobalSurgeML

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

2. Download and Installation

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

# 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

# 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.

python scripts/fake_data.py

Training

python scripts/train.py

For multi-GPU training, use:

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.

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

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

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.