[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

str default = “local” dev experimental source

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

One of: "local" "scipy" "scipy_sparse" "petsc"

Examples

• "local"

• "scipy_sparse"

surface_interaction_model

str 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.

One of: "auto" "regularized_partition" "complementarity" "vi_obstacle" "ts_vi_obstacle"

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] with kind = "homogeneous" – model FieldHomogeneousSection.

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] with kind = "heterogeneous" – model FieldHeterogeneousSection.

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

str default = “inline” user source

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

One of: "inline" "csv"

values in TOML: [flow.param.<id>.field.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

str default = “none” user source

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

One of: "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

str default = “linear” dev source

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

One of: "linear" "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” | “spinup_cyclic” factory user source

Hydraulic-head initial condition payload.

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

top

TOML: [flow.ic.h] with type = "top" – model FlowICTop.

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] with type = "top_offset" – model FlowICTopOffset.

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] with type = "bottom" – model FlowICBottom.

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] with type = "custom" – model FlowICCustom.

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] with type = "steady_state" – model FlowICSteadyState.

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[str] default = None user source

Forcing source used by the initialization solve. ‘mean_recharge’ is an alias for source=’recharge’ with recharge_statistic=’time_mean’. ‘prescribed’ holds the solve at the single rate given by rate instead of reading the chronicle.

One of: "recharge" "mean_recharge" "prescribed"

recharge_statistic

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

Statistic applied to the recharge chronicle.

rate

Optional[float] default = None user source

Recharge rate the initialization solve is held at, in m/s. Carries its own unit: ‘500 mm/yr’, ‘2 mm/day’, 1.6e-8. Required by source=’prescribed’ and refused by any other source.

boundary_condition_policy

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

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

spinup_cyclic

TOML: [flow.ic.h] with type = "spinup_cyclic" – model FlowICSpinupCyclic.

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.

max_cycles

int default = 4 user source

Most cycles the loop may run. A loop that runs out of cycles still hands back its last state and says so, rather than reporting a convergence that did not happen.

tol_head

Any default = “0.01 m” user source

Largest head change between two cycles that counts as settled, anywhere in the domain. One centimetre is a starting point; the honest check is to loosen it and see whether what you report moves.

first_cycle_from

str default = “top” user source

Where cycle one starts. ‘top’ is the water table at the surface, which the cycling then drains. ‘steady_state’ starts from the equilibrium under the mean forcing, which is closer and usually saves a cycle.

One of: "top" "steady_state"

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.<id>], one block per boundary, keyed by what it is. Canonical ids: drainage, ocean, stream, north_side, south_side, east_side, west_side

• a boundary the registry describes entirely needs NO block: listing it in flow.active_bc is enough

Common keys

• kind: optional, the registry supplies it; write it only to depart from the default, and only within a family (cauchy and robin may be swapped, a prescribed head may not)

• value: optional on a drainage, where leaving it out derives the conductance from K; required for a prescribed head

• application_domain: optional, the registry supplies it, and a value contradicting it is refused

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.<id>] with kind = "dirichlet" – model DirichletBC.

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. On a drainage boundary it is a conductance in m2/s, and it may be left out: the run then derives it from the conductivity, C = K * cell_area / solver.drain_bed_thickness_m, which keeps the drain proportional to K and makes K/R the quantity a network calibration searches. A zero or negative number selects that same derivation, so it does NOT mean a closed boundary; write a positive conductance to impose one.

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.<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.<id>.forcing] with mode = "constant" – model FlowBoundaryForcingConstantConfig.

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.<id>.forcing] with mode = "csv" – model FlowBoundaryForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

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.<id>] with kind = "cauchy" – model CauchyBC.

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. On a drainage boundary it is a conductance in m2/s, and it may be left out: the run then derives it from the conductivity, C = K * cell_area / solver.drain_bed_thickness_m, which keeps the drain proportional to K and makes K/R the quantity a network calibration searches. A zero or negative number selects that same derivation, so it does NOT mean a closed boundary; write a positive conductance to impose one.

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.<id>] with kind = "robin" – model RobinBC.

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. On a drainage boundary it is a conductance in m2/s, and it may be left out: the run then derives it from the conductivity, C = K * cell_area / solver.drain_bed_thickness_m, which keeps the drain proportional to K and makes K/R the quantity a network calibration searches. A zero or negative number selects that same derivation, so it does NOT mean a closed boundary; write a positive conductance to impose one.

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] with kind = "cell" – model FlowWellLocationCell.

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] with kind = "absolute_xy" – model FlowWellLocationAbsoluteXY.

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] with kind = "relative_xy" – model FlowWellLocationRelativeXY.

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” | “piecewise” | “seasonal” default = None dev source

Optional runtime forcing declaration. Supported modes: ‘constant’, ‘csv’, ‘piecewise’, and ‘seasonal’. 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] with kind = "constant" – model FlowWellForcingConstantConfig.

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] with kind = "csv" – model FlowWellForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

piecewise

TOML: [flow.sinks_sources.wells.<id>.forcing] with kind = "piecewise" – model FlowWellForcingPiecewiseConfig.

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

