Data Loading Architecture#

This section documents how the project and runtime layers decide which data families must be active and where concrete data objects are stored for downstream use.

Open it when you want:

  • the split between planning-time activation and runtime loading;

  • the transfer points between loaded data, domain objects, and the Project runtime state;

  • the code path from [data] config to consumed runtime payloads.

Code map#

  • hydromodpy/data/planner.py and plan.py: activation inference and immutable plan creation.

  • hydromodpy/data/runtime_loader.py: data-family dispatch during Project.load_data().

  • hydromodpy/data/data_managers.py: loaded-data container published to runtime state.

  • hydromodpy/project/facade.py: orchestration of setup_workspace / build_geographic / load_data.

  • hydromodpy/physics/flow/structure_binders.py: example downstream consumer that expects transferred structures.

Class diagram: definition and transfer#

This static view documents the collaboration that defines which data must be prepared, then transfers those data objects to the runtime state where they are consumed.

It focuses on:

  • data-type inference and normalization (DataPlanner -> DataLoadPlan);

  • transfer of resolved data types into the project runtime state;

  • setup-time transfer for geology (GeologyField -> Domain.set_zone);

  • data-phase transfer for hydrometry (StationSet -> Project.loaded_data.hydrometry).

@startuml title Data Definition And Transfer - Class Diagram package "hydromodpy" { class Project { +cfg: HydroModPyConfig +data_plan: DataLoadPlan +run_state: ProjectRunState +setup_workspace() +build_geographic() +load_data() +_apply_structural_updates_from_data() } } package "hydromodpy.core.state" { class ProjectRunState { +raw_toml: dict +data_plan: DataLoadPlan +setup: SetupContext +loaded_data: LoadedDataContext } class SetupContext { +domain +flow } class LoadedDataContext { +geology +oceanic +climatic +hydrometry } } package "hydromodpy.data" { class DataPlanner { +build(config, domain_zone_ids, raw_toml, flow_active_bc) } class DataLoadPlan { +types: tuple[str, ...] +inferred_types: tuple[str, ...] +reasons_by_type } class DataManagersRuntimeLoader { +load_all(run_state) } } package "hydromodpy.spatial.field.geology" { class GeologyField { +from_watershed_config(...) } } package "hydromodpy.data.hydrometry" { class StationSet { +from_config(config_data) } } package "hydromodpy.spatial.domain" { class Domain { +set_zone(name, zone) } class DomainBinders { +apply_geology_to_domain(domain, geology) } } package "hydromodpy.physics.flow" { class FlowBinders { +apply_oceanic_to_flow(flow, oceanic) +apply_climatic_to_flow_recharge(flow, climatic) } } Project --> DataPlanner : build(...) DataPlanner ..> DataLoadPlan : returns Project --> ProjectRunState : stores raw_toml\nand data_plan Project --> DataManagersRuntimeLoader : load_all(run_state) DataManagersRuntimeLoader --> ProjectRunState : fills loaded_data DataManagersRuntimeLoader ..> GeologyField : builds if geology active DataManagersRuntimeLoader ..> StationSet : builds if hydrometry active Project --> DomainBinders : apply_geology_to_domain(...) DomainBinders --> Domain : set_zone("geology", geology) Project --> FlowBinders : apply_oceanic/climatic(...) ProjectRunState ..> DataLoadPlan : resolved activation trace @enduml

Notes:

  • DataLoadPlan defines which data families are active.

  • _run_setup, DataManagersRuntimeLoader, and binders define where corresponding objects are stored.

  • Geology is transferred into Domain as a zone used by process solvers.

  • Hydrometry is transferred into the Project loaded-data state for diagnostics and downstream use.

Activity diagram: definition and transfer#

This control-flow view documents the activation of data families and the transfer of concrete data objects to the right runtime holders.

It focuses on:

  • planning-time activation (DataPlanner.build);

  • setup-time geology transfer to Domain;

  • data-phase transfer of hydrometry to the Project runtime loaded-data state;

  • continuation into simulation execution after data placement is complete.

@startuml title Data Definition And Transfer - Activity start :Project.__init__(); :Load validated cfg and raw TOML; :DataPlanner.build(..., raw_toml, domain_zone_ids, flow_active_bc); if (domain.zone_ids contains geology?) then (yes) :Activate geology (explicit or inferred); endif :Apply resolved data types into cfg.data; :Store data_plan in Project runtime state; :Project.run(); :setup_workspace(); :build_geographic(); :load_data(); :DataManagersRuntimeLoader.load_all(run_state); :Transfer loaded_data.geology/hydrometry/oceanic/climatic; :_apply_structural_updates_from_data(); if (geology loaded?) then (yes) :apply_geology_to_domain(domain, geology); endif if (oceanic loaded?) then (yes) :apply_oceanic_to_flow(flow, oceanic); endif if (climatic loaded?) then (yes) :apply_climatic_to_flow_recharge(flow, climatic); endif :Continue with simulation plan execution; stop @enduml

Notes:

  • The same raw TOML can influence both activation inference and data payloads.

  • Geology transfer is driven by resolved data types at setup time.

  • Hydrometry transfer is implemented by DataManagersRuntimeLoader during Project.load_data().

  • Missing or invalid hydrometry configuration can be downgraded to warnings in data.inference_mode = "warn" mode.