Skip to content

README.md

Latest commit

 

History

History
841 lines (637 loc) · 24.8 KB

README.md

File metadata and controls

841 lines (637 loc) · 24.8 KB

PyDebFlow

Advanced Two-Phase Mass Flow Simulation Software

Open-source debris flow, avalanche & lahar simulation inspired by r.avaflow and RAMMS

Features • Installation • Quick Start • Documentation • Contributing

Stars Build Status Tests Status License Website Release Contributor Covenant

Last Commit Issues Python Versions Code Style PRs Welcome

📋 Table of Contents

🌍 Overview

PyDebFlow is a professional-grade, open-source mass flow simulation tool designed for geoscientists, hazard analysts, and researchers. It simulates the dynamics of:

  • 🏔️ Debris flows - Rapid, gravity-driven flows of saturated debris
  • ❄️ Snow avalanches - Dry and wet snow mass movements
  • 🌋 Volcanic lahars - Volcanic mudflows and debris flows
  • 🪨 Rock avalanches - High-velocity rock mass failures
  • 💧 Hyperconcentrated flows - Sediment-laden flood events

PyDebFlow implements a two-phase (solid + fluid) shallow water model with advanced numerical schemes, making it a powerful replica of established software like r.avaflow and RAMMS.

Why PyDebFlow?

Feature PyDebFlow r.avaflow RAMMS
Open Source ✅ AGPL-3.0 ✅ GPL ❌ Commercial
Two-Phase Flow ✅ ✅ ❌
Python API ✅ Native ❌ GRASS GIS ❌
Modern GUI ✅ PyQt6 ❌ ✅
3D Visualization ✅ PyVista ✅ ParaView ✅
Cross-Platform ✅ Win/Linux ✅ Linux ❌ Windows
Standalone .exe ✅ PyInstaller ❌ ✅

✨ Features

🧮 Numerical Solver

  • NOC-TVD Scheme - Non-Oscillatory Central with Total Variation Diminishing limiters
  • CFL-Adaptive Timestep - Automatic stable timestep calculation
  • Multiple Flux Limiters - Minmod, Superbee, Van Leer
  • Dimensional Splitting - Efficient 2D computation via x/y sweeps
  • Numba JIT Acceleration - Near-C performance with Python simplicity

🔬 Physics Engine

  • Two-Phase Flow Model - Solid granular + viscous fluid phases
  • Multiple Rheology Models:
    • Mohr-Coulomb (dry granular friction)
    • Voellmy-Salm (avalanche standard model)
    • Bingham (viscoplastic mudflows)
    • Herschel-Bulkley (general viscoplastic)
  • Entrainment/Erosion - Bed material incorporation
  • Solid-Fluid Drag - Phase interaction forces
  • Impact Pressure - Hazard assessment calculations

🗺️ Terrain & I/O

  • DEM Formats: GeoTIFF (.tif), ESRI ASCII Grid (.asc), NumPy (.npy)
  • Synthetic Terrain - Built-in slope/channel generators for testing
  • Georeferenced Output - Maintains spatial reference from input DEMs
  • Results Export: NumPy arrays, JSON summaries, raster outputs

🎨 Visualization

  • Premium 3D Viewer - Interactive PyVista/VTK terrain rendering
  • Animated Debris Flow - Time-series flow progression on DEM
  • Video Export - MP4/GIF animation generation
  • Publication-Ready Plots - Matplotlib multi-panel summaries
  • Real-Time Progress - Console progress bars during simulation

🖥️ User Interface

  • Modern PyQt6 GUI - Dark-themed professional desktop application
  • Parameter Presets - Quick setup for debris/snow/lahar scenarios
  • Background Simulation - Non-blocking threaded execution
  • Interactive Controls - Load DEM, configure, run, visualize, export

📦 Distribution

  • Standalone Executable - Single .exe file via PyInstaller
  • No Dependencies - End users don't need Python installed
  • Sample Data - Included test DEMs for immediate use

💾 Installation

Prerequisites

  • Python 3.10, 3.11, or 3.12 (recommended: 3.12)
  • pip package manager
  • Git (for cloning)

Method 1: Install from PyPI (Easiest)

# Basic installation
pip install pydebflow

# With visualization support (3D viewer, animations)
pip install pydebflow[visualization]

# With GUI support
pip install pydebflow[gui]

# Full installation (all features)
pip install pydebflow[all]