list[FlowWellForcingSegment] required user source

Date-ordered segments covering the simulation window.

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

units

str | None default = None dev source

Source units of segment values before runtime conversion.

seasonal

TOML: [flow.sinks_sources.wells.<id>.forcing] with kind = "seasonal" – model FlowWellForcingSeasonalConfig.

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

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

Mapping of calendar month (1-12) to a forcing value.

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

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

Mapping of meteorological season (DJF/MAM/JJA/SON) to a forcing value.

units

str | None default = None dev source

Source units of seasonal values before runtime conversion.

units

str default = “m3/s” dev source

Units of flux values.

description

str default = “” user source

Optional well description.

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

dict[str, FlowLakeConfig] factory user source

Mapping of lake ids to typed lake / reservoir payloads.

Fields of FlowLakeConfig

bedleak

float required user source

Lake-bed leakance [1/T] = K_bed / thickness_bed. Resistance of the lake-aquifer interface; the under-dam leakage calibration parameter. 0 means a perfectly sealed lakebed (no leakage).

bedleak_unit

str default = “1/s” user source

Unit of bedleak (leakance, 1/T): one of 1/s, 1/day, 1/h, 1/min (aliases like 1/d accepted). HydroModPy converts it to 1/s for MF6, so a 1/day leakance is not silently taken as 1/s.

stageinit

Any required user source

Initial lake stage [L].

steady_stage_hold

bool default = False user source

Hold the lake stage at stageinit during the steady warm-up period(s) (LAK status CONSTANT) and re-activate it on the first transient period. Use for a managed reservoir whose observed initial level is far from the natural steady equilibrium: the aquifer equilibrates around the observed stage instead of overriding it.

occupied_layers

int default = 1 user source

Number of top grid layers the lake occupies in each of its columns. 1 is a surface lake; a deeper reservoir embedded over several layers uses a higher count. Must leave at least one active layer below the lake for the VERTICAL leakage connection.

fill_enclosed_cells

bool default = False user source

Fill cells enclosed by the lake footprint (the polygon’s interior rings / islands) so the lake is contiguous. Off by default: interior rings stay active aquifer (real islands). Enable to drop sub-grid islands and classification pockets that would otherwise be isolated non-lake cells inside the lake.

surfdep

float | None default = None expert source

LAK surface depression depth [L] that smooths the dry/wet (marnage) transition for Newton. Default (None) uses 0.1 m. Raise it (e.g. 0.5 to 1.0 m) to stabilise and speed up the active-littoral steady solve when many lakebed cells toggle at once; it slightly fuzzes the shoreline.

bed_reconstruction in TOML: [flow.sinks_sources.lakes.<id>.bed_reconstruction]

BathymetryReconstructionConfig | None default = None user source

Optional bathymetry-driven bed carving. When set, the real lake bed is reconstructed from the lake_bathymetry raster (reconciled to the abacus) and carved into the grid instead of a flat reservoir.

Fields of BathymetryReconstructionConfig

reconcile_to_abacus

bool default = True user source

Re-map the regridded bed so the cell area-vs-elevation distribution matches the abacus (the abacus is the storage source of truth). When False, the raw regridded bathymetry is carved as-is.

dynamic_area

bool default = False user source

Active-littoral (marnage) representation. When True the lake-bed cells stay ACTIVE with the carved bathymetric bed as their cell top and one VERTICAL LAK connection each; MODFLOW 6 then toggles recharge/ET per cell (IWETLAKE) so a cell exchanges with the lake when submerged and recharges as land when the shoreline recedes below its bed. When False the footprint is deactivated (fixed-area reservoir, the classic inactive-footprint carve).

exposed_band_runoff

bool default = False expert source

Shed the overland runoff of the exposed lakebed band directly to the lake, sized per timestep from the simulated stage via the MODFLOW 6 BMI API (runoff_rate * exposed_area). Requires dynamic_area and forces the in-process API runner (serial only). When False the catchment runoff already covers the footprint area in a lumped, stage-static way.

bank_seepage

bool default = True user source

Also emit HORIZONTAL (bank) LAK connections on the active-littoral footprint, in addition to the VERTICAL (bed) ones, so the lake exchanges with the aquifer through both the bed AND the banks (the physical case). Sealed at the cutoff wall (dam) when one is declared. Only applies with dynamic_area = true; a fixed-area lake always emits both. Set False to keep the bed-only marnage representation (the bedleak then absorbs the bank contribution).

min_thickness

float default = 0.5 user source

Minimum layer thickness [L, model units] held by EVERY layer when re-grading a lake column around the carved bed, so no degenerate (near-zero) cell breaks the solver. The bed is clamped into the band the column can hold at that floor, i.e. [base + n_active * min_thickness, top - n_occupied * min_thickness]; a column too thin for it raises at build time. Raising this value moves the carved bed away from the bathymetry (the build logs the shift).

min_pixels

int default = 1 user source

Minimum bathymetry pixels whose centre must fall inside a cell for the zonal mean to be used; below it a bilinear sample at the cell centroid is taken instead.

outlets in TOML: [[flow.sinks_sources.lakes.<id>.outlets]]

