femic.hydrology.process_models Module
The femic.hydrology.process_models module defines FEMIC’s boundary to
user-supplied process-based hydrology models. It builds scenario manifests,
probes external runtimes, constructs commands for DHSVM and SUMMA, executes
models, and normalizes peak-flow and receptor outputs.
FEMIC does not bundle model binaries or model licences.
Start Here If…
Use this page first if you are trying to:
build a process-model scenario manifest;
check whether DHSVM or SUMMA is available;
inspect a model command without running it;
run a user-supplied model and parse normalized outputs; or
add another process-model adapter behind the same contract.
Typical Usage
from pathlib import Path
from femic.hydrology.process_models import (
adapter_for_model,
build_scenario_manifest,
plan_process_model_run,
run_process_model,
)
manifest = build_scenario_manifest(...)
adapter = adapter_for_model("dhsvm")
plan = plan_process_model_run(adapter, manifest, Path("runtime/run"))
result = run_process_model(
adapter,
manifest,
Path("runtime/run"),
executable=Path("/opt/dhsvm/bin/dhsvm"),
timeout_sec=3600,
)
Key Entry Surfaces
build_scenario_manifest()validate_scenario_manifest()write_scenario_manifest()load_scenario_manifest()Build, validate, and persist scenario manifests.process_model_specs()find_process_model_spec()adapter_for_model()Inspect the model registry and resolve implemented adapters.plan_process_model_run()Probe the runtime and return the command without executing it.run_process_model()Execute and normalize outputs.read_peak_flow_series()read_receptor_metrics()Read the normalized output contract.ProcessModelResultNormalized model result.
Cross-References
Process-based hydrology model adapters and scenario manifests.
P114.6 defines how FEMIC drives user-supplied DHSVM, RHESSys, CRHM, SUMMA, and HEC-HMS runtimes. It does not bundle binaries, licences, or private data.
- class femic.hydrology.process_models.DhsvmAdapter[source]
Bases:
_BaseProcessModelAdapterDHSVM config-path adapter.
- build_command(manifest, run_dir, executable)[source]
- Parameters:
manifest (HydrologyScenarioManifest)
run_dir (Path)
executable (str)
- Return type:
tuple[str, …]
- spec: ProcessModelSpec = ProcessModelSpec(model_id='dhsvm', display_name='Distributed Hydrology Soil Vegetation Model', licence='User-supplied DHSVM build and research-model terms.', runtime_kind='binary', default_executable='dhsvm', executable_env_var='FEMIC_DHSVM_EXE', config_filename='dhsvm.config', command_style='config_path', required_inputs=('climate', 'land_cover', 'roads', 'dem'), notes=('DHSVM is commonly used for forest/snow watersheds in BC.',))
- exception femic.hydrology.process_models.HydrologyProcessModelError[source]
Bases:
RuntimeErrorRaised when a process-model scenario, adapter, or run is invalid.
- class femic.hydrology.process_models.HydrologyScenarioManifest(scenario_id, scenario_name, model_id, domain_id, scenario_kind, watershed_ids, start_year, end_year, time_step_hours, crs, climate_forcing_path, land_cover_path, road_scenario_path, harvest_scenario_path, model_config_path, output_dir, receptor_ids=(), ledger_id=None, provenance=<factory>, caveats=(), schema_version='femic.hydrology.process_scenario.v1')[source]
Bases:
objectScenario inputs for one external hydrology model run.
- Parameters:
scenario_id (str)
scenario_name (str)
model_id (str)
domain_id (str)
scenario_kind (str)
watershed_ids (tuple[str, ...])
start_year (int)
end_year (int)
time_step_hours (float)
crs (str)
climate_forcing_path (str)
land_cover_path (str)
road_scenario_path (str)
harvest_scenario_path (str)
model_config_path (str)
output_dir (str)
receptor_ids (tuple[str, ...])
ledger_id (str | None)
provenance (dict[str, object])
caveats (tuple[str, ...])
schema_version (str)
- caveats: tuple[str, ...] = ()
- climate_forcing_path: str
- crs: str
- domain_id: str
- end_year: int
- harvest_scenario_path: str
- land_cover_path: str
- ledger_id: str | None = None
- model_config_path: str
- model_id: str
- output_dir: str
- provenance: dict[str, object]
- receptor_ids: tuple[str, ...] = ()
- road_scenario_path: str
- scenario_id: str
- scenario_kind: str
- scenario_name: str
- schema_version: str = 'femic.hydrology.process_scenario.v1'
- start_year: int
- time_step_hours: float
- to_dict()[source]
Return the scenario manifest as a JSON-serializable mapping.
- Return type:
dict[str, object]
- watershed_ids: tuple[str, ...]
- class femic.hydrology.process_models.ProcessModelAdapter(*args, **kwargs)[source]
Bases:
ProtocolProtocol for a user-supplied process-model adapter.
- build_command(manifest, run_dir, executable)[source]
Build the model command for one run directory.
- Parameters:
manifest (HydrologyScenarioManifest)
run_dir (Path)
executable (str)
- Return type:
tuple[str, …]
- parse_outputs(run_dir, manifest)[source]
Parse normalized peak-flow and receptor outputs.
- Parameters:
run_dir (Path)
manifest (HydrologyScenarioManifest)
- Return type:
tuple[FloodSample, dict[str, dict[str, float]], tuple[str, …]]
- probe(executable=None)[source]
Return whether the model runtime is available.
- Parameters:
executable (Path | None)
- Return type:
- spec: ProcessModelSpec
- class femic.hydrology.process_models.ProcessModelAvailability(model_id, available, executable, source, warnings=())[source]
Bases:
objectProbe result for a user-supplied process-model runtime.
- Parameters:
model_id (str)
available (bool)
executable (str | None)
source (str | None)
warnings (tuple[str, ...])
- available: bool
- executable: str | None
- model_id: str
- source: str | None
- warnings: tuple[str, ...] = ()
- class femic.hydrology.process_models.ProcessModelResult(model_id, scenario_id, command, returncode, peak_series, receptor_metrics, output_files, stdout_path, stderr_path, warnings=(), caveats=(), schema_version='femic.hydrology.process_result.v1')[source]
Bases:
objectNormalized result from one process-model run.
- Parameters:
model_id (str)
scenario_id (str)
command (tuple[str, ...])
returncode (int)
peak_series (FloodSample)
receptor_metrics (dict[str, dict[str, float]])
output_files (tuple[str, ...])
stdout_path (str)
stderr_path (str)
warnings (tuple[str, ...])
caveats (tuple[str, ...])
schema_version (str)
- caveats: tuple[str, ...] = ()
- command: tuple[str, ...]
- model_id: str
- output_files: tuple[str, ...]
- peak_series: FloodSample
- receptor_metrics: dict[str, dict[str, float]]
- returncode: int
- scenario_id: str
- schema_version: str = 'femic.hydrology.process_result.v1'
- stderr_path: str
- stdout_path: str
- warnings: tuple[str, ...] = ()
- class femic.hydrology.process_models.ProcessModelRunPlan(model_id, scenario_id, executable, executable_source, command, available, warnings=())[source]
Bases:
objectCommand and availability for one planned process-model run.
- Parameters:
model_id (str)
scenario_id (str)
executable (str | None)
executable_source (str | None)
command (tuple[str, ...])
available (bool)
warnings (tuple[str, ...])
- available: bool
- command: tuple[str, ...]
- executable: str | None
- executable_source: str | None
- model_id: str
- scenario_id: str
- warnings: tuple[str, ...] = ()
- class femic.hydrology.process_models.ProcessModelSpec(model_id, display_name, licence, runtime_kind, default_executable, executable_env_var, config_filename, command_style, required_inputs=(), notes=())[source]
Bases:
objectExternal process-model boundary metadata.
- Parameters:
model_id (str)
display_name (str)
licence (str)
runtime_kind (str)
default_executable (str)
executable_env_var (str)
config_filename (str)
command_style (str)
required_inputs (tuple[str, ...])
notes (tuple[str, ...])
- command_style: str
- config_filename: str
- default_executable: str
- display_name: str
- executable_env_var: str
- licence: str
- model_id: str
- notes: tuple[str, ...] = ()
- required_inputs: tuple[str, ...] = ()
- runtime_kind: str
- class femic.hydrology.process_models.SummaAdapter[source]
Bases:
_BaseProcessModelAdapterSUMMA file-manager adapter.
- build_command(manifest, run_dir, executable)[source]
- Parameters:
manifest (HydrologyScenarioManifest)
run_dir (Path)
executable (str)
- Return type:
tuple[str, …]
- spec: ProcessModelSpec = ProcessModelSpec(model_id='summa', display_name='Structure for Unifying Multiple Modeling Alternatives', licence='Open-source SUMMA; user-supplied build and runtime.', runtime_kind='binary', default_executable='summa.exe', executable_env_var='FEMIC_SUMMA_EXE', config_filename='fileManager.txt', command_style='file_manager', required_inputs=('climate', 'land_cover', 'roads', 'dem'), notes=('SUMMA uses a file-manager run configuration.',))
- femic.hydrology.process_models.adapter_for_model(model_id)[source]
Return an implemented adapter for a supported process model.
- Parameters:
model_id (str)
- Return type:
- femic.hydrology.process_models.build_scenario_manifest(*, scenario_id, scenario_name, model_id, domain_id, scenario_kind, watershed_ids, start_year, end_year, time_step_hours=24.0, crs='EPSG:3005', climate_forcing_path, land_cover_path, road_scenario_path, harvest_scenario_path, model_config_path, output_dir, receptor_ids=(), ledger_id=None, provenance=None, caveats=())[source]
Build and validate one process-model scenario manifest.
- Parameters:
scenario_id (str)
scenario_name (str)
model_id (str)
domain_id (str)
scenario_kind (str)
watershed_ids (Sequence[str])
start_year (int)
end_year (int)
time_step_hours (float)
crs (str)
climate_forcing_path (str)
land_cover_path (str)
road_scenario_path (str)
harvest_scenario_path (str)
model_config_path (str)
output_dir (str)
receptor_ids (Sequence[str])
ledger_id (str | None)
provenance (Mapping[str, object] | None)
caveats (Sequence[str])
- Return type:
- femic.hydrology.process_models.find_process_model_spec(model_id)[source]
Resolve one process-model spec.
- Parameters:
model_id (str)
- Return type:
ProcessModelSpec | None
- femic.hydrology.process_models.load_scenario_manifest(path)[source]
Load a scenario manifest from JSON.
- Parameters:
path (Path)
- Return type:
- femic.hydrology.process_models.plan_process_model_run(adapter, manifest, run_dir, *, executable=None)[source]
Plan a process-model run without executing it.
- Parameters:
adapter (ProcessModelAdapter)
manifest (HydrologyScenarioManifest)
run_dir (Path)
executable (Path | None)
- Return type:
- femic.hydrology.process_models.process_model_specs()[source]
Return the process-model boundary registry.
- Return type:
tuple[ProcessModelSpec, …]
- femic.hydrology.process_models.read_peak_flow_series(path, *, station_id, regime='unknown')[source]
Read a normalized
year,peak_flow_m3speak-flow CSV.- Parameters:
path (Path)
station_id (str)
regime (str)
- Return type:
- femic.hydrology.process_models.read_receptor_metrics(path)[source]
Read a normalized
receptor_id,metric,valueCSV.- Parameters:
path (Path)
- Return type:
dict[str, dict[str, float]]
- femic.hydrology.process_models.run_process_model(adapter, manifest, run_dir, *, executable=None, timeout_sec=600.0)[source]
Execute a user-supplied process model and parse normalized outputs.
- Parameters:
adapter (ProcessModelAdapter)
manifest (HydrologyScenarioManifest)
run_dir (Path)
executable (Path | None)
timeout_sec (float)
- Return type:
- femic.hydrology.process_models.validate_scenario_manifest(manifest)[source]
Validate a process-model scenario manifest.
- Parameters:
manifest (HydrologyScenarioManifest)
- Return type:
tuple[str, …]
- femic.hydrology.process_models.write_peak_flow_series(sample, path)[source]
Write a normalized peak-flow CSV.
- Parameters:
sample (FloodSample)
path (Path)
- Return type:
Path
- femic.hydrology.process_models.write_receptor_metrics(metrics, path)[source]
Write a normalized receptor-metrics CSV.
- Parameters:
metrics (Mapping[str, Mapping[str, float]])
path (Path)
- Return type:
Path
- femic.hydrology.process_models.write_scenario_manifest(manifest, path)[source]
Write a scenario manifest as JSON.
- Parameters:
manifest (HydrologyScenarioManifest)
path (Path)
- Return type:
Path