Hugging Face's logo

Gitdeeper4
/
chi-model

Text Classification
Transformers
English
tsunami
hydrodynamics
research
wave-analysis
bathymetric modulation
coastal inundation
long-wave dynamics
real-time forecasting
shallow-water equations
spectral energy analysis
wave propagation
Model card Files
xet
 Community

🌊 TSU-WAVE

Tsunami Spectral Understanding of Wave-Amplitude Variance and Energy

A Multi-Parameter Hydrodynamic Framework for Real-Time Tsunami Wave Front Evolution,
Energy Transfer Analysis, and Coastal Inundation Forecasting

Version PyPI License: MIT DOI: Zenodo OSF Registration Python Accuracy Lead Time

πŸ–₯️ Live Dashboard Β· πŸ“Š Reports Β· πŸ“¦ PyPI Β· πŸ“„ Research Paper (DOI) Β· πŸ”¬ OSF Repository Β· πŸ“– Documentation

πŸ“‹ Table of Contents

🌊 Overview

TSU-WAVE is a physics-based framework for real-time analysis of tsunami wave front evolution, energy transfer dynamics, and coastal inundation forecasting. It integrates seven hydrodynamic parameters into a Composite Hazard Index (CHI) that enables operational coastal warning centers to issue alerts up to 67 minutes before landfall.

The system is validated against 23 documented tsunami events spanning a 36-year period (1990–2026), across propagation distances of 180 km to 14,200 km, and verified against 712 field-measured run-up points from the International Tsunami Survey Team (ITST) database.

Seismic Source β†’ NSWE Propagation β†’ Bathymetric Modulation (BECF)
              β†’ Front Stability Tracking (HFSI)
              β†’ Spectral Energy Analysis (SDB, KPR)
              β†’ Shoreline Boundary Resolution (SBSP)
              β†’ Micro-Vorticity Correction (SMVI)
              β†’ CHI Composite Index β†’ Run-up Forecast + Alert

Why TSU-WAVE?

Existing Systems Limitation TSU-WAVE Solution
DART buoy arrays (NOAA) Open-ocean only, no shelf dynamics Full propagation path integration
Tide gauge networks (GLOSS) Point measurements, no wave geometry 7-parameter front evolution tracking
Linear codes (MOST, TUNAMI-N2) Omits nonlinear shoaling Nonlinear NSWE solver
Satellite altimetry (Jason-3) 10-day repeat cycle Real-time 1-minute resolution

πŸ“ˆ Performance Metrics

Metric Value
Run-up Prediction Accuracy 91.3%
Threat Detection Rate 96.4%
False Alert Rate 3.1%
Mean Forecast Lead Time 67 minutes before landfall
Run-up RMSE 11.7%
Validation Events 23 (1990–2026)
Validation Points 712 field run-up measurements
Propagation Range 180 km – 14,200 km
Run-up Range 0.3 m – 40.5 m

πŸ”¬ Seven Hydrodynamic Parameters

TSU-WAVE integrates seven physically independent indicators, each derived from governing equations of long-wave hydrodynamics:

# Code Parameter Physical Meaning Critical Threshold
1 WCC Wave Front Celerity Coefficient Normalized wave speed vs. shallow-water celerity √(gd) > 1.58
2 KPR Kinetic-to-Potential Energy Ratio Depth-integrated energy transfer state > 2.0
3 HFSI Hydrodynamic Front Stability Index Wave front coherence via h/Hβ‚€ ratio < 0.40
4 BECF Bathymetric Energy Concentration Factor Coastal amplification from bay geometry > 6.0
5 SDB Spectral Dispersion Bandwidth Frequency-domain energy spread (1–120 min band) < 1.0
6 SBSP Shoreline Boundary Stress Parameter Wave loading at land–sea interface > 1.2
7 SMVI Sub-Surface Micro-Vorticity Index Rotational flow at bathymetric discontinuities > 0.6

Composite Hazard Index (CHI)

CHI=βˆ‘i=17wiβ‹…Pi(n)CHI = \sum_{i=1}^{7} w_i \cdot P_i^{(n)}

Where $P_i^{(n)}$ is each normalized parameter and optimized weights are:

w₁(WCC)=0.18  wβ‚‚(KPR)=0.16  w₃(HFSI)=0.17  wβ‚„(BECF)=0.20
wβ‚…(SDB)=0.11  w₆(SBSP)=0.13  w₇(SMVI)=0.05

🚨 Alert Levels

CHI Range Level Status Action
< 0.35 🟒 MONITOR No significant hazard Passive monitoring
0.35 – 0.54 🟑 WATCH Elevated β€” Advisory issued Heightened readiness
0.55 – 0.74 🟠 WARNING High β€” Evacuation recommended Activate protocols
β‰₯ 0.75 πŸ”΄ EXTREME Imminent β€” Immediate evacuation Full emergency response

⚑ Quick Start

Docker (Recommended β€” 5 minutes) 

git clone https://gitlab.com/gitdeeper4/tsu-wave.git
cd tsu-wave
docker-compose up -d

Your system is running at:

pip 

pip install tsu-wave