couttype = “WEIR” | “MANNING” | “SPECIFIED” factory user source

Surverse / spillway / controlled-release outlets for this lake.

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

WEIR

TOML: [[flow.sinks_sources.lakes.<id>.outlets]] with couttype = "WEIR" – model FlowLakeOutletWeir.

invert

Any required user source

Weir crest elevation [L].

width

Any required user source

Effective weir crest length [L].

lakeout

int default = 0 user source

Downstream destination lake (1-based). 0 = external boundary (the discharge leaves the model).

mover in TOML: [flow.sinks_sources.lakes.<id>.outlets.mover]

FlowLakeOutletMover | None default = None user source

Optional controlled LAK -> LAK transfer routed through MVR (keep lakeout = 0 when a mover is set).

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

MANNING

TOML: [[flow.sinks_sources.lakes.<id>.outlets]] with couttype = "MANNING" – model FlowLakeOutletManning.

invert

Any required user source

Channel invert elevation [L].

width

Any required user source

Channel width [L].

rough

float required user source

Manning roughness coefficient n (> 0).

slope

float required user source

Channel bed slope (> 0).

lakeout

int default = 0 user source

Downstream destination lake (1-based). 0 = external boundary (the discharge leaves the model).

mover in TOML: [flow.sinks_sources.lakes.<id>.outlets.mover]

FlowLakeOutletMover | None default = None user source

Optional controlled LAK -> LAK transfer routed through MVR (keep lakeout = 0 when a mover is set).

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

SPECIFIED

TOML: [[flow.sinks_sources.lakes.<id>.outlets]] with couttype = "SPECIFIED" – model FlowLakeOutletSpecified.

rate

Optional[Any] default = None user source

Constant specified outlet rate [L^3/T], signed (+in, -out).

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

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

Optional transient release schedule resolved at runtime.

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

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

lakeout

int default = 0 user source

Downstream destination lake (1-based). 0 = external boundary (the discharge leaves the model).

mover in TOML: [flow.sinks_sources.lakes.<id>.outlets.mover]

FlowLakeOutletMover | None default = None user source

Optional controlled LAK -> LAK transfer routed through MVR (keep lakeout = 0 when a mover is set).

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

cutoff_wall in TOML: [flow.sinks_sources.lakes.<id>.cutoff_wall]

FlowBarrierConfig | None default = None user source

Optional dam cutoff wall / grout curtain on the dam axis, modeled as a MODFLOW 6 HFB (the lake-derived use of FlowBarrierConfig). The barrier forces the under-dam seepage to dive below the wall instead of leaking through the top layers.

Fields of FlowBarrierConfig

auto

bool default = False user source

Auto-place the dam cutoff wall (lakes only): the trace is derived at bind time as the chord across the reservoir at its downstream neck (the footprint point nearest the catchment outlet), perpendicular to the outlet-flow direction. Mutually exclusive with line / line_path; the mesh dam refinement then follows this auto axis too.

line

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

Inline barrier-trace vertices [(x, y), …] in the project CRS. Mutually exclusive with line_path and auto.

line_path

Path | None default = None user source

Barrier-trace file: a vector polyline (gpkg / shp / GeoJSON) or a CSV of ordered x,y (or lon,lat) vertices. A bare filename resolves against <workspace>/data/cutoff_wall/. Alternative to line and auto.

depths

list[float] | None default = None user source

Barrier depth [m] below the top (or below crest_elevation). One value is uniform; several are interpolated per vertex along the trace. The HFB blocks every layer down to this depth. Mutually exclusive with base_elevation.

crest_elevation

float | None default = None user source

Absolute TOP elevation of the barrier [m, model datum]; defaults to the cell top (the DEM). Set it when the barrier crest sits below the DEM top.

base_elevation

float | None default = None user source

Absolute BOTTOM elevation of the barrier [m, model datum]. When set, the HFB spans [base_elevation, crest_elevation or top] and blocks EVERY layer in that band. Use it to make a full-height dam impervious: the concrete body plus the grout curtain block all flow from the crest down to the curtain foot (e.g. base_elevation = 41 m), so nothing seeps across the dam above that. Mutually exclusive with depths.

hydchr

float | None default = None user source

HFB hydraulic characteristic [1/T] = K_barrier / thickness_barrier. A near-zero value (e.g. 1e-9 1/s) is a quasi-impermeable wall. Mutually exclusive with k + thickness.

hydchr_unit

str default = “1/s” user source

Unit of hydchr (1/T): 1/s, 1/day, 1/h, 1/min. Converted to 1/s for MF6.

k

float | None default = None user source

Barrier hydraulic conductivity [L/T]; used with thickness when hydchr is unset.

k_unit

str default = “m/s” user source

Unit of k (L/T): m/s, m/day, m/h, m/min. Converted to m/s.

thickness

float | None default = None user source

Barrier thickness [L]; used with k when hydchr is unset.

thickness_unit

str default = “m” user source

Unit of thickness (L): m, cm, mm, km. Converted to m.

rainfall in TOML: [flow.sinks_sources.lakes.<id>.rainfall]

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

