Flow#

class hydromodpy.physics.Flow(config)[source]#

Bases: ProcessSpatial

Runtime flow-process object built from a validated FlowConfig.

Quick reading guide#

For a first pass, focus on these three methods: - set_config: one-shot synchronization from FlowConfig to runtime. - _build_boundary_conditions: validation and normalization of BC payloads. - set_sinks_sources: runtime storage of wells and recharge payloads.

Inherits from ProcessSpatial, which initializes the base containers (parameters, initial_conditions, boundary_conditions, sinks_sources, active_bc, active_sinks_sources) and provides the parameter-ingestion helpers.

Flow specializes those containers with:

  • FlowInitialConditions as the typed IC structure (head policy),

  • BoundaryCondition Pydantic objects for each configured BC,

  • a {"wells": ..., "recharge": ...} namespace for sinks/sources.

Runtime attributes (populated by set_config)#

flow_regimestr

'steady' or 'transient', forwarded from FlowConfig.

runtime_backendstr

Optional nonlinear runtime backend hint, currently consumed by the Boussinesq solver implementation.

surface_interaction_modelstr

Optional groundwater/surface interaction closure selector consumed by the Boussinesq solver implementation.

runtime_max_iterationsint | None

Optional nonlinear iteration-budget override forwarded to Boussinesq.

runtime_tol_residual_inffloat | None

Optional residual-tolerance override forwarded to Boussinesq.

runtime_tol_state_update_inffloat | None

Optional state-update-tolerance override forwarded to Boussinesq.

vi_substeps_per_periodint

Fixed substeps per stress period for PETSc VI obstacle.

vi_substep_on_failurebool

Whether PETSc VI obstacle retries failed periods with more substeps.

vi_max_adaptive_substepsint | None

Maximum PETSc VI obstacle adaptive substep count.

ts_vi_steps_per_periodint

Fixed PETSc TS steps per stress period for TS VI obstacle.

ts_vi_adaptbool

Whether PETSc TS adaptivity is enabled for TS VI obstacle.

configFlowConfig

Reference to the last validated config applied via set_config.

parametersdict[str, FieldParam | object]

Hydraulic property parameters (K, Sy, Ss, …) keyed by id.

initial_conditionsFlowInitialConditions | None

Typed IC container; exposes h (head IC: type + optional value).

initial_condition_typesdict[str, str]

Compact cache {"h": type_str}; allows fast IC-type inspection without traversing the full FlowInitialConditions object.

boundary_conditionsdict[str, FlowBoundaryConditionConfig]

Typed BC objects keyed by BC id.

boundary_condition_application_domainsdict[str, str]

Optional per-BC spatial domain strings (e.g. "top", "west side"); used by spatial adapters that need to know where a BC is applied.

active_bclist[str]

BC ids declared as active in config; only these are processed by the solver adapter.

sinks_sourcesdict[str, object]

Namespace with keys "wells" (dict[str, FlowWellConfig]) and "recharge" (FlowRechargeConfig | None).

active_sinks_sourceslist[str]

Sink/source categories explicitly activated (e.g. ["wells", "recharge"]).

param config:

type config:

FlowConfig

Build one Flow runtime object from one validated config.

Parameters#

configFlowConfig

Typed flow configuration payload.

param config:

type config:

FlowConfig

set_config(config)[source]#

Apply one validated FlowConfig payload to runtime state.

This is the main synchronization point between config and runtime containers. All existing runtime attributes are replaced in one deterministic pass. Calling this method a second time with a new config fully resets the runtime state.

Return type:

None

Parameters:

config (FlowConfig)

Steps performed (in order)#

  1. flow_regime is forwarded directly from the config string.

  2. parameters are resolved in the order declared by config.param_list (preserves user intent for K/Sy/Ss ordering).

  3. initial_conditions are built from config.ic via the process-specific normalizer (delegates to normalize_flow_initial_conditions).

  4. active_* lists are copied from config, then boundary_conditions and boundary_condition_bundle are built from config.bc.

  5. sinks_sources is populated from config.sinks_sources (wells dict + recharge config).

param config:

type config:

FlowConfig

build_initial_conditions(initial_conditions)[source]#

Normalize one raw IC payload into FlowInitialConditions.

Delegates to the dedicated normalizer used by FlowConfig, so runtime and configuration validation rules stay aligned.

Parameters:

initial_conditions (object | None)

Return type:

FlowInitialConditions | None

set_initial_conditions(initial_conditions)[source]#

Normalize and store flow initial conditions.

Delegates normalization to build_initial_conditions (which calls normalize_flow_initial_conditions), then stores the result in self.initial_conditions.

Also maintains self.initial_condition_types, a compact {"h": type_str} dict. This cache lets downstream code (e.g. solver adapters) check the IC type in O(1) without traversing the full FlowInitialConditions object.

Parameters:

initial_conditions (object | None)

Return type:

None

set_boundary_conditions(boundary_conditions=None, *, application_domains=None)[source]#

Replace boundary-condition runtime containers.

Return type:

None

Parameters:

  • boundary_conditions (dict[str, FlowBoundaryConditionConfig] | None)

  • application_domains (dict[str, str] | None)

Parameters#

boundary_conditionsdict[str, FlowBoundaryConditionConfig] | None

Typed BC payloads keyed by BC id.

application_domainsdict[str, str] | None

Optional per-BC domain targets (for example top, west side).

param boundary_conditions:

type boundary_conditions:

dict[str, FlowBoundaryConditionConfig] | None

param application_domains:

type application_domains:

dict[str, str] | None

set_sinks_sources(sinks_sources=None)[source]#

Replace flow sink/source runtime payloads.

Stores wells under self.sinks_sources[“wells”] and recharge config under self.sinks_sources[“recharge”].

Well fluxes are converted to SI volumetric flow (m3/s) at load time using each well units field.

Parameters:

sinks_sources (FlowSinksSourcesConfig | None)

Return type:

None

set_recharge(recharge)[source]#

Inject or replace the recharge payload at runtime.

Useful when recharge is computed dynamically (e.g. from a PyHELP run) and must be set after Flow is already configured from TOML.

Return type:

None

Parameters:

recharge (FlowRechargeConfig | None)

Parameters#

rechargeFlowRechargeConfig | None

Typed recharge payload, or None to clear.

param recharge:

type recharge:

FlowRechargeConfig | None

set_etp(etp)[source]#

Inject or replace the ETP payload at runtime.

Parameters:

etp (FlowEtpConfig | None)

Return type:

None

Parameters:

config (FlowConfig)