Method 2: Quick Install with Scripts

# Clone the repository
git clone https://github.com/ankitdutta428/PyDebFlow.git
cd PyDebFlow

# Run the install script
# On Windows:
scripts\install.bat

# On Linux/macOS:
chmod +x scripts/install.sh
./scripts/install.sh

Method 2: Manual Install

# Clone the repository
git clone https://github.com/ankitdutta428/PyDebFlow.git
cd PyDebFlow

# Create virtual environment (recommended)
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Method 2: Direct Installation

pip install numpy>=1.24.0 numba>=0.57.0 rasterio>=1.3.0 matplotlib>=3.7.0 \
    PyQt6>=6.5.0 scipy>=1.10.0 pyvista>=0.42.0 imageio>=2.31.0 \
    imageio-ffmpeg>=0.4.0 pyyaml>=6.0.0 pytest>=7.4.0

Verify Installation

python -c "import numpy; import numba; print('Core dependencies OK')"
python run_simulation.py --test-all

Optional: Rasterio on Windows

If you encounter issues installing rasterio on Windows:

# Option 1: Use conda
conda install -c conda-forge rasterio

# Option 2: Download wheel from https://www.lfd.uci.edu/~gohlke/pythonlibs/
pip install rasterio-x.x.x-cpXX-cpXX-win_amd64.whl

🚀 Quick Start

Using CLI Scripts (Recommended)

# On Windows:
scripts\run.bat --synthetic-test      # Quick demo simulation
scripts\run.bat --gui                 # Launch GUI

# On Linux/macOS:
./scripts/run.sh --synthetic-test     # Quick demo simulation
./scripts/run.sh --gui                # Launch GUI

Using the pydebflow CLI

# Professional CLI (after installation)
python pydebflow.py simulate --synthetic    # Quick demo
python pydebflow.py gui                     # Launch GUI
python pydebflow.py info                    # System info
python pydebflow.py simulate --dem terrain.tif --time 60 --animate

Direct Python Commands

# Test with synthetic terrain
python run_simulation.py --synthetic-test

# Launch GUI
python main.py

# Run with your DEM file
python run_simulation.py --dem-file your_terrain.tif --t-end 120 --animate-3d

# Export animation video
python run_simulation.py --dem-file terrain.asc --t-end 60 --export-video

📖 Usage

GUI Mode

Launch the graphical interface for an intuitive simulation experience:

python main.py

GUI Features:

  • 📂 Load DEM - Import GeoTIFF or ASCII Grid terrain files
  • ⚙️ Parameter Panel - Configure flow properties, rheology, simulation time
  • 🎯 Presets - Quick-select debris flow, snow avalanche, or lahar settings
  • ▶️ Run Simulation - Execute with real-time progress tracking
  • 🖼️ 3D Visualization - Interactive terrain and flow rendering
  • 💾 Export Results - Save outputs and animation videos

Command Line Interface

Full CLI for scripted/batch simulations:

python run_simulation.py [OPTIONS]

Simulation Options

Option Description Default
--synthetic-test Run with generated terrain -
--dem-file PATH Path to DEM file (.tif, .asc) -
--t-end SECONDS Simulation duration 30.0
--output-dir PATH Results output directory ./output

Release Zone Configuration

Option Description Default
--release-row I Release zone center row Auto
--release-col J Release zone center column Auto
--release-radius N Radius in grid cells 10
--release-height M Initial height in meters 5.0

Visualization Options

Option Description Default
--animate-3d Show interactive 3D animation -
--export-video Export to MP4 video -
--no-viz Disable all visualization -

Testing Options

Option Description
--test-all Run all component tests
--test-flow-model Test flow model only
--test-solver Test NOC-TVD solver only
--test-rheology Test rheology models only
--test-3d Test 3D visualization

Example Commands

# Quick synthetic test
python run_simulation.py --synthetic-test

# Full simulation with 3D viewer
python run_simulation.py --dem-file ./sample_dem.asc --t-end 120 --animate-3d

# Custom release zone
python run_simulation.py --dem-file terrain.tif --release-row 50 --release-col 100 \
    --release-radius 15 --release-height 8.0

# Batch processing (no visualization)
python run_simulation.py --dem-file dem1.tif --t-end 300 --output-dir ./results/run1 --no-viz

# Export animation video
python run_simulation.py --dem-file study_area.asc --t-end 60 --export-video

