Skip to content

Modeling Adapters

Salvador Navas edited this page Jul 3, 2026 · 2 revisions

Modeling Adapters

Package: pyhydra.modeling

pyhydra provides helpers around external hydrological and hydraulic models. The external models themselves are not bundled, licensed or installed by pyhydra.

Hydrology

Package: pyhydra.modeling.hydrology

HEC-HMS

Main APIs include:

  • readers for HMS text files: read_gages, read_met, read_basin, read_subbasin, read_control, read_run;
  • file generators: generate_gage, fill_gage, generate_met, generate_met_freq_storm, generate_hms, generate_control, generate_run, generate_py, generate_flow;
  • execution helper: run_hms_script;
  • object-oriented workflow: HMSModel;
  • calibration and parameter utilities: extract_curve_number, calculate_clark_parameters, estimate_muskingum_k, update_basin_file, run_climate_change_scenarios.

HEC-HMS workflows require a local HMS project and compatible HEC-HMS runtime. Result reading is implemented for documented HMS/DSS workflows, but it depends on local DSS libraries and file structure.

SWAT+

Main APIs:

  • write_precipitation_file
  • write_temperature_file
  • write_swatplus_precipitation_files
  • write_swatplus_temperature_files
  • edit_file_cio
  • run_swat
  • read_channel_sd
  • read_swat_discharge

The SWAT+ adapter writes climate input files, edits simulation periods, launches an external SWAT+ executable, and reads back per-channel results (channel_sd_day/mon/yr/aa.txt — flow, sediment and nutrient balances) through read_channel_sd; read_swat_discharge is a convenience wrapper for a single channel's discharge (flo_out, m3/s) time series.

Hydraulic

Package: pyhydra.modeling.hydraulic

HEC-RAS

Main APIs:

  • modify_unsteady_file
  • modify_plan_file
  • modify_project_file
  • create_flow_series
  • run_hec_ras
  • read_ras_dss_timeseries
  • read_ras_max_wsel

The HEC-RAS adapter modifies project input files and can execute HEC-RAS through rascontrol (Windows COM only). read_ras_dss_timeseries reads a named DSS output series (WSEL, FLOW, STAGE, ...) via hecdss; read_ras_max_wsel is a convenience wrapper returning its peak value. There is still no generic reader for 2D spatial results (depth/velocity rasters, .hdf output) — only the scalar/time-series DSS outputs.

SFINCS

Main APIs:

  • setup_sfincs_model
  • run_sfincs

The current module prepares selected SFINCS inputs and runs the external model. Result analysis is handled in flood-ensemble utilities and notebooks rather than through a generic SFINCS output-reader API.

Manning Sensitivity and Flood Ensembles

Main APIs:

  • generate_manning_combinations
  • generate_manning_combinations_correlated
  • build_manning_ensemble
  • load_flood_ensemble
  • load_sfincs_ensemble
  • compute_manning_stats
  • flooded_area
  • spatial_stats
  • manning_flood_regression
  • filter_anomalous_simulations

These utilities support uncertainty analysis of flood maps and Manning roughness ensembles.

Capability Matrix

Model/workflow Prepare inputs Execute model Read/analyse outputs
HEC-HMS Yes Yes, via local runtime/script Available for documented DSS/time-series workflows, environment-dependent
SWAT+ Yes, climate files and file.cio Yes, via external executable Yes, per-channel channel_sd_*.txt (flow, sediment, nutrients)
HEC-RAS Yes, selected plan/unsteady/project edits Yes, via rascontrol DSS time series (WSEL/FLOW/STAGE) via hecdss; no 2D spatial/raster reader
SFINCS Yes, selected model setup helpers Yes, via external executable Ensemble/post-processing helpers, not a generic reader API
Manning ensembles Yes, parameter sampling Uses external hydraulic simulations Yes, for flood-map ensemble statistics

When writing methods sections, use precise wording such as "prepares inputs", "executes through an external model", or "analyses documented outputs", instead of saying all adapters prepare, execute and read results generically.

Clone this wiki locally