Optional rainfall rate forcing [L/T] (per unit lake surface).

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

constant

TOML: [flow.sinks_sources.lakes.<id>.rainfall] with kind = "constant" – model FlowWellForcingConstantConfig.

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.lakes.<id>.rainfall] with kind = "csv" – model FlowWellForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

piecewise

TOML: [flow.sinks_sources.lakes.<id>.rainfall] with kind = "piecewise" – model FlowWellForcingPiecewiseConfig.

segments in TOML: [[flow.sinks_sources.lakes.<id>.rainfall.segments]]

list[FlowWellForcingSegment] required user source

Date-ordered segments covering the simulation window.

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

units

str | None default = None dev source

Source units of segment values before runtime conversion.

seasonal

TOML: [flow.sinks_sources.lakes.<id>.rainfall] with kind = "seasonal" – model FlowWellForcingSeasonalConfig.

by_month in TOML: [flow.sinks_sources.lakes.<id>.rainfall.by_month.<id>]

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

Mapping of calendar month (1-12) to a forcing value.

by_season in TOML: [flow.sinks_sources.lakes.<id>.rainfall.by_season.<id>]

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

Mapping of meteorological season (DJF/MAM/JJA/SON) to a forcing value.

units

str | None default = None dev source

Source units of seasonal values before runtime conversion.

evaporation in TOML: [flow.sinks_sources.lakes.<id>.evaporation]

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

Optional open-water evaporation rate forcing [L/T].

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

constant

TOML: [flow.sinks_sources.lakes.<id>.evaporation] with kind = "constant" – model FlowWellForcingConstantConfig.

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.lakes.<id>.evaporation] with kind = "csv" – model FlowWellForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

piecewise

TOML: [flow.sinks_sources.lakes.<id>.evaporation] with kind = "piecewise" – model FlowWellForcingPiecewiseConfig.

segments in TOML: [[flow.sinks_sources.lakes.<id>.evaporation.segments]]

list[FlowWellForcingSegment] required user source

Date-ordered segments covering the simulation window.

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

units

str | None default = None dev source

Source units of segment values before runtime conversion.

seasonal

TOML: [flow.sinks_sources.lakes.<id>.evaporation] with kind = "seasonal" – model FlowWellForcingSeasonalConfig.

by_month in TOML: [flow.sinks_sources.lakes.<id>.evaporation.by_month.<id>]

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

Mapping of calendar month (1-12) to a forcing value.

by_season in TOML: [flow.sinks_sources.lakes.<id>.evaporation.by_season.<id>]

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

Mapping of meteorological season (DJF/MAM/JJA/SON) to a forcing value.

units

str | None default = None dev source

Source units of seasonal values before runtime conversion.

runoff in TOML: [flow.sinks_sources.lakes.<id>.runoff]

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

Optional runoff forcing, volumetric [L^3/T].

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

constant

TOML: [flow.sinks_sources.lakes.<id>.runoff] with kind = "constant" – model FlowWellForcingConstantConfig.

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.lakes.<id>.runoff] with kind = "csv" – model FlowWellForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

piecewise

TOML: [flow.sinks_sources.lakes.<id>.runoff] with kind = "piecewise" – model FlowWellForcingPiecewiseConfig.

segments in TOML: [[flow.sinks_sources.lakes.<id>.runoff.segments]]

list[FlowWellForcingSegment] required user source

Date-ordered segments covering the simulation window.

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

units

str | None default = None dev source

Source units of segment values before runtime conversion.

seasonal

TOML: [flow.sinks_sources.lakes.<id>.runoff] with kind = "seasonal" – model FlowWellForcingSeasonalConfig.

by_month in TOML: [flow.sinks_sources.lakes.<id>.runoff.by_month.<id>]

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

Mapping of calendar month (1-12) to a forcing value.

by_season in TOML: [flow.sinks_sources.lakes.<id>.runoff.by_season.<id>]

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

Mapping of meteorological season (DJF/MAM/JJA/SON) to a forcing value.

units

str | None default = None dev source

Source units of seasonal values before runtime conversion.

inflow in TOML: [flow.sinks_sources.lakes.<id>.inflow]

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

Optional inflow forcing, volumetric [L^3/T].

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

constant

TOML: [flow.sinks_sources.lakes.<id>.inflow] with kind = "constant" – model FlowWellForcingConstantConfig.

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.lakes.<id>.inflow] with kind = "csv" – model FlowWellForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

piecewise

TOML: [flow.sinks_sources.lakes.<id>.inflow] with kind = "piecewise" – model FlowWellForcingPiecewiseConfig.

segments in TOML: [[flow.sinks_sources.lakes.<id>.inflow.segments]]

list[FlowWellForcingSegment] required user source

Date-ordered segments covering the simulation window.

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

units

str | None default = None dev source

Source units of segment values before runtime conversion.

seasonal

TOML: [flow.sinks_sources.lakes.<id>.inflow] with kind = "seasonal" – model FlowWellForcingSeasonalConfig.

by_month in TOML: [flow.sinks_sources.lakes.<id>.inflow.by_month.<id>]

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

