[flow] FlowConfig

TOML section: [flow]

Pydantic model: FlowConfig defined in hydromodpy.physics.flow.flow_config.

Source on GitHub

Flow-process configuration.

Parameters are declared in param_list (ordered list of ids), and parameter payloads are stored in param. The 13 flat runtime_*/vi_*/ts_vi_* Boussinesq knobs are declared on FlowRuntimeFields and grouped together by the runtime property as a FlowRuntimeConfig view.

Show fields: User User + Dev All

Fields

runtime_backend

Literal[‘local’, ‘scipy’, ‘scipy_sparse’, ‘petsc’] default = “local” dev experimental source

Optional nonlinear runtime backend hint used by the Boussinesq solver implementation. Other flow solvers may ignore this field.

Examples

• "local"

• "scipy_sparse"

surface_interaction_model

Literal[‘auto’, ‘regularized_partition’, ‘complementarity’, ‘vi_obstacle’, ‘ts_vi_obstacle’] default = “auto” dev experimental source

Optional Boussinesq surface-interaction closure selector. ‘regularized_partition’ uses the Marcais-style q_ex = G_r(theta) R(balance) law; ‘complementarity’ uses the mixed PETSc q_ex-perp-(z_top-h) formulation; ‘vi_obstacle’ uses the experimental PETSc head-only VI obstacle formulation; ‘auto’ keeps the historical backend-dependent default.

Examples

• "auto"

• "regularized_partition"

runtime_max_iterations

int | None default = None dev source

Optional override for the nonlinear iteration budget used by the Boussinesq runtime backend.

runtime_tol_residual_inf

float | None default = None dev source

Optional override for the infinity-norm residual tolerance used by the Boussinesq runtime backend.

runtime_tol_state_update_inf

float | None default = None dev source

Optional override for the infinity-norm state-update tolerance used by Boussinesq backends that track it.

vi_substeps_per_period

int default = 1 dev source

Fixed number of Backward-Euler substeps per stress period for the experimental PETSc VI obstacle runtime. Rate-based forcing values are kept unchanged on each substep.

vi_substep_on_failure

bool default = False dev source

When true, retry a failed PETSc VI obstacle stress period with increasing substep counts.

vi_max_adaptive_substeps

int | None default = None dev source

Maximum number of PETSc VI obstacle substeps allowed for adaptive failure retries.

ts_vi_steps_per_period

int default = 4 dev source

Fixed PETSc TS Backward-Euler steps per stress period for the experimental TS VI obstacle runtime.

ts_vi_adapt

bool default = False dev source

Enable experimental PETSc TS adaptivity for the TS VI obstacle runtime.

ts_vi_dt_min_fraction

float default = 0.015625 dev source

Minimum TS VI time-step as a fraction of the stress-period length.

ts_vi_dt_max_fraction

float default = 0.25 dev source

Maximum TS VI time-step as a fraction of the stress-period length.

ts_vi_type

str default = “beuler” dev source

PETSc TS type for the experimental TS VI obstacle runtime.

ts_vi_snes_type

str default = “vinewtonrsls” dev source

PETSc SNES type for the experimental TS VI obstacle runtime.

param_list

list[str] factory user source

Ordered list of flow-parameter identifiers used to build runtime parameters (for example [‘K’, ‘Ss’, ‘Sy’]).

Example: ["K", "Sy", "Ss"]

param in TOML: [flow.param.<id>]

dict[str, FlowParam] factory user source

Mapping of flow-parameter identifiers to native FieldParamConfig payloads.

Fields of FlowParam

field in TOML: [flow.param.<id>.field]

kind = “homogeneous” | “heterogeneous” required user source

Discriminated parameter section [field].

Pick a tab below: setting kind selects the matching schema.

homogeneous

TOML: [flow.param.<id>.field.homogeneous] – model FieldHomogeneousSection (set kind = "homogeneous").

id

Optional[str] default = None user source

Parameter identifier used in outputs and logs (for example ‘K’, ‘Sy’).

unit

str | None default = None user source

