--- language : - en license: mit tags: - tsunami - hydrodynamics - research - wave-analysis - bathymetric modulation - coastal inundation - hydrodynamics - long-wave dynamics - real-time forecasting - shallow-water equations - spectral energy analysis - wave propagation library_name: transformers pipeline_tag: text-classification ---
# 🌊 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](https://img.shields.io/badge/version-1.0.0-blue?style=flat-square)](https://gitlab.com/gitdeeper4/tsu-wave/-/releases) [![PyPI](https://img.shields.io/pypi/v/tsu-wave?style=flat-square&color=green)](https://pypi.org/project/tsu-wave/) [![License: MIT](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE) [![DOI: Zenodo](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.18679361-blue?style=flat-square)](https://doi.org/10.5281/zenodo.18679361) [![OSF Registration](https://img.shields.io/badge/OSF-10.17605%2FOSF.IO%2F6U3RM-teal?style=flat-square)](https://osf.io/7t6mr) [![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square)](https://www.python.org/) [![Accuracy](https://img.shields.io/badge/run--up%20accuracy-91.3%25-brightgreen?style=flat-square)](#performance) [![Lead Time](https://img.shields.io/badge/mean%20lead%20time-67%20min-orange?style=flat-square)](#performance) --- **[πŸ–₯️ Live Dashboard](https://tsu-wave.netlify.app/dashboard)** Β· **[πŸ“Š Reports](https://tsu-wave.netlify.app/reports)** Β· **[πŸ“¦ PyPI](https://pypi.org/project/tsu-wave/)** Β· **[πŸ“„ Research Paper (DOI)](https://doi.org/10.5281/zenodo.18679361)** Β· **[πŸ”¬ OSF Repository](https://osf.io/7t6mr)** Β· **[πŸ“– Documentation](https://tsu-wave.netlify.app/documentation)**
--- ## πŸ“‹ Table of Contents - [Overview](#-overview) - [Performance Metrics](#-performance-metrics) - [Seven Hydrodynamic Parameters](#-seven-hydrodynamic-parameters) - [Alert Levels](#-alert-levels) - [Quick Start](#-quick-start) - [Installation](#-installation) - [Python API](#-python-api) - [REST API](#-rest-api) - [Architecture](#-architecture) - [Validation](#-validation) - [Key Scientific Findings](#-key-scientific-findings) - [Research & Citation](#-research--citation) - [Open Science & Registration](#-open-science--registration) - [Research Team](#-research-team) - [Repositories](#-repositories) - [License](#-license) --- ## 🌊 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 = \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) ```bash git clone https://gitlab.com/gitdeeper4/tsu-wave.git cd tsu-wave docker-compose up -d ``` Your system is running at: - **Dashboard**: http://localhost:8080 - **API Docs**: http://localhost:8000/docs ### pip ```bash pip install tsu-wave ``` πŸ“¦ [https://pypi.org/project/tsu-wave/](https://pypi.org/project/tsu-wave/) ### Try the Live Demo πŸ–₯️ [https://tsu-wave.netlify.app/dashboard](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 ```bash # 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 ```python 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 ```bash # 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 ```bash 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](https://osf.io/7t6mr) --- ## πŸ”‘ 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:** ```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`](https://doi.org/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](https://osf.io/7t6mr) | | **OSF Preregistration** | [DOI: 10.17605/OSF.IO/6U3RM](https://osf.io/7t6mr) | | **Registration Type** | OSF Preregistration | | **Date Registered** | February 18, 2026 | | **License (Registration)** | CC-By Attribution 4.0 International | | **Zenodo Archive** | [DOI: 10.5281/zenodo.18679361](https://doi.org/10.5281/zenodo.18679361) | | **PyPI Package** | [pypi.org/project/tsu-wave](https://pypi.org/project/tsu-wave/) | | **Hugging Face** | [huggingface.co/tsu-wave](https://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](https://orcid.org/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](https://gitlab.com/gitdeeper4/tsu-wave) | Primary | | **GitHub** | [github.com/gitdeeper4/tsu-wave](https://github.com/gitdeeper4/tsu-wave) | Mirror | | **Codeberg** | [codeberg.org/gitdeeper4/tsu-wave](https://codeberg.org/gitdeeper4/tsu-wave) | Mirror | | **Bitbucket** | [bitbucket.org/gitdeeper7/tsu-wave](https://bitbucket.org/gitdeeper7/tsu-wave) | Mirror | --- ## πŸ“œ License This project is licensed under the **MIT License** β€” see [LICENSE](LICENSE) for details. The research paper and OSF registration are licensed under **CC-By Attribution 4.0 International**. --- ## πŸ“¬ Contact **Samir Baladi** πŸ“§ [gitdeeper@gmail.com](mailto:gitdeeper@gmail.com) πŸ”¬ [ORCID: 0009-0003-8903-0029](https://orcid.org/0009-0003-8903-0029) πŸ› Issues: [gitlab.com/gitdeeper4/tsu-wave/-/issues](https://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](https://tsu-wave.netlify.app) Β· [Dashboard](https://tsu-wave.netlify.app/dashboard) Β· [Documentation](https://tsu-wave.netlify.app/documentation) Β· [Research Paper](https://doi.org/10.5281/zenodo.18679361) Β· [PyPI](https://pypi.org/project/tsu-wave/) Β· [OSF](https://osf.io/7t6mr) Β· [Hugging Face](https://huggingface.co/tsu-wave) Β· [Reports](https://tsu-wave.netlify.app/reports) [GitLab](https://gitlab.com/gitdeeper4/tsu-wave) Β· [GitHub](https://github.com/gitdeeper4/tsu-wave) Β· [Codeberg](https://codeberg.org/gitdeeper4/tsu-wave) Β· [Bitbucket](https://bitbucket.org/gitdeeper7/tsu-wave) Copyright Β© TSU-WAVE 🌊 β€” 2026 | All rights reserved