hydromodpy.physics.flow.flow#

Flow Runtime Process#

Purpose#

Provide the runtime representation of the groundwater flow process, built from one validated FlowConfig and consumed by solver adapter layers.

Scope#

Flow is process-level and solver-agnostic. It exposes the following runtime attributes after set_config(...) is called:

  • flow_regime : 'steady' or 'transient', forwarded from config.

  • runtime_backend : optional nonlinear runtime backend hint used by the Boussinesq solver implementation (for example local, scipy, scipy_sparse, petsc).

  • surface_interaction_model : optional Boussinesq closure selector for the groundwater/surface interaction (auto, regularized_partition, complementarity, vi_obstacle, ts_vi_obstacle).

  • runtime_max_iterations / runtime_tol_* : optional nonlinear runtime overrides forwarded to the Boussinesq backend.

  • vi_substeps_per_period / vi_substep_on_failure / vi_max_adaptive_substeps : optional substepping controls for the experimental PETSc VI obstacle Boussinesq runtime.

  • ts_vi_steps_per_period / ts_vi_adapt : optional PETSc TS controls for the experimental TS VI obstacle Boussinesq runtime.

  • parameters : normalized hydraulic property dict (K, Sy, Ss, …), keyed by parameter id and containing FieldParam objects.

  • initial_conditions : one FlowInitialConditions instance grouping the head IC policy (type + optional scalar value).

  • initial_condition_types : compact cache {"h": type_str} for fast IC-type inspection downstream.

  • boundary_conditions : typed BoundaryCondition objects keyed by BC id ("ocean", "drainage", "west_side", …).

  • boundary_condition_application_domains : optional per-BC domain strings (e.g. "top", "west side"), used by some spatial adapters.

  • active_bc : list of BC ids explicitly activated in the config; only these ids will be processed by the solver adapter.

  • sinks_sources : dict with two keys: "wells" → dict[str, FlowWellConfig], "recharge" → FlowRechargeConfig | None.

  • active_sinks_sources : list of sink/source categories explicitly activated (e.g. ["wells", "recharge"]).

Runtime lifecycle#

  1. FlowConfig is validated by Pydantic from a TOML/dict payload.

  2. Flow(config) calls set_config(config) which normalizes each config section into the typed runtime containers listed above.

  3. Solver adapters (outside this module) read those containers and transform them into solver-ready arrays and stress-period payloads.

Data path (high-level)#

TOML
 └─> FlowConfig (Pydantic)
      └─> Flow.set_config()
           ├─ [flow]               -> flow_regime
           ├─ [flow.param]         -> parameters
           ├─ [flow.ic]            -> initial_conditions
           ├─ [flow.bc]            -> boundary_conditions, active_bc
           └─ [flow.sinks_sources] -> sinks_sources, active_sinks_sources
                                           └─> FlowToModflowAdapter -> MODFLOW

Design rule#

Any transformation to solver-specific formats (for example MODFLOW stress-period dictionaries) is performed outside this class, in solver adapter layers. Flow itself never references FLOPY or any solver convention.

Non-goals#

  • no direct FLOPY/MODFLOW package creation in this module,

  • no spatial discretization or gridding logic in this module,

  • no temporal stress-period formatting in this module.

Classes

Flow(config)

Runtime flow-process object built from a validated FlowConfig.
On this page