permeabledt Documentation

Digital Twin Tools for Permeable Pavement Water Flow Modeling

Welcome to the comprehensive documentation for PermeableDT, a Python library for permeable pavement digital twin modeling, featuring water flow simulation, genetic algorithm calibration, particle filtering, and weather data acquisition capabilities.

Table of Contents

Getting Started

• Installation Guide
  • Table of Contents
  • Installation Methods
  • Optional Dependencies
  • Virtual Environment Setup
  • Development Installation
  • Verification
  • Troubleshooting
  • Next Steps
• Quick Start Guide
  • Prerequisite
  • 1. Water Flow Simulation
  • 2. Calibration and validation
  • 3. Download Forecast Rainfall (HRRR):
  • 4. Particle Filter
  • Summary
• Data Preparation Guide
  • Table of Contents
  • Data Requirements Overview
  • Setup Files (.ini)
  • Rainfall Data (.dat)
  • Observed Outflow Data (.csv)
  • Particle Filter Data (.ssv)
  • Configuration Files (.toml)

Technical Documentation

• Model Theory and Mathematical Background
  • Table of Contents
  • Model Overview
  • Three-Zone Conceptual Model
  • Mathematical Formulation
  • Governing Equations
  • Numerical Implementation
  • Parameter Definitions
  • Water Balance
  • Model Assumptions
  • Model Validation
  • Mathematical Notation

API Reference

• API Reference
  • Quick reference
  • Typical import pattern
• Core Water Flow API
  • Simulation entry points
  • Parameter utilities
  • Data loading helpers
  • Additional notes
• Calibration API
  • run_calibration(calibration_rainfall, calibration_observed_data, setup_file, output_setup_file=None, logbook_output_path=None, seed=None)
  • calibrate(*args, **kwargs)
• Particle Filtering API
  • PavementModel
  • PipeObs
• Weather Data API
  • HRRRAccumulatedPrecipitationDownloader
• Plotting API
  • plot_rainfall_hydrograph(rainfall_file, outflow_data, rainfall_unit='mm', output_path=None)
  • plot_event_comparison(rainfall_files, observed_files, parameters, rainfall_unit='in', output_folder=None, figure_size=(12, 10), ncols=2)
  • plot_calibration_summary(metrics, output_path=None)

Features Overview

🌊 Water Flow Modeling

Physics-based simulation of permeable pavement systems with three-zone modeling:

• Ponding zone with overflow

• Unsaturated zone with evapotranspiration

• Saturated zone with pipe drainage

🧬 Genetic Algorithm Calibration

Automated parameter optimization using DEAP library:

• Multi-objective optimization

• Parallel processing support

• Comprehensive parameter bounds

📊 Particle Filtering

Real-time state estimation and uncertainty quantification:

• Probabilistic forecasting

• Uncertainty propagation

• Real-time data assimilation

🌦️ Weather Data Integration

HRRR forecast data downloading and processing:

• Automated data retrieval

• Format conversion

• Historical and real-time data

📊 Visualization

Built-in plotting functions for results analysis:

• Rainfall-hydrograph plots

• Calibration convergence

• Particle filter results

Quick Navigation

Topic	Description	Key Files
Installation	Get permeabledt running	installation.md
Basic Usage	Core functionality	quickstart.md
Calibration	Parameter optimization	user_guide/calibration.md
Particle Filter	Real-time forecasting	user_guide/particle_filtering.md
API Reference	Function documentation	api/index.md
Examples	Working code samples	examples/

Getting Help

• 📖 Documentation: You’re reading it!

• 🐛 Issues: GitHub Issues

• 💬 Discussions: GitHub Discussions

• 📧 Email: Contact the development team

License

PermeableDT is released under the MIT License. See LICENSE for details.