Mapping of calendar month (1-12) to a forcing value.

by_season in TOML: [flow.sinks_sources.lakes.<id>.inflow.by_season.<id>]

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

Mapping of meteorological season (DJF/MAM/JJA/SON) to a forcing value.

units

str | None default = None dev source

Source units of seasonal values before runtime conversion.

withdrawal in TOML: [flow.sinks_sources.lakes.<id>.withdrawal]

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

Optional withdrawal forcing, volumetric [L^3/T].

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

constant

TOML: [flow.sinks_sources.lakes.<id>.withdrawal] with kind = "constant" – model FlowWellForcingConstantConfig.

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.lakes.<id>.withdrawal] with kind = "csv" – model FlowWellForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

piecewise

TOML: [flow.sinks_sources.lakes.<id>.withdrawal] with kind = "piecewise" – model FlowWellForcingPiecewiseConfig.

segments in TOML: [[flow.sinks_sources.lakes.<id>.withdrawal.segments]]

list[FlowWellForcingSegment] required user source

Date-ordered segments covering the simulation window.

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

units

str | None default = None dev source

Source units of segment values before runtime conversion.

seasonal

TOML: [flow.sinks_sources.lakes.<id>.withdrawal] with kind = "seasonal" – model FlowWellForcingSeasonalConfig.

by_month in TOML: [flow.sinks_sources.lakes.<id>.withdrawal.by_month.<id>]

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

Mapping of calendar month (1-12) to a forcing value.

by_season in TOML: [flow.sinks_sources.lakes.<id>.withdrawal.by_season.<id>]

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

Mapping of meteorological season (DJF/MAM/JJA/SON) to a forcing value.

units

str | None default = None dev source

Source units of seasonal values before runtime conversion.

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

dict[str, FlowReachNetworkConfig] factory user source

Mapping of stream-network ids to typed SFR payloads.

Fields of FlowReachNetworkConfig

stream_threshold_km2

float | None default = None user source

Drainage-area threshold [km^2] for stream initiation. Exactly one of stream_threshold_km2 / stream_threshold_cells must be set when reaches are delineated automatically.

stream_threshold_cells

int | None default = None user source

Alternative stream-initiation threshold as a flow-accumulation cell count.

min_reach_length

Any default = “0 m” user source

Prune reaches shorter than this [L] (0 keeps all reaches).

manning

float default = 0.035 user source

Manning roughness coefficient n [T/L^(1/3)] (> 0). Default 0.035.

streambed_k

float default = 1e-06 user source

Streambed hydraulic conductivity rhk [L/T]. 0 = no reach-aquifer leakage (pure routing).

streambed_k_unit

str default = “m/s” user source

Unit of streambed_k (velocity, L/T): m/s, m/day, m/h… HydroModPy converts it to m/s for MF6, so a m/day value is not taken as m/s.

streambed_thickness

Any default = “1 m” user source

Streambed thickness rbth [L] (> 0).

min_slope

float default = 0.0001 user source

Floor for the reach gradient rgrd [-] after monotone-downhill conditioning.

bed_incision

Optional[Any] default = None user source

Depth [L] of the streambed top rtp below the top of the reach’s OWN aquifer cell. A bed never sits above the ground of its own cell, whether this is set or not. None (default) only lifts the lower bound: the bed may then sink to the cell bottom instead of stopping at max_bed_sag. When set, each reach is solved inside [cell_top - bed_incision - max_bed_sag, cell_top - bed_incision], monotone downstream, and the build refuses when that band is empty. rtp is delineated on the model top, so this anchors a bed that a coarse DEM cannot resolve; it is not a correction for the stream burn, which never reaches the bed. Pick it against the water table, not against the channel: MODFLOW 6 switches a reach between connected and disconnected at rtp minus streambed_thickness (gwf-sfr.f90:3973-3985), so a bed sitting near the seasonal water-table depth toggles at every outer iteration.

max_bed_sag

Any default = “5 m” expert source

Only read when bed_incision is set. How far [L] below cell_top - bed_incision the monotone-downstream solve may sink a reach. It bounds the cumulative descent that a traced channel climbing over a rise forces on everything downstream of it. Widening it never refuses the build on its own: a reach that cannot hold the descent is warned about and pinned to the floor.

width in TOML: [flow.sinks_sources.sfr.<id>.width]

kind = “constant” | “by_order” | “power_law” factory user source

How the reach width rwid [L] is set (constant / by_order / power_law).

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

constant

TOML: [flow.sinks_sources.sfr.<id>.width] with kind = "constant" – model FlowReachWidthConstant.

value

Any required user source

Uniform reach width rwid [L] for all reaches.

by_order

TOML: [flow.sinks_sources.sfr.<id>.width] with kind = "by_order" – model FlowReachWidthByOrder.

widths in TOML: [flow.sinks_sources.sfr.<id>.width.widths.<id>]

dict[int, Any] required user source

Reach width rwid [L] per Strahler order (e.g. {1: ‘1 m’, 2: ‘3 m’}).

power_law

TOML: [flow.sinks_sources.sfr.<id>.width] with kind = "power_law" – model FlowReachWidthPowerLaw.

