Spaces:

Gitdeeper4
/

tsunami

Sleeping

App Files Files Community

tsunami / README.md

Gitdeeper4

رفع جميع ملفات TSU-WAVE مع YAML

12834b7 about 1 month ago

preview code

raw

history blame contribute delete

17.2 kB

	---
	title: TSU-WAVE Tsunami Dashboard
	emoji: 🌊
	colorFrom: blue
	colorTo: green
	sdk: docker
	sdk_version: "20.10"
	app_file: src/tsuwave/dashboard/app.py
	pinned: false
	tags:
	- tsunami
	- wave-analysis
	- hydrodynamics
	- coastal-engineering
	- disaster-prevention
	- early-warning-system
	- python
	- fastapi
	- streamlit
	- docker
	---
	---
	title: TSU-WAVE Tsunami Dashboard
	emoji: 🌊
	colorFrom: blue
	colorTo: green
	sdk: docker
	sdk_version: "20.10"
	app_file: src/tsuwave/dashboard/app.py
	pinned: false
	tags:
	- tsunami
	- wave-analysis
	- hydrodynamics
	- coastal-engineering
	- disaster-prevention
	- early-warning-system
	- python
	- fastapi
	- streamlit
	- docker
	--------

	<div align="center">

	# 🌊 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)

	</div>

	---

	## 📋 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)

	---

	<div align="center">

	🌊 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

	</div>