Unit of parameter values. Typical examples: ‘m/s’ (K), ‘-’ (Sy), ‘m-1’ (Ss).

value

object | None default = None user source

Scalar surface value used when kind=’homogeneous’.

heterogeneous

TOML: [flow.param.<id>.field.heterogeneous] – model FieldHeterogeneousSection (set kind = "heterogeneous").

id

Optional[str] default = None user source

Parameter identifier used in outputs and logs (for example ‘K’, ‘Sy’).

unit

str | None default = None user source

Unit of parameter values. Typical examples: ‘m/s’ (K), ‘-’ (Sy), ‘m-1’ (Ss).

values_source

Literal[‘inline’, ‘csv’] default = “inline” user source

Source for heterogeneous values. Use ‘inline’ for TOML mapping or ‘csv’ for external table.

values in TOML: [flow.param.<id>.field.heterogeneous.values.<id>]

dict[str, float | str] | None default = None user source

Inline key/value mapping used when values_source=’inline’. Keys are zone/material ids, values are numeric parameter values.

values_csv_file

Optional[str] default = None dev source

Path to CSV mapping file used when values_source=’csv’. Relative paths are resolved from TOML directory.

csv_key_column

str default = “zone_key” dev source

CSV column name containing zone/material keys.

csv_value_column

str default = “value” dev source

CSV column name containing numeric parameter values.

field_spatial_id

Optional[str] default = None user source

Identifier of the spatial field used to map heterogeneous values (must match geometry field id).

field_vertical_profile in TOML: [flow.param.<id>.field_vertical_profile]

FieldVerticalProfileSection | None default = None user source

Optional depth profile section [field_vertical_profile].

Fields of FieldVerticalProfileSection

mode

Literal[‘none’, ‘exponential’, ‘tabulated’] default = “none” user source

Depth dependency mode shared over the full domain. Allowed values: ‘none’, ‘exponential’, ‘tabulated’.

characteristic_depth

Optional[Any] default = None dev source

Characteristic depth for exponential mode. Vertical factor is exp(-depth/characteristic_depth).

min_factor

Optional[float] default = None dev source

Optional floor factor for exponential mode. If provided, factor is max(exp(-depth/characteristic_depth), min_factor).

depths

list[float] | None default = None dev source

Depth nodes for tabulated mode (meters, first value must be 0).

factors

list[float] | None default = None dev source

Multiplicative factors aligned with depths for tabulated mode (first value must be 1 at depth 0).

interpolation

Literal[‘linear’, ‘step’] default = “linear” dev source

Interpolation strategy for tabulated mode. Allowed values: ‘linear’ or ‘step’.

ic in TOML: [flow.ic]

FlowInitialConditions factory user source

Validated flow initial-condition structure parsed from [flow.ic]. Stored as FlowInitialConditions(h=FlowInitialCondition).

Fields of FlowInitialConditions

h in TOML: [flow.ic.h]

type = “top” | “top_offset” | “bottom” | “custom” | “steady_state” factory user source

Hydraulic-head initial condition payload.

Pick a tab below: setting type selects the matching schema.

top

TOML: [flow.ic.h.top] – model FlowICTop (set type = "top").

id

str default = “h” dev source

id of the initial condition (forced to ‘h’ for flow)

value

object | None default = None user source

Process-specific initial-condition value payload.

description

str default = “” user source

Description of the initial condition

units

str default = “m” dev source

Runtime unit for the initial hydraulic-head field.

top_offset

TOML: [flow.ic.h.top_offset] – model FlowICTopOffset (set type = "top_offset").

id

str default = “h” dev source

id of the initial condition (forced to ‘h’ for flow)

value

Any required user source

Vertical offset below the top surface.

description

str default = “” user source

Description of the initial condition

units

str default = “” user source

Units of the initial condition

bottom

TOML: [flow.ic.h.bottom] – model FlowICBottom (set type = "bottom").

id

str default = “h” dev source

id of the initial condition (forced to ‘h’ for flow)

value

object | None default = None user source

Process-specific initial-condition value payload.

description

