Process-Based Hydrology Model Adapters
Purpose
P114.6 defines how FEMIC drives user-supplied process-based hydrology models. It provides scenario manifests, runtime probing, adapter boundaries, and a normalized peak-flow/receptor output contract.
FEMIC does not bundle model binaries, model licences, or private data. The
operator supplies the model installation and runtime. All runtimes are
user-supplied. The scenario schema is
femic.hydrology.process_scenario.v1 and the result schema is
femic.hydrology.process_result.v1.
Model Boundaries
The registry covers:
DHSVM
RHESSys
CRHM
SUMMA
HEC-HMS
P114.6 implements executable adapters for DHSVM and SUMMA. The other models are registered boundaries and can be added without changing the scenario or output contract.
Scenario Manifest
A scenario records:
scenario, model, domain, and disturbance-ledger identity;
scenario kind: baseline, treatment, or ensemble;
watershed and receptor IDs;
start/end years and time step;
CRS, flow units, and area units;
climate forcing, land cover, road scenario, harvest scenario, model config, and output paths;
provenance and caveats.
from femic.hydrology.process_models import build_scenario_manifest
manifest = build_scenario_manifest(
scenario_id="dhsvm-treatment-2040",
scenario_name="DHSVM treatment 2040",
model_id="dhsvm",
domain_id="example-domain",
scenario_kind="treatment",
watershed_ids=("w1",),
start_year=2020,
end_year=2040,
time_step_hours=24.0,
crs="EPSG:3005",
climate_forcing_path="climate.csv",
land_cover_path="landcover.gpkg",
road_scenario_path="roads.gpkg",
harvest_scenario_path="harvest.csv",
model_config_path="dhsvm.config",
output_dir="output",
receptor_ids=("r1",),
ledger_id="ledger-1",
)
Runtime Probing
Adapters locate a runtime in this order:
an explicit executable path;
the model-specific environment variable, such as FEMIC_DHSVM_EXE or FEMIC_SUMMA_EXE;
PATH lookup by the default executable name.
Probing never downloads or installs a model.
Implemented Adapters
DHSVM:
<dhsvm> <run-dir>/dhsvm.config
SUMMA:
<summa> -m <run-dir>/fileManager.txt
Use plan_process_model_run to inspect the command without executing it.
Running A Model
from pathlib import Path
from femic.hydrology.process_models import adapter_for_model, run_process_model
result = run_process_model(
adapter_for_model("dhsvm"),
manifest,
Path("runtime/hydrology/dhsvm-treatment-2040"),
executable=Path("/opt/dhsvm/bin/dhsvm"),
timeout_sec=3600,
)
The run directory receives the scenario manifest, stdout/stderr logs, and normalized outputs.
Normalized Outputs
Peak-flow CSV (peak_flows.csv):
year,peak_flow_m3s
2020,10.0
2021,12.5
Receptor metrics CSV (receptor_metrics.csv):
receptor_id,metric,value
r1,peak_flow_m3s,15.0
r1,exceedance_probability,0.1
The result normalizes these into a FloodSample plus a receptor-metric mapping. The adapter may need a model-specific post-processing step before these files exist; P114.6 defines the handoff, not every native output format.
External Runtime And Licensing
Model binaries, executables, and licences are user-supplied.
FEMIC does not distribute DHSVM, RHESSys, CRHM, SUMMA, or HEC-HMS.
Cite and comply with each model’s licence and documentation.
Do not add private or licence-restricted forcing data to tracked files.
Keep large forcing data and model outputs in DataLad/Arbutus, not git.
Limits
Only DHSVM and SUMMA have executable adapters in P114.6.
Native model output conversion may require a reviewed post-processor.
A successful run is not a validated model; calibration and benchmark checks remain P114.9.
FEMIC does not infer or silently transform units, CRS, or time steps.
Hydrologist review is required before operational use.