Python API

Use PyDebFlow as a library in your own scripts:

from src.core.terrain import Terrain
from src.core.flow_model import TwoPhaseFlowModel, FlowState, FlowParameters
from src.core.noc_tvd_solver import NOCTVDSolver, SolverConfig
from src.physics.rheology import Voellmy

# Load terrain
terrain = Terrain.load("your_dem.tif")

# Configure flow parameters
params = FlowParameters(
    solid_density=2500.0,      # kg/m³
    fluid_density=1100.0,      # kg/m³
    basal_friction_angle=22.0, # degrees
    voellmy_mu=0.15,           # Coulomb coefficient
    voellmy_xi=500.0           # Turbulent coefficient (m/s²)
)

# Create model and solver
model = TwoPhaseFlowModel(params)
solver = NOCTVDSolver(terrain, model)

# Initialize release zone
state = FlowState.zeros((terrain.rows, terrain.cols))
release = terrain.create_release_zone(
    center_i=20, center_j=50, radius=10, height=5.0
)
state.h_solid = release * 0.7  # 70% solid
state.h_fluid = release * 0.3  # 30% fluid

# Run simulation
outputs = solver.run_simulation(state, t_end=60.0, output_interval=1.0)

# Process results
for time, flow_state in outputs:
    h_total = flow_state.h_solid + flow_state.h_fluid
    print(f"t={time:.1f}s: max height = {h_total.max():.2f} m")

🔬 Physical Models

Two-Phase Flow Equations

PyDebFlow solves the shallow water equations for a two-phase (solid + fluid) mixture:

Mass Conservation:

∂h_s/∂t + ∂(h_s·u_s)/∂x + ∂(h_s·v_s)/∂y = E_s - D_s
∂h_f/∂t + ∂(h_f·u_f)/∂x + ∂(h_f·v_f)/∂y = E_f - D_f

Momentum Conservation:

∂(h_s·u_s)/∂t + ... = -g·h_s·∂z/∂x - τ_s/ρ_s + F_drag
∂(h_f·u_f)/∂t + ... = -g·h_f·∂z/∂x - τ_f/ρ_f - F_drag

Where:

  • h_s, h_f = solid/fluid flow heights (m)
  • u, v = velocity components (m/s)
  • E, D = erosion/deposition rates (m/s)
  • τ = basal shear stress (Pa)
  • F_drag = solid-fluid drag force

Rheology Models

Mohr-Coulomb (Dry Granular)

τ = μ · σ_n = tan(φ) · ρgh·cos(θ)

Suitable for dry rockslides and granular flows.

Voellmy-Salm (Standard Avalanche Model)

τ = μ · ρgh·cos(θ) + ρg · v² / ξ
  • μ = Coulomb friction coefficient (0.1–0.4)
  • ξ = Turbulent friction coefficient (200–2000 m/s²)

Standard model for snow avalanches (RAMMS, r.avaflow).

Presets:

Preset μ ξ Application
Snow (dry) 0.15 2000 Powder avalanches
Snow (wet) 0.25 1000 Wet slab avalanches
Rock 0.20 500 Rock avalanches
Debris 0.12 400 Debris flows

Bingham (Viscoplastic)

τ = τ_y + η · (v/h)

For mudflows and lahars with yield strength.

Herschel-Bulkley (General Viscoplastic)

τ = τ_y + K · (γ̇)^n

Generalized power-law rheology.

Entrainment Model

Erosion rate based on velocity:

E = e · (v - v_crit)² · (1 - α)

Deposition rate based on concentration:

D = d · α · h / (1 + v²)

📁 Input/Output Formats

Supported Input Formats

Format Extension Description
GeoTIFF .tif, .tiff Standard geospatial raster (requires rasterio)
ESRI ASCII Grid .asc Text-based elevation grid
NumPy Array .npy Native Python array format

ASCII Grid Format Example

ncols         100
nrows         80
xllcorner     500000.0
yllcorner     4000000.0
cellsize      10.0
NODATA_value  -9999
1245.3 1244.8 1244.2 ...
...

Output Files

After simulation, results are saved to the output directory:

