Skip to content

Architecture

Salvador Navas edited this page Aug 4, 2026 · 2 revisions

Architecture

pyhydra is organized by domain, not by individual case study. The main package tree is:

pyhydra/
|-- data/                         Pilot-case data downloader
|-- data_sources/                 External hydroclimatic data sources
|   |-- rainfall/
|   |-- river_discharge/
|   |-- climate_change/
|   `-- soils/
|-- climate/
|   |-- time_series/
|   |-- bias_correction/
|   |-- spatial_analysis/
|   |-- stochastic_generation/
|   `-- hybrid_downscaling/
|-- modeling/
|   |-- hydrology/
|   `-- hydraulic/
`-- uq/                           Design reduction, emulability, strategy, stopping

Design Principles

  • Keep reusable scientific operations in importable Python modules.
  • Keep notebooks as examples, tutorials and pilot-case reproductions.
  • Avoid bundling large datasets or third-party model projects in Git.
  • Treat external hydrological/hydraulic engines as adapters, not as internal dependencies.
  • Prefer explicit functions and classes over hidden global configuration.

Package Layers

Layer Package Purpose
Data acquisition pyhydra.data_sources Download/read public rainfall, discharge, soil and climate datasets.
Climate statistics pyhydra.climate.time_series Event extraction, block maxima, POT, GEV/GPD fitting and performance metrics.
Bias correction pyhydra.climate.bias_correction Delta method and quantile-based corrections.
Spatial analysis pyhydra.climate.spatial_analysis RFA, interpolation, copulas and hierarchical GEV models.
Stochastic generation pyhydra.climate.stochastic_generation NSRP/STNSRP and CoSMoS-based generation when optional dependencies exist.
Hybrid downscaling pyhydra.climate.hybrid_downscaling Classification, event selection, reconstruction, map interpolation and return-period maps.
Model adapters pyhydra.modeling Helpers around HEC-HMS, SWAT+, HEC-RAS, SFINCS and flood-map ensembles.
Uncertainty quantification pyhydra.uq MaxDiss design reduction, Voronoi population weighting, cross-validated emulability, the pilot-based strategy rule and a sequential stopping rule.

Public API Style

Many subpackages expose public symbols from their __init__.py, for example:

from pyhydra.climate.time_series import fit_gev, return_levels
from pyhydra.climate.bias_correction import BiasCorrection
from pyhydra.climate.spatial_analysis import regional_return_levels
from pyhydra.modeling.hydrology import write_swatplus_precipitation_files

For advanced or less stable workflows, import from the concrete module:

from pyhydra.modeling.hydraulic.sensitivity import load_sfincs_ensemble

Stability

pyhydra (currently 0.2.0) is research software in active development. The most stable areas are the tested utilities for time-series statistics, event extraction, bias correction, selected data readers, pure file-generation helpers and the pyhydra.uq decision layer. Model execution adapters and workflows involving external services are necessarily more environment-dependent.

Clone this wiki locally