str default = “” user source

Description of the initial condition

units

str default = “m” dev source

Runtime unit for the initial hydraulic-head field.

custom

TOML: [flow.ic.h.custom] – model FlowICCustom (set type = "custom").

id

str default = “h” dev source

id of the initial condition (forced to ‘h’ for flow)

value

Any required user source

Initial hydraulic-head value.

description

str default = “” user source

Description of the initial condition

units

str default = “” user source

Units of the initial condition

steady_state

TOML: [flow.ic.h.steady_state] – model FlowICSteadyState (set type = "steady_state").

id

str default = “h” dev source

id of the initial condition (forced to ‘h’ for flow)

value

object | None default = None user source

Process-specific initial-condition value payload.

description

str default = “” user source

Description of the initial condition

units

str default = “m” dev source

Runtime unit for the initial hydraulic-head field.

source

Optional[Literal[‘recharge’, ‘mean_recharge’]] default = None user source

Forcing source used by the initialization solve. ‘mean_recharge’ is an alias for source=’recharge’ with recharge_statistic=’time_mean’.

recharge_statistic

Optional[Literal[‘time_mean’]] default = None user source

Statistic applied to the recharge chronicle.

boundary_condition_policy

Optional[Literal[‘first_period’]] default = None user source

Policy used for transient boundary-condition chronicles during the steady initialization solve.

bc in TOML: [flow.bc.<id>]

kind = “dirichlet” | “cauchy” | “robin” factory user source

Mapping of flow boundary-condition payloads parsed from [flow.bc].

Supported TOML sections

• [flow.bc.dirichlet.<id>] where <id> is one of ocean, stream, north_side, south_side, east_side, west_side

• [flow.bc.cauchy.drainage]

• [flow.bc.robin.drainage]

• [flow.bc.<custom_id>] for generic payloads

Common keys

• value (required): numeric or '<value> <unit>'

• application_domain: optional for dirichlet when <id> implies it (e.g. west_side -> 'west side'); required for cauchy and robin drainage

Allowed application_domain values: top, north side, south side, east side, west side.

Default units: m for dirichlet, m2/s for cauchy/robin.

Cauchy vs Robin: both map to the same MODFLOW DRN package; the distinction only matters for the Boussinesq solver, which uses two different surface-interaction closures (cauchy for the linear formulation q = C(h - h_ref), robin for the regularized partition / complementarity variants selected by flow.surface_interaction_model).

Pick a tab below: setting kind selects the matching schema.

dirichlet

TOML: [flow.bc.dirichlet.<id>] – model DirichletBC (set kind = "dirichlet").

id

str required user source

Boundary-condition identifier.

value

float | list[float] | None default = None user source

Boundary-condition value, scalar or one value per stress period.

description

str default = “” user source

Boundary-condition description.

units

str default = “” dev source

Boundary-condition units.

data_value

bool default = False dev source

If True, boundary-condition values are sourced from data.

forcing in TOML: [flow.bc.dirichlet.<id>.forcing]

mode = “constant” | “csv” default = None dev source

Optional runtime forcing declaration for lateral Dirichlet boundaries. Supported modes: ‘constant’ and ‘csv’. The launcher resolves this payload to boundary.value using [simulation.time].

Pick a tab below: setting mode selects the matching schema.

constant

TOML: [flow.bc.dirichlet.<id>.forcing.constant] – model FlowBoundaryForcingConstantConfig (set mode = "constant").

value

float required user source

Constant boundary head value used when mode=’constant’.

units

str | None default = None dev source

Source units of forcing values before runtime conversion.

csv

TOML: [flow.bc.dirichlet.<id>.forcing.csv] – model FlowBoundaryForcingCsvConfig (set mode = "csv").

path_file

Path required dev source

CSV file path containing time-series boundary head values when mode=’csv’.

sep

str default = “,” dev source

CSV column separator.

date_column

str default = “date” dev source

CSV column containing timestamps.

date_format

str | None default = None dev source

Optional datetime format passed to pandas.to_datetime.

value_column

str default = “value” dev source