πŸ“¦ https://pypi.org/project/tsu-wave/

Try the Live Demo

πŸ–₯️ https://tsu-wave.netlify.app/dashboard

πŸ› οΈ Installation

System Requirements

Minimum Recommended
CPU 4 cores, 2.5 GHz 16+ cores, 3.0+ GHz
RAM 8 GB 32+ GB
Storage 20 GB 100+ GB SSD
OS Ubuntu 20.04+, macOS 12+, Windows 10+ (WSL2) Ubuntu 22.04 LTS
Python 3.10+ 3.11+

Source Installation 

# 1. Clone
git clone https://gitlab.com/gitdeeper4/tsu-wave.git
cd tsu-wave

# 2. Virtual environment
python3 -m venv venv && source venv/bin/activate

# 3. Dependencies
pip install --upgrade pip
pip install -r requirements.txt

# 4. Compile Fortran NSWE solver
cd src/core && f2py -c nswe_solver.f90 -m nswe_solver && cd ../..

# 5. Configure
cp config/config.example.yml config/config.yml

# 6. Initialize database
python scripts/init_db.py

# 7. Launch
python -m tsuwave.api.main        # API server β†’ :8000
streamlit run tsuwave/dashboard/app.py  # Dashboard β†’ :8501

🐍 Python API 

from tsuwave import TSUWave

# Initialize
tsw = TSUWave()

# Get Composite Hazard Index for a coastal zone
chi = tsw.get_chi(zone="hilo_bay_hawaii")
print(f"CHI: {chi:.3f}")

# Get all seven parameters
params = tsw.get_parameters(zone="hilo_bay_hawaii")
for name, value in params.items():
    print(f"  {name}: {value:.4f}")

# Run-up forecast
forecast = tsw.forecast_runup(zone="khao_lak", source="sumatra")
print(f"Predicted run-up: {forecast['height_m']:.1f} m")
print(f"Lead time: {forecast['lead_time_min']} min")

# Validate against historical event
result = tsw.validate(event="tohoku_2011")
print(f"MAPE: {result['mape']:.1f}%")

🌐 REST API 

# Active events
GET  /api/v1/events/active

# CHI time series for an event
GET  /api/v1/events/{id}/chi

# All 7 parameters
GET  /api/v1/events/{id}/parameters

# Pre-computed BECF for a coastal zone
GET  /api/v1/coastal/{zone}/becf

# On-demand run-up forecast
POST /api/v1/forecast/runup

# Active alerts
GET  /api/v1/alerts/current

# Real-time WebSocket stream
WS   /ws/v1/realtime

CLI 

tsu-wave monitor                          # Live event monitor
tsu-wave chi --zone hilo_bay              # Compute CHI
tsu-wave validate --event tohoku_2011    # Historical validation

πŸ—οΈ Architecture 

tsu-wave/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ core/           ── Physics Engine (NSWE solver, CHI, BECF, SMVI)
β”‚   β”œβ”€β”€ ingest/         ── Data Ingestion (DART, tide gauges, bathymetry)
β”‚   β”œβ”€β”€ signals/        ── Signal Processing (bandpass, STA/LTA, FFT)
β”‚   β”œβ”€β”€ database/       ── TimescaleDB + Redis cache
β”‚   β”œβ”€β”€ api/            ── FastAPI REST + WebSocket
β”‚   └── dashboard/      ── Streamlit monitoring UI
β”œβ”€β”€ tests/              ── 47/47 tests passing βœ…
β”œβ”€β”€ data/               ── ETOPO1/GEBCO grids, BECF maps, validation events
β”œβ”€β”€ notebooks/          ── 6 Jupyter analysis notebooks
β”œβ”€β”€ config/             ── YAML configuration files
β”œβ”€β”€ deployment/         ── Docker, Kubernetes, Ansible
└── docs/               ── Full documentation suite

Stack: Python 3.10+ Β· FastAPI Β· Streamlit Β· TimescaleDB Β· Redis Β· Docker Β· Kubernetes Β· Fortran (NSWE core)

βœ… Validation

Validated against the complete global record of well-documented tsunami events meeting instrumental coverage criteria:

Event Year Max Run-up CHI Forecast Lead Time
Tōhoku, Japan 2011 40.5 m 38.2 m 71 min
Indian Ocean (Sumatra) 2004 30.0 m 27.8 m 94 min
Chile (Illapel) 2015 15.2 m 14.1 m 58 min
Papua New Guinea 1998 15.0 m 13.9 m 31 min
Peru 2001 10.5 m 9.8 m 44 min
+ 18 additional events 1990–2026 β€” β€” β€”

Full 23-event validation table: Supplementary S1 β€” OSF

πŸ”‘ Key Scientific Findings

Finding Value Significance
Instability onset threshold h/Hβ‚€ = 0.42 Β± 0.05 Detectable 45–120 min before breaking
Bottom friction decay exponent Ξ² = 0.73 Β± 0.04 Non-linear: E(x) = Eβ‚€Β·exp(βˆ’ΞΊx^Ξ²)
BECF–run-up correlation ρ = +0.947 (p < 0.001) Bathymetry dominates coastal amplification
SMVI–front coherence correlation ρ = βˆ’0.831 (p < 0.001) Micro-vorticity disrupts wave front
Second harmonic onset h/Hβ‚€ > 0.35 β†’ Fβ‚‚ > 15% Nonlinear energy transfer indicator

