TSU-WAVE β€’ COMPLETE DOCUMENTATION

🌊 Documentation

Tsunami Spectral Understanding of Wave-Amplitude Variance and Energy

A physics-based framework for real-time tsunami analysis

Version 1.0.0 91.3% Accuracy 67 min Lead Time 23 Events Validated DOI: 10.5281/zenodo.18679361 OSF: 10.17605/OSF.IO/6U3RM PyPI: tsu-wave

Table of Contents

πŸ“‹ Overview πŸ“ˆ Performance Metrics πŸ”¬ Seven Parameters 🚨 Alert Levels ⚑ Quick Start πŸ› οΈ Installation 🐍 Python API 🌐 REST API πŸ—οΈ Architecture βœ… Validation πŸ”‘ Scientific Findings πŸ“„ Citation πŸ”¬ Open Science πŸ‘₯ Research Team 🌐 Repositories πŸ“œ 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:

1. WCC

Wave Front Celerity Coefficient

Normalized wave speed vs. shallow-water celerity √(gd)

Critical Threshold: > 1.58

2. KPR

Kinetic-to-Potential Energy Ratio

Depth-integrated energy transfer state

Critical Threshold: > 2.0

3. HFSI

Hydrodynamic Front Stability Index

Wave front coherence via h/Hβ‚€ ratio

Critical Threshold: < 0.40

4. BECF

Bathymetric Energy Concentration Factor

Coastal amplification from bay geometry

Critical Threshold: > 6.0

5. SDB

Spectral Dispersion Bandwidth

Frequency-domain energy spread (1–120 min band)

Critical Threshold: < 1.0

6. SBSP

Shoreline Boundary Stress Parameter

Wave loading at land–sea interface

Critical Threshold: > 1.2

7. SMVI

Sub-Surface Micro-Vorticity Index

Rotational flow at bathymetric discontinuities

Critical Threshold: > 0.6

Composite Hazard Index (CHI)

CHI = w₁·WCC* + wβ‚‚Β·KPR* + w₃·HFSI* + wβ‚„Β·BECF* + wβ‚…Β·SDB* + w₆·SBSP* + w₇·SMVI*

Where 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

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

GitLab (primary) GitHub (mirror) Codeberg (mirror) Bitbucket (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