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.

  • ProcessModelResult Normalized 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: _BaseProcessModelAdapter

DHSVM config-path adapter.

build_command(manifest, run_dir, executable)[source]
Parameters:
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: RuntimeError

Raised 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: object

Scenario 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: Protocol

Protocol for a user-supplied process-model adapter.

build_command(manifest, run_dir, executable)[source]

Build the model command for one run directory.

Parameters:
Return type:

tuple[str, …]

parse_outputs(run_dir, manifest)[source]

Parse normalized peak-flow and receptor outputs.

Parameters:
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:

ProcessModelAvailability

spec: ProcessModelSpec
class femic.hydrology.process_models.ProcessModelAvailability(model_id, available, executable, source, warnings=())[source]

Bases: object

Probe 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
to_dict()[source]

Return the probe as a JSON-serializable mapping.

Return type:

dict[str, object]

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: object

Normalized 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
to_dict()[source]

Return the result as a JSON-serializable mapping.

Return type:

dict[str, object]

warnings: tuple[str, ...] = ()
class femic.hydrology.process_models.ProcessModelRunPlan(model_id, scenario_id, executable, executable_source, command, available, warnings=())[source]

Bases: object

Command 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
to_dict()[source]

Return the plan as a JSON-serializable mapping.

Return type:

dict[str, object]

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: object

External 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
to_dict()[source]

Return the spec as a JSON-serializable mapping.

Return type:

dict[str, object]

class femic.hydrology.process_models.SummaAdapter[source]

Bases: _BaseProcessModelAdapter

SUMMA file-manager adapter.

build_command(manifest, run_dir, executable)[source]
Parameters:
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:

ProcessModelAdapter

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:

HydrologyScenarioManifest

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:

HydrologyScenarioManifest

femic.hydrology.process_models.plan_process_model_run(adapter, manifest, run_dir, *, executable=None)[source]

Plan a process-model run without executing it.

Parameters:
Return type:

ProcessModelRunPlan

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_m3s peak-flow CSV.

Parameters:
  • path (Path)

  • station_id (str)

  • regime (str)

Return type:

FloodSample

femic.hydrology.process_models.read_receptor_metrics(path)[source]

Read a normalized receptor_id,metric,value CSV.

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:
Return type:

ProcessModelResult

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:
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:
Return type:

Path