CSV column containing boundary head values.

fill_method

Literal[‘ffill’, ‘bfill’] default = “ffill” dev source

Gap-filling policy used when a stress period has no direct sample.

aggregate

Literal[‘mean’, ‘last’] default = “mean” dev source

Stress-period aggregation method.

units

str | None default = None dev source

Source units of forcing values before runtime conversion.

application_domain

str | None default = None user source

Boundary-application domain. Supported values are: top, north side, south side, east side, west side.

support_label

Optional[str] default = None user source

Optional explicit runtime support label used by unstructured backends to select one target support independently from the canonical boundary id.

cauchy

TOML: [flow.bc.cauchy.<id>] – model CauchyBC (set kind = "cauchy").

id

str required user source

Boundary-condition identifier.

value

float | list[float] | None default = None user source

Boundary-condition value, scalar or one value per stress period.

description

str default = “” user source

Boundary-condition description.

units

str default = “” dev source

Boundary-condition units.

data_value

bool default = False dev source

If True, boundary-condition values are sourced from data.

application_domain

str | None default = None user source

Boundary-application domain. Supported values are: top, north side, south side, east side, west side.

support_label

Optional[str] default = None user source

Optional explicit runtime support label used by unstructured backends to select one target support independently from the canonical boundary id.

robin

TOML: [flow.bc.robin.<id>] – model RobinBC (set kind = "robin").

id

str required user source

Boundary-condition identifier.

value

float | list[float] | None default = None user source

Boundary-condition value, scalar or one value per stress period.

description

str default = “” user source

Boundary-condition description.

units

str default = “” dev source

Boundary-condition units.

data_value

bool default = False dev source

If True, boundary-condition values are sourced from data.

application_domain

str | None default = None user source

Boundary-application domain. Supported values are: top, north side, south side, east side, west side.

support_label

Optional[str] default = None user source

Optional explicit runtime support label used by unstructured backends to select one target support independently from the canonical boundary id.

sinks_sources in TOML: [flow.sinks_sources]

FlowSinksSourcesConfig factory user source

Typed sinks/sources payload (for example pumping wells).

Fields of FlowSinksSourcesConfig

wells in TOML: [flow.sinks_sources.wells.<id>]

dict[str, FlowWellConfig] factory user source

Mapping of well ids to typed well payloads.

Fields of FlowWellConfig

location in TOML: [flow.sinks_sources.wells.<id>.location]

kind = “cell” | “absolute_xy” | “relative_xy” required user source

Well location payload. Discriminated by ‘kind’: ‘cell’, ‘absolute_xy’, or ‘relative_xy’.

Pick a tab below: setting kind selects the matching schema.

cell

TOML: [flow.sinks_sources.wells.<id>.location.cell] – model FlowWellLocationCell (set kind = "cell").

cell

tuple[int, int, int] required user source

Direct cell indices as [lay, row, col] (0-based, FLOPY convention).

absolute_xy

TOML: [flow.sinks_sources.wells.<id>.location.absolute_xy] – model FlowWellLocationAbsoluteXY (set kind = "absolute_xy").

layer

int default = 0 dev source

Layer index (0-based) targeted by the well.

x

float required user source

Projected X coordinate in solver units.

y

float required user source

Projected Y coordinate in solver units.

relative_xy

TOML: [flow.sinks_sources.wells.<id>.location.relative_xy] – model FlowWellLocationRelativeXY (set kind = "relative_xy").

layer

int default = 0 dev source

Layer index (0-based) targeted by the well.

x_rel

float required user source

Relative X position in [0, 1] from west to east.

y_rel

float required user source

Relative Y position in [0, 1] from south to north.

flux

float | list[float] | None default = None user source

Well rate [L^3/T]. Scalar for constant rate, or one value per stress period. Negative = pumping, positive = injection.

forcing in TOML: [flow.sinks_sources.wells.<id>.forcing]

kind = “constant” | “csv” default = None dev source

Optional runtime forcing declaration. Supported modes: ‘constant’ and ‘csv’. The launcher resolves this payload to well.flux using [simulation.time].