File Description
max_height.npy Maximum flow height reached at each cell (m)
max_velocity.npy Maximum velocity at each cell (m/s)
max_pressure.npy Maximum impact pressure (kPa)
final_h_solid.npy Final solid phase height (m)
final_h_fluid.npy Final fluid phase height (m)
final_u.npy Final x-velocity (m/s)
final_v.npy Final y-velocity (m/s)
summary.json Metadata and statistics
results_summary.png Multi-panel visualization
debris_flow.mp4 Animation video (if exported)

📚 Examples

Example 1: Basic Debris Flow Simulation

from src.core.terrain import Terrain
from src.core.flow_model import TwoPhaseFlowModel, FlowState, FlowParameters
from src.core.noc_tvd_solver import NOCTVDSolver

# Create synthetic terrain (25° slope with channel)
terrain = Terrain.create_synthetic_slope(
    rows=100, cols=80, cell_size=10.0,
    slope_angle=25.0, add_channel=True
)

# Standard debris flow parameters
params = FlowParameters(
    solid_density=2600.0,
    fluid_density=1100.0,
    basal_friction_angle=20.0,
    voellmy_mu=0.12,
    voellmy_xi=400.0
)

model = TwoPhaseFlowModel(params)
solver = NOCTVDSolver(terrain, model)

# Initialize 10,000 m³ release
state = FlowState.zeros((100, 80))
release = terrain.create_release_zone(15, 40, 12, 6.0)
state.h_solid = release * 0.65
state.h_fluid = release * 0.35

# Simulate 2 minutes
outputs = solver.run_simulation(state, t_end=120.0)

Example 2: Snow Avalanche with Voellmy Preset

from src.physics.rheology import Voellmy

# Use dry snow avalanche preset
rheology = Voellmy.from_preset('snow_dry')
# Equivalent to: Voellmy(mu=0.15, xi=2000.0)

Example 3: 3D Visualization

from src.visualization.dem_viewer import DEMViewer3D

# Create viewer
viewer = DEMViewer3D(
    elevation=terrain.elevation,
    cell_size=terrain.cell_size,
    vertical_exaggeration=2.0
)

# Load simulation snapshots
snapshots = [state.h_solid + state.h_fluid for _, state in outputs]
times = [t for t, _ in outputs]
viewer.load_snapshots(snapshots, times)

# Show interactive animation
viewer.show_animation("Debris Flow Simulation")

# Or export to video
viewer.export_animation("debris_flow.mp4", fps=15)

🏗️ Architecture

PyDebFlow/
├── main.py                 # GUI entry point
├── run_simulation.py       # CLI entry point
├── build_script.py         # PyInstaller build script
├── requirements.txt        # Python dependencies
├── sample_dem.asc          # Sample ASCII DEM for testing
│
├── src/
│   ├── __init__.py
│   │
│   ├── core/               # Core simulation engine
│   │   ├── flow_model.py       # Two-phase flow model & state
│   │   ├── noc_tvd_solver.py   # NOC-TVD numerical solver
│   │   └── terrain.py          # Terrain/DEM handling
│   │
│   ├── physics/            # Physical models
│   │   ├── rheology.py         # Mohr-Coulomb, Voellmy, Bingham
│   │   └── entrainment.py      # Erosion/deposition models
│   │
│   ├── io/                 # Input/Output
│   │   ├── raster_io.py        # GeoTIFF, ASCII Grid reading
│   │   ├── parameters.py       # Simulation parameters
│   │   └── results.py          # Results export
│   │
│   ├── visualization/      # Visualization
│   │   ├── dem_viewer.py       # 3D PyVista viewer
│   │   └── plot_utils.py       # Matplotlib plotting
│   │
│   └── gui/                # Graphical interface
│       └── main_window.py      # PyQt6 main window
│
├── scripts/                # CLI helper scripts
│   ├── install.sh/.bat         # Installation scripts
│   ├── run.sh/.bat             # Quick simulation runner
│   ├── test.sh/.bat            # Test runner
│   ├── build.sh/.bat           # Build executable
│   └── pydebflow/.bat          # CLI wrapper
│
├── tests/                  # Test suite
│   ├── test_integration.py     # Integration tests
│   ├── test_rheology.py        # Rheology unit tests
│   ├── test_solver.py          # Solver unit tests
│   └── test_scripts.py         # CLI script tests
│
└── .github/
    └── workflows/
        └── tests.yml           # CI/CD pipeline

Module Responsibilities