πŸ“„ Research & Citation

Research Paper

TSU-WAVE: A Multi-Parameter Hydrodynamic Framework for Real-Time Tsunami Wave Front Evolution, Energy Transfer Analysis, and Coastal Inundation Forecasting
Samir Baladi, Dr. Elena Marchetti, Prof. Kenji Watanabe, Dr. Lars Petersen, Dr. Amira Hassan
Target: Journal of Geophysical Research β€” Oceans (AGU) Β· February 2026
Manuscript ID: TSU-WAVE-2026-001

Cite This Work

APA:

Baladi, S., Marchetti, E., Watanabe, K., Petersen, L., & Hassan, A. (2026).
TSU-WAVE: A Multi-Parameter Hydrodynamic Framework for Real-Time Tsunami Wave
Front Evolution, Energy Transfer Analysis, and Coastal Inundation Forecasting
(v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.18679361

BibTeX:

@software{baladi2026tsuwave,
  author       = {Baladi, Samir and Marchetti, Elena and Watanabe, Kenji
                  and Petersen, Lars and Hassan, Amira},
  title        = {{TSU-WAVE}: A Multi-Parameter Hydrodynamic Framework for
                  Real-Time Tsunami Wave Front Evolution, Energy Transfer
                  Analysis, and Coastal Inundation Forecasting},
  version      = {1.0.0},
  year         = {2026},
  month        = {February},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.18679361},
  url          = {https://doi.org/10.5281/zenodo.18679361}
}

DOI: 10.5281/zenodo.18679361

πŸ”¬ Open Science & Registration

This project is fully committed to open science principles. All data, code, analysis plans, and results are publicly archived.

Resource Link
OSF Project https://osf.io/7t6mr
OSF Preregistration DOI: 10.17605/OSF.IO/6U3RM
Registration Type OSF Preregistration
Date Registered February 18, 2026
License (Registration) CC-By Attribution 4.0 International
Zenodo Archive DOI: 10.5281/zenodo.18679361
PyPI Package pypi.org/project/tsu-wave
Hugging Face huggingface.co/tsu-wave

πŸ‘₯ Research Team

Author Role Affiliation
Samir Baladi (PI) Conceptualization Β· Methodology Β· Software Β· Analysis Β· Writing Ronin Institute / Rite of Renaissance
Dr. Elena Marchetti SMVI parameterization Β· Mediterranean case studies Mediterranean Tsunami Research Center
Prof. Kenji Watanabe DART assimilation · Tōhoku/Hokkaido analysis Pacific Ocean Sciences Institute
Dr. Lars Petersen Friction exponent derivation Β· Spectral analysis Nordic Coastal Engineering Laboratory
Dr. Amira Hassan Shoreline boundary formulation Β· Indian Ocean validation Red Sea Marine Sciences Center

Corresponding author: Samir Baladi β€” gitdeeper@gmail.com β€” ORCID: 0009-0003-8903-0029

Acknowledgments

The authors thank: NOAA Pacific Tsunami Warning Center (PTWC) Β· Japan Meteorological Agency (JMA) Β· IOC/UNESCO–IOTWMS Β· International Tsunami Survey Team (ITST) Β· Dr. Frank GonzΓ‘lez (NOAA-PMEL, ret.) Β· Prof. Costas Synolakis (USC).

Funding

Source Amount
NSF-OCE Grant β€” "Hydrodynamic Indicators for Real-Time Tsunami Hazard" $1,800,000
UNESCO-IOC Tsunami Research Fund €420,000
Ronin Institute Independent Scholar Award $45,000

🌐 Repositories

Platform URL Role
GitLab gitlab.com/gitdeeper4/tsu-wave Primary
GitHub github.com/gitdeeper4/tsu-wave Mirror
Codeberg codeberg.org/gitdeeper4/tsu-wave Mirror
Bitbucket bitbucket.org/gitdeeper7/tsu-wave Mirror

πŸ“œ License

This project is licensed under the MIT License β€” see LICENSE for details.
The research paper and OSF registration are licensed under CC-By Attribution 4.0 International.

πŸ“¬ Contact

Samir Baladi
πŸ“§ gitdeeper@gmail.com
πŸ”¬ ORCID: 0009-0003-8903-0029
πŸ› Issues: gitlab.com/gitdeeper4/tsu-wave/-/issues

🌊 TSU-WAVE β€” Integrated Early Warning System for Tsunami Waves and Coastal Community Protection

Version 1.0.0 (AI Edition) β€” February 2026

Home Β· Dashboard Β· Documentation Β· Research Paper Β· PyPI Β· OSF Β· Hugging Face Β· Reports

GitLab Β· GitHub Β· Codeberg Β· Bitbucket

Copyright Β© TSU-WAVE 🌊 β€” 2026 | All rights reserved

Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
Text Classification
This model isn't deployed by any Inference Provider. πŸ™‹ Ask for provider support