Pick a tab below: setting kind selects the matching schema.

constant

TOML: [flow.sinks_sources.wells.<id>.forcing.constant] – model FlowWellForcingConstantConfig (set kind = "constant").

value

Any required user source

Constant well rate in the same units as the parent well.

units

str | None default = None dev source

Source units of the constant value before runtime conversion.

csv

TOML: [flow.sinks_sources.wells.<id>.forcing.csv] – model FlowWellForcingCsvConfig (set kind = "csv").

path_file

Path required dev source

Path to the CSV chronicle file.

sep

str default = “,” dev source

CSV delimiter.

date_column

str default = “date” dev source

CSV column containing timestamps.

date_format

str | None default = None dev source

Optional datetime format passed to pandas.to_datetime.

value_column

str default = “value” dev source

CSV column containing well rates.

fill_method

Literal[‘ffill’, ‘bfill’] default = “ffill” dev source

Gap-filling policy used when a stress period has no direct sample.

aggregate

Literal[‘mean’, ‘last’] default = “mean” dev source

Stress-period aggregation method.

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

units

str default = “m3/s” dev source

Units of flux values.

description

str default = “” user source

Optional well description.

recharge in TOML: [flow.sinks_sources.recharge]

FlowRechargeConfig | None default = None user source

Diffuse recharge configuration. None = zero recharge for all periods.

Fields of FlowRechargeConfig

values

Any default = 0.0 user source

Recharge payload: scalar, list (one per stress period), mapping {kper: value}, or runtime series.

heterogeneous_source

Any default = None dev source

Optional raw data source for heterogeneous (2D per-cell) recharge. When set, the solver adapter discretizes FieldRecords onto the MODFLOW grid instead of using the scalar ‘values’ field. Expected: LoadResult with FieldRecords.

first_clim

str | float default = “mean” dev source

Period-0 policy when values is a sequence: ‘mean’ (series average), ‘first’ (first element), or a numeric scalar.

units

str default = “mm/day” dev source

Units of the recharge data source. Data-manager outputs use mm/day by convention; override when providing values in another unit (e.g. ‘m/day’). Converted to m/s at runtime via factor_to_m_per_s().

negative_to_evt

bool default = True dev source

When true, negative recharge values are routed to the solver EVT package and RCH receives the non-negative clipped recharge.

spatial_mode

Literal[‘auto’, ‘homogeneous’, ‘heterogeneous’] default = “auto” dev source

How to interpret spatial data: ‘auto’ (points->homogeneous, fields->heterogeneous), ‘homogeneous’ (force spatial averaging), ‘heterogeneous’ (force per-cell discretization, including point-to-grid interpolation when stations have coordinates).

interpolation_method

Literal[‘nearest’, ‘linear’, ‘idw’] default = “nearest” dev source

Spatial interpolation method for gridded/point data onto the MODFLOW grid. Options: ‘nearest’, ‘linear’, ‘idw’.

etp in TOML: [flow.sinks_sources.etp]

FlowEtpConfig | None default = None user source

Diffuse evapotranspiration configuration. None = no EVT package built.

Fields of FlowEtpConfig

values

Any default = 0.0 user source

ETP payload: scalar, list (one per stress period), mapping {kper: value}, or runtime series. Values must be non-negative; the EVT package treats them as outflow rates.

heterogeneous_source

Any default = None dev source

Optional raw data source for heterogeneous (2D per-cell) ETP. When set, the solver adapter discretizes FieldRecords onto the MODFLOW grid instead of using the scalar ‘values’ field. Expected: LoadResult with FieldRecords.

first_clim

str | float default = “mean” dev source

Period-0 policy when values is a sequence: ‘mean’ (series average), ‘first’ (first element), or a numeric scalar.

units

str default = “mm/day” dev source

Units of the ETP data source. Data-manager outputs use mm/day by convention; converted to m/s at runtime.

surface_offset

Any default = 2.0 dev source