Module Purpose
core/flow_model.py FlowState, FlowParameters, TwoPhaseFlowModel classes
core/noc_tvd_solver.py NOCTVDSolver with TVD flux limiters
core/terrain.py Terrain class for DEM handling
physics/rheology.py MohrCoulomb, Voellmy, Bingham, HerschelBulkley
physics/entrainment.py EntrainmentModel, McDougallHungr
visualization/dem_viewer.py DEMViewer3D with PyVista
gui/main_window.py MainWindow PyQt6 application

🧪 Testing

Run All Tests

# Using test scripts (recommended)
# On Windows:
scripts\test.bat

# On Linux/macOS:
./scripts/test.sh

# Using pytest directly
python -m pytest tests/ -v

# Using built-in test runner
python run_simulation.py --test-all

Run Specific Test Modules

# Test flow model
python run_simulation.py --test-flow-model

# Test NOC-TVD solver
python run_simulation.py --test-solver

# Test rheology models
python run_simulation.py --test-rheology

# Test 3D visualization
python run_simulation.py --test-3d

Run Tests with Coverage

python -m pytest tests/ --cov=src --cov-report=html
# Open htmlcov/index.html in browser

CI/CD Pipeline

The project includes GitHub Actions workflows that:

  • Run tests on Python 3.10, 3.11, 3.12
  • Test on both Ubuntu and Windows
  • Check code formatting (black, isort)
  • Run linting (flake8)
  • Upload coverage reports

📦 Building Executable

Create a standalone Windows executable:

# Using build scripts (recommended)
# On Windows:
scripts\build.bat

# On Linux/macOS:
./scripts/build.sh

# Or using the build script directly
python build_script.py

This produces:

  • dist/PyDebFlow.exe - Standalone executable (~50-100 MB)
  • dist/sample_config.json - Example configuration
  • dist/README.md - Quick start guide

Manual PyInstaller Build

python -m PyInstaller main.py --name=PyDebFlow --onefile --windowed \
    --add-data "src;src" \
    --hidden-import=numpy --hidden-import=PyQt6

🤝 Contributing

Contributions are welcome! Here's how to get started:

Development Setup

# Fork and clone
git clone https://github.com/ankitdutta428/PyDebFlow.git
cd PyDebFlow

# Use install script (creates venv and installs deps)
# Windows: scripts\install.bat
# Linux/macOS: ./scripts/install.sh

# Or manual setup:
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
pip install black isort flake8 pytest-cov

Code Style

# Format code
black src/ tests/
isort src/ tests/

# Lint
flake8 src/ tests/ --max-line-length=100

Pull Request Process

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (python -m pytest tests/ -v)
  5. Commit changes (git commit -m "Add amazing feature")
  6. Push to branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Areas for Contribution

  • 🌍 Additional DEM formats (NetCDF, HDF5)
  • 🧮 New rheology models (μ(I) rheology)
  • 📊 Enhanced visualization (cross-sections, time series plots)
  • 📝 Documentation improvements
  • 🐛 Bug fixes and optimizations

🙏 Acknowledgments

PyDebFlow is inspired by and draws concepts from:

  • r.avaflow - The open-source GRASS GIS mass flow simulation tool by Martin Mergili et al.
  • RAMMS - The Swiss Federal Institute WSL's rapid mass movement simulation software
  • DAN3D - Dynamic Analysis of Landslides by Oldrich Hungr

Key References

  • Pudasaini, S.P. (2012). A general two-phase debris flow model. Journal of Geophysical Research, 117(F3).
  • Mergili, M., et al. (2017). r.avaflow v1, an advanced open-source computational framework for the propagation and interaction of two-phase mass flows. Geoscientific Model Development, 10(2), 553-569.
  • Voellmy, A. (1955). Über die Zerstörungskraft von Lawinen. Schweizerische Bauzeitung, 73(12).
  • Hungr, O. & McDougall, S. (2009). Two numerical models for landslide dynamic analysis. Computers & Geosciences, 35(5), 978-992.

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

The AGPL-3.0 license ensures that:

  • ✅ You can freely use, modify, and distribute the software
  • ✅ Modified versions must also be open-sourced under AGPL-3.0
  • ✅ If used in a network service, source code must be made available to users
  • ✅ Proper attribution must be maintained

For commercial licensing inquiries, please contact the maintainers.

⭐ Star this repository if PyDebFlow helps your research! ⭐

Made with ❤️ for the geoscience community

📞 Contact & Support

PyDebFlow v0.1.0 • Last updated: January 2026