coef

float required user source

Coefficient [m] of the width power law (> 0).

exp

float default = 0.5 user source

Exponent of the drainage-area (km^2) power law. Typical ~0.5.

connected_to_aquifer

bool default = True user source

If False every reach uses cellid ‘none’ (routing only, no streambed leakage).

route_drainage

bool default = False user source

Route the hillslope drainage (DRN) discharge into the stream network: every remaining DRN cell hands its outflow to the NEAREST reach through an MVR record (FACTOR 1.0) instead of leaving the model. This is the surface re-infiltration / runon convergence of drained water towards the river; without it only the reach cells’ streambed captures baseflow and the rest of the catchment discharge is lost.

storage

bool default = False user source

Enable the channel-storage term (transient first period / SIMPLE only).

headwater_inflow in TOML: [flow.sinks_sources.sfr.<id>.headwater_inflow]

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

External inflow [L^3/T] injected at the headwater reach(es).

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

constant

TOML: [flow.sinks_sources.sfr.<id>.headwater_inflow] with kind = "constant" – model FlowWellForcingConstantConfig.

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.sfr.<id>.headwater_inflow] with kind = "csv" – model FlowWellForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

piecewise

TOML: [flow.sinks_sources.sfr.<id>.headwater_inflow] with kind = "piecewise" – model FlowWellForcingPiecewiseConfig.

segments in TOML: [[flow.sinks_sources.sfr.<id>.headwater_inflow.segments]]

list[FlowWellForcingSegment] required user source

Date-ordered segments covering the simulation window.

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

units

str | None default = None dev source

Source units of segment values before runtime conversion.

seasonal

TOML: [flow.sinks_sources.sfr.<id>.headwater_inflow] with kind = "seasonal" – model FlowWellForcingSeasonalConfig.

by_month in TOML: [flow.sinks_sources.sfr.<id>.headwater_inflow.by_month.<id>]

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

Mapping of calendar month (1-12) to a forcing value.

by_season in TOML: [flow.sinks_sources.sfr.<id>.headwater_inflow.by_season.<id>]

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

Mapping of meteorological season (DJF/MAM/JJA/SON) to a forcing value.

units

str | None default = None dev source

Source units of seasonal values before runtime conversion.

runoff in TOML: [flow.sinks_sources.sfr.<id>.runoff]

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

Diffuse overland inflow [L^3/T], distributed per reach by length.

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

constant

TOML: [flow.sinks_sources.sfr.<id>.runoff] with kind = "constant" – model FlowWellForcingConstantConfig.

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.sfr.<id>.runoff] with kind = "csv" – model FlowWellForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

piecewise

TOML: [flow.sinks_sources.sfr.<id>.runoff] with kind = "piecewise" – model FlowWellForcingPiecewiseConfig.

segments in TOML: [[flow.sinks_sources.sfr.<id>.runoff.segments]]

list[FlowWellForcingSegment] required user source

Date-ordered segments covering the simulation window.

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

units

str | None default = None dev source

Source units of segment values before runtime conversion.

seasonal

TOML: [flow.sinks_sources.sfr.<id>.runoff] with kind = "seasonal" – model FlowWellForcingSeasonalConfig.

by_month in TOML: [flow.sinks_sources.sfr.<id>.runoff.by_month.<id>]

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

Mapping of calendar month (1-12) to a forcing value.

by_season in TOML: [flow.sinks_sources.sfr.<id>.runoff.by_season.<id>]

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

Mapping of meteorological season (DJF/MAM/JJA/SON) to a forcing value.

units

str | None default = None dev source

Source units of seasonal values before runtime conversion.

rainfall in TOML: [flow.sinks_sources.sfr.<id>.rainfall]

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

Rainfall rate [L/T] on the reach surface.

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

constant

TOML: [flow.sinks_sources.sfr.<id>.rainfall] with kind = "constant" – model FlowWellForcingConstantConfig.

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.sfr.<id>.rainfall] with kind = "csv" – model FlowWellForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

piecewise

TOML: [flow.sinks_sources.sfr.<id>.rainfall] with kind = "piecewise" – model FlowWellForcingPiecewiseConfig.

segments in TOML: [[flow.sinks_sources.sfr.<id>.rainfall.segments]]

list[FlowWellForcingSegment] required user source

Date-ordered segments covering the simulation window.

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

units

str | None default = None dev source

Source units of segment values before runtime conversion.

seasonal

TOML: [flow.sinks_sources.sfr.<id>.rainfall] with kind = "seasonal" – model FlowWellForcingSeasonalConfig.

by_month in TOML: [flow.sinks_sources.sfr.<id>.rainfall.by_month.<id>]

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

Mapping of calendar month (1-12) to a forcing value.

by_season in TOML: [flow.sinks_sources.sfr.<id>.rainfall.by_season.<id>]

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

Mapping of meteorological season (DJF/MAM/JJA/SON) to a forcing value.

units

str | None default = None dev source

Source units of seasonal values before runtime conversion.

evaporation in TOML: [flow.sinks_sources.sfr.<id>.evaporation]

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