Distance below the topographic surface (m) where the EVT extraction surface sits. MODFLOW EVT extracts water linearly between this surface and surface - extinction_depth. Legacy default was DEM - 2 m.

extinction_depth

Any default = 1.0 dev source

EVT extinction depth (m): below surface_offset + extinction_depth, evapotranspiration is zero. Legacy default was 1 m.

spatial_mode

Literal[‘auto’, ‘homogeneous’, ‘heterogeneous’] default = “auto” dev source

How to interpret spatial data: ‘auto’ (points->homogeneous, fields->heterogeneous), ‘homogeneous’, or ‘heterogeneous’.

interpolation_method

Literal[‘nearest’, ‘linear’, ‘idw’] default = “nearest” dev source

Spatial interpolation method for gridded/point data onto the MODFLOW grid. Options: ‘nearest’, ‘linear’, ‘idw’.

active_sinks_sources

list[str] factory user source

Explicitly activated sink/source names for this flow run. Allowed values: ‘recharge’, ‘wells’, ‘etp’. Boussinesq currently rejects ‘etp’ at solver-contract validation. An empty list means no sink/source package is assembled by the solver.

Examples

• ["recharge"]

• ["recharge", "wells"]

• ["etp"]

active_bc

list[str] factory user source

Explicitly activated boundary-condition ids for this flow run. Allowed values are the canonical ids declared in the flow boundary-condition registry: ‘ocean’, ‘stream’, ‘north_side’, ‘south_side’, ‘east_side’, ‘west_side’, ‘drainage’. An empty list means no boundary-condition package is assembled by the solver.

Examples

• ["ocean"]

• ["west_side", "east_side", "drainage"]

flow_regime

Literal[‘steady’, ‘transient’] default = “transient” user source

Global flow simulation regime used by solvers consuming [flow] (steady or transient).

Examples

• "steady"

• "transient"

first_period_steady

bool default = True user source

For transient flow, mark the first solver stress period as steady-state. Ignored for steady flow, where all solver periods are steady.

Examples

• true

• false

Starter TOML snippet

Click to expand a copy-pasteable [flow] TOML skeleton

Copy this block into your project.toml and uncomment the lines you want to set. Sub-tables ([parent.subfield]) appear in the order Pydantic expects them.

[flow]
# param_list = ...  # uses factory default
# [flow.param.<id>]
# [flow.bc.<id>]
# active_sinks_sources = ...  # uses factory default
# active_bc = ...  # uses factory default
# flow_regime = "transient"
# first_period_steady = true

[flow.ic]
# h = ...  # factory default

[flow.sinks_sources]
# wells = ...  # factory default
# recharge = ...  # default = None
# etp = ...  # default = None

Cases using this section

Validation gallery cases that reference fields from this section:

• Boussinesq Circular-Island Piecewise-K 2D

• Boussinesq Divide-Fixed-Head Piecewise-K 1D

• Boussinesq Fixed-Head Piecewise-K 1D

• Boussinesq Hillslope Interception 1D

• Boussinesq Sloping-Substratum Constant-Thickness 1D

• Boussinesq Sloping-Substratum Fixed-Head 1D

• Boussinesq Sloping-Substratum Uniform-Recharge 1D

• Boussinesq Uniform-Recharge Piecewise-K 1D

• Brutsaert Recession Validation: Thin Nonlinear Aquifer

• Brutsaert Recession Validation: Deep Linearized Aquifer

• Dupuit Circular-Island Ocean 2D

• Dupuit Divide-River 1D

• Dupuit Fixed-Head 1D

• Dupuit Uniform Recharge 1D

• Late-Time Unconfined Pumping 2D

• Linearized Unconfined Boundary Piecewise 1D

• Linearized Unconfined 1D Boundary Step

• Linearized Unconfined Drainage 1D

• Linearized Unconfined Hillslope Drainage 1D

• Linearized Unconfined 1D Periodic Recharge

• Linearized Unconfined 1D Recharge Step

• Linearized Unconfined 1D Recharge Step (Deep Aquifer)

Entity-relationship diagram

Click to zoom and pan. Press Esc or click outside to close.