Open-channel evaporation rate [L/T] (positive, subtracted).

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

constant

TOML: [flow.sinks_sources.sfr.<id>.evaporation] with kind = "constant" – model FlowWellForcingConstantConfig.

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.sfr.<id>.evaporation] with kind = "csv" – model FlowWellForcingCsvConfig.

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

str default = “ffill” dev source

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

One of: "ffill" "bfill"

aggregate

str default = “mean” dev source

Stress-period aggregation method.

One of: "mean" "last"

units

str | None default = None dev source

Source units of CSV values before runtime conversion.

piecewise

TOML: [flow.sinks_sources.sfr.<id>.evaporation] with kind = "piecewise" – model FlowWellForcingPiecewiseConfig.

segments in TOML: [[flow.sinks_sources.sfr.<id>.evaporation.segments]]

list[FlowWellForcingSegment] required user source

Date-ordered segments covering the simulation window.

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

units

str | None default = None dev source

Source units of segment values before runtime conversion.

seasonal

TOML: [flow.sinks_sources.sfr.<id>.evaporation] with kind = "seasonal" – model FlowWellForcingSeasonalConfig.

by_month in TOML: [flow.sinks_sources.sfr.<id>.evaporation.by_month.<id>]

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

Mapping of calendar month (1-12) to a forcing value.

by_season in TOML: [flow.sinks_sources.sfr.<id>.evaporation.by_season.<id>]

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

Mapping of meteorological season (DJF/MAM/JJA/SON) to a forcing value.

units

str | None default = None dev source

Source units of seasonal values before runtime conversion.

reaches in TOML: [[flow.sinks_sources.sfr.<id>.reaches]]

list[FlowReachConfig] | None default = None dev source

Explicit reach table; bypasses delineation. None = delineate from the DEM.

Fields of FlowReachConfig

cell in TOML: [flow.sinks_sources.sfr.<id>.reaches.cell]

kind = “cell” | “absolute_xy” | “relative_xy” default = None user source

DISV cell the reach exchanges with (streambed leakage). None = no aquifer connection (cellid ‘none’, pure routing).

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

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

length

Any required user source

Reach length rlen [L].

width

Any required user source

Reach width rwid [L].

slope

float required user source

Reach gradient rgrd [-] (> 0).

top

Any required user source

Streambed top rtp [L].

upstream

list[int] factory user source

1-based ids of reaches whose downstream end feeds this reach.

downstream

list[int] factory user source

1-based ids of reaches this reach feeds.

ustrf

float default = 1.0 user source

Upstream fraction routed to this reach (siblings must sum to 1.0).

diversions in TOML: [[flow.sinks_sources.sfr.<id>.diversions]]

list[FlowReachDiversionConfig] factory user source

SFR-to-SFR diversions (controlled splits). Empty = none.

Fields of FlowReachDiversionConfig

reach

int required user source

Source reach (1-based) the diversion leaves from.

to_reach

int required user source

Receiver reach (1-based); must be a downstream connection of reach.

cprior

str default = “FRACTION” user source

Diversion priority rule (FRACTION / EXCESS / THRESHOLD / UPTO).

One of: "FRACTION" "EXCESS" "THRESHOLD" "UPTO"

divflow in TOML: [flow.sinks_sources.sfr.<id>.diversions.divflow]

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

Per-period diversion flow [L^3/T] (or fraction for FRACTION).

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

Nested structure truncated at depth 3. See :doc:`config_index` for the complete TOML path listing.

outflow_to_lake

int | None default = None user source

1-based lake number the terminal reach feeds via MVR (SFR -> LAK). None = the network outflow leaves the model (EXT-OUTFLOW).

outflow_mvrtype

str default = “FACTOR” user source

MVR transfer rule for the SFR -> LAK coupling.

One of: "FACTOR" "UPTO" "EXCESS" "THRESHOLD"

outflow_value

float default = 1.0 user source

MVR value: the fraction for FACTOR, or the flow rate [L^3/T] for UPTO / EXCESS / THRESHOLD.

lake_feeder_snap

Any default = “300 m” expert source

Max distance from a lake shoreline within which a dead-end reach is snapped to that lake via MVR (a real feeder the DEM fell short of). Scale it to the catchment: too large teleports an unrelated reach into the lake.

outlet_keepout

Any default = “1000 m” expert source

Min distance from the model outlet a terminal reach must keep to count as a lake feeder. A terminal closer than this is the below-dam discharge reach (the lake feeds it and it leaves the model), so it is not routed into the lake.

rectify_on_mesh

bool default = False expert source

Re-derive the delineated reach cells as a clean single-flow-direction (SFD) channel on the DISV mesh. From every delineated cell the steepest descent of the (conditioned) mesh top is traced one face-neighbour at a time until it reaches a lake, the domain edge, or an already-traced cell; a residual pit or flat spill is crossed by stepping to the lowest unvisited rim. The union of those paths is the channel: one cell wide (a single downstream per cell, so no braiding), face-continuous (no geometric gap), following the true thalweg (so the surface flow follows the reach), and always reaching a real sink (no inland dead-end that leaks its flow out). Requires [modflow6.sgrid] condition_top = true so every cell has a descending path.

rectify_stub_max_upstream

int default = 2 expert source

When rectify_on_mesh is set, demote a low-order parallel stub to hillslope drainage (DRN -> SFR) to thin braided bands: a reach cell with at most this many reach cells upstream of it that runs beside a reach carrying strictly more (the true channel) is dropped from SFR, keeping a one-thread channel; its water still reaches the network as routed drainage. 0 demotes only headwater leaves, a negative value keeps every traced cell. Default 2 removes stubs up to ~3 cells.

rectify_min_component_cells

int default = 2 expert source

When rectify_on_mesh is set, drop a whole reach component smaller than this many cells (a lone one-cell stream that just touches a lake or the outlet is hillslope drainage, not a channel, and reads as a spurious SFR -> lake entry). Its water still reaches the network as routed DRN. Default 2 drops single-cell components; 1 keeps every component.

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

dict[str, FlowBarrierConfig] factory user source

Mapping of flow-barrier ids to typed HFB payloads (general addon, modflow6 backend only; declaring one activates it). A lake’s dam cutoff wall is declared on the lake instead.

Fields of FlowBarrierConfig

auto

bool default = False user source

Auto-place the dam cutoff wall (lakes only): the trace is derived at bind time as the chord across the reservoir at its downstream neck (the footprint point nearest the catchment outlet), perpendicular to the outlet-flow direction. Mutually exclusive with line / line_path; the mesh dam refinement then follows this auto axis too.

line

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

Inline barrier-trace vertices [(x, y), …] in the project CRS. Mutually exclusive with line_path and auto.

line_path

Path | None default = None user source

Barrier-trace file: a vector polyline (gpkg / shp / GeoJSON) or a CSV of ordered x,y (or lon,lat) vertices. A bare filename resolves against <workspace>/data/cutoff_wall/. Alternative to line and auto.

depths

list[float] | None default = None user source

Barrier depth [m] below the top (or below crest_elevation). One value is uniform; several are interpolated per vertex along the trace. The HFB blocks every layer down to this depth. Mutually exclusive with base_elevation.

crest_elevation

float | None default = None user source

Absolute TOP elevation of the barrier [m, model datum]; defaults to the cell top (the DEM). Set it when the barrier crest sits below the DEM top.

base_elevation

float | None default = None user source

Absolute BOTTOM elevation of the barrier [m, model datum]. When set, the HFB spans [base_elevation, crest_elevation or top] and blocks EVERY layer in that band. Use it to make a full-height dam impervious: the concrete body plus the grout curtain block all flow from the crest down to the curtain foot (e.g. base_elevation = 41 m), so nothing seeps across the dam above that. Mutually exclusive with depths.

hydchr

float | None default = None user source

HFB hydraulic characteristic [1/T] = K_barrier / thickness_barrier. A near-zero value (e.g. 1e-9 1/s) is a quasi-impermeable wall. Mutually exclusive with k + thickness.

hydchr_unit

str default = “1/s” user source

Unit of hydchr (1/T): 1/s, 1/day, 1/h, 1/min. Converted to 1/s for MF6.

k

float | None default = None user source

Barrier hydraulic conductivity [L/T]; used with thickness when hydchr is unset.

k_unit

str default = “m/s” user source

Unit of k (L/T): m/s, m/day, m/h, m/min. Converted to m/s.

thickness

float | None default = None user source

Barrier thickness [L]; used with k when hydchr is unset.

thickness_unit

str default = “m” user source

Unit of thickness (L): m, cm, mm, km. Converted to m.

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

str 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).

One of: "auto" "homogeneous" "heterogeneous"

interpolation_method

str default = “nearest” dev source

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

One of: "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

str default = “auto” dev source

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

One of: "auto" "homogeneous" "heterogeneous"

interpolation_method

str default = “nearest” dev source

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

One of: "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’, ‘lake’, ‘reservoir’. ‘lake’/’reservoir’ build a MODFLOW 6 LAK advanced package and are only supported by the modflow6 backend. An empty list means no boundary-condition package is assembled by the solver.

Examples

• ["ocean"]

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

flow_regime

str default = “transient” user source

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

One of: "steady" "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

restart_from

str | None default = None user source

Optional hotstart: path to a prior simulation Zarr store whose last time step seeds the initial heads (and the lake stage), overriding [flow.ic]. The prior run must share this run’s mesh, so enable [mesh_catchment] cache = true; otherwise the cell count differs and restart is refused. None keeps [flow.ic]. Read only by a backend that declares it can: elsewhere the run is refused rather than started from [flow.ic] without a word. This is one of the four ways to say where a transient starts, next to [flow.ic] type=’steady_state’ (equilibrium under the mean recharge, or under a rate you state with source=’prescribed’), type=’custom’/’top’/’bottom’ (a level you write), and hmp spinup (repeat a representative window until the state stops moving, then point this key at its result).

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
# restart_from = ...  # default = None

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

[flow.sinks_sources]
# wells = ...  # factory default
# lakes = ...  # factory default
# sfr = ...  # factory default
# flow_barriers = ...  # 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.