[modflow6] Modflow6Config#
TOML section: [modflow6]
Pydantic model: Modflow6Config defined in hydromodpy.solver.modflow6.modflow6_config.
Expert-level MODFLOW 6 configuration organized by concern.
Fields#
runtime
in TOML:
[modflow6.runtime]
Modflow6RuntimeConfig factory expert source
MODFLOW 6 runtime options.
Fields of Modflow6RuntimeConfig
ims_print_option
str default = “NONE” expert source
IMS PRINT_OPTION. ‘SUMMARY’ adds one line per time step to the listing with the outer and inner iteration counts, which is the only way to tell an expensive iteration from too many of them. Deliberately NOT tied to mf_verbose: that switch also sets print_input and print_flows on the whole model, and on a run with one drain per cell those print every boundary flux at every step. ‘NONE’ by default; ‘SUMMARY’ costs a line per step.
One of: "NONE" "SUMMARY" "ALL"
print_head
bool default = False expert source
Re-print the whole head field, formatted as text, into the model listing at every output step. Nothing in the package reads it, and the binary head file already carries the same numbers. It costs DISK, not time: measured on the Nancon at 25 m, 243 552 cells over 1826 daily steps wrote a 2.96 GB listing, but a one-variable-at-a-time probe put its effect on the solve at -0.4 per cent, inside the noise. Default false to stop producing the file, not to go faster. The listing keeps its budget summaries and its convergence reports either way, and Mf6ListBudget reads those.
save_specific_discharge
bool default = True expert source
Compute and write the cell-by-cell Darcy velocity (DATA-SPDIS). Required by particle tracking and by any velocity figure. The cost is the COMPUTATION, not the write: MODFLOW interpolates a velocity vector per cell at every step. Measured on the Nancon at 25 m by changing this switch alone, 4.64 -> 3.68 s per step, 20.7 per cent of the solve. A calibration that only scores a discharge series should turn it off.
save_saturation
bool default = True expert source
Compute and write the cell saturation (DATA-SAT). Measured on the Nancon at 25 m by changing this switch alone, 4.64 -> 4.13 s per step, 10.9 per cent of the solve. Same reasoning as save_specific_discharge: the cost is the per-cell computation, and the two together are worth 34.5 per cent.
mf6_runner
str default = “subprocess” expert source
MODFLOW 6 solve dispatch: ‘subprocess’ runs the mf6 executable, ‘api’ drives libmf6 via the optional modflowapi package. Both write the same simulation, so output extraction is identical.
One of: "subprocess" "api"
mf6_api_timeout_s
Optional[float] default = None expert source
Wall-clock budget (seconds) for an isolated libmf6 (‘api’ runner) solve in parallel calibration; the child is killed past it so one stuck trial cannot wedge the session. None keeps the built-in default (2400 s).
mf6_ims_complexity
str default = “COMPLEX” expert source
IMS complexity preset for MODFLOW 6: SIMPLE, MODERATE, or COMPLEX.
One of: "SIMPLE" "MODERATE" "COMPLEX"
mf_verbose
bool default = False expert source
Enable verbose FloPy logging for MODFLOW 6 setup and execution.
mf6_outer_dvclose
float default = 0.0001 expert source
IMS outer-iteration head-change convergence criterion.
mf6_inner_dvclose
float default = 0.0001 expert source
IMS inner-iteration head-change convergence criterion.
mf6_inner_rclose
Optional[float] default = None expert source
IMS inner-iteration flow-residual closure (L^3/T in run units). None keeps the complexity-preset default.
mf6_linear_acceleration
Optional[str] default = None expert source
IMS linear acceleration: CG for symmetric matrices, BICGSTAB for the non-symmetric Newton formulation. None keeps the preset default.
One of: "CG" "BICGSTAB"
mf6_under_relaxation
Optional[str] default = None expert source
IMS non-linear under-relaxation scheme. DBD is recommended with Newton. None keeps the preset default.
One of: "NONE" "SIMPLE" "COOLEY" "DBD"
mf6_enable_rewet
bool | None default = None expert source
Enable NPF cell rewetting. When left to None, HydroModPy keeps rewetting disabled unless explicitly enabled.
mf6_newton
bool default = True expert source
Enable the MODFLOW 6 Newton-Raphson formulation. Catchment cells are always convertible (unconfined), so Newton with under-relaxation is the robust default and matches the MODFLOW-NWT backend.
mf6_newton_under_relaxation
bool default = True expert source
Enable MODFLOW 6 Newton under-relaxation when mf6_newton is true.
mf6_ats
bool default = False expert source
Enable MODFLOW 6 adaptive time stepping (ATS) on transient periods. Each stress period starts at its full length and MF6 subdivides only the periods the solver cannot converge in one step (e.g. littoral wet/dry under Newton), instead of carrying budget error at nstp=1. When on, OC saves per period end so the extraction still sees one record per period. Default off (baseline).
mf6_ats_dtmin_s
float default = 60.0 expert source
Minimum ATS time step in seconds (only used when mf6_ats is true).
mf6_enable_xt3d
bool | None default = None expert source
Enable MF6 NPF XT3D terms. When left to None, XT3D is auto-enabled only when the mesh is significantly non-orthogonal or anisotropic K is configured; the default Voronoi/PEBI dual grid is near-orthogonal, so XT3D stays off there. It adds cost but improves accuracy on non-orthogonal or anisotropic grids.
mf6_rewet_wetdry
float default = 0.1 expert source
MF6 NPF WETDRY threshold used when rewetting is active.
process_specific
in TOML:
[modflow6.process_specific]
Modflow6ProcessSpecificConfig factory expert source
Process-specific controls for MODFLOW 6 flow packages.
Fields of Modflow6ProcessSpecificConfig
vka
float default = 1.0 expert source
Uniform vertical anisotropy ratio kh/kv (dimensionless, > 0); k33 = k / vka. Default 1.0 is vertically isotropic. For spatial control declare a per-cell ‘Kv’ flow parameter instead, which is mutually exclusive with a non-unit vka and is a direct conductivity, never a mode-switched value. Vertical anisotropy is grid-aligned and needs no XT3D; a horizontal K22 field or an angle (not exposed here) would auto-activate XT3D.
evt_extinction_depth
float default = 1.0 expert source
Meters; extinction depth for the EVT sink used when recharge negatives are routed to EVT. The routed deficit tapers linearly from the cell top to this depth and stops below it, so a sustained climatic deficit can saturate near this value.
lak_forcing_mode
str default = “auto” expert source
How time-varying LAK forcings are written. ‘inline’ expands values into the LAK PERIOD block, emitting one row per stress period whenever the value changes. ‘ts6’ always routes non-constant forcings to external MF6 TS6 files. ‘auto’ keeps constant/short forcings inline and routes only genuinely long series (nper > ts6_min_periods) to TS6.
One of: "auto" "inline" "ts6"
ts6_min_periods
int default = 120 expert source
Period count above which ‘auto’ mode offloads a non-constant LAK forcing to a TS6 file.
sgrid
in TOML:
[modflow6.sgrid]
SolverSGridConfig factory user source
Solver-grid payload split into planar and vertical sections.
Fields of SolverSGridConfig
planar
in TOML:
[modflow6.sgrid.planar]
PlanarGridConfig factory user source
Planar discretization of the solver grid.
Fields of PlanarGridConfig
mode
str default = “keep_native” user source
Planar solver-grid mode: keep the native domain support or resample to an explicit (ny, nx) target shape.
"keep_native"Keeps the top raster’s native shape and resolution, no resampling.
"resample_to_shape"Resamples top and bottom onto an explicit (ny, nx) grid, keeping the same extent.
nx
Optional[int] default = None user source
Target number of columns when planar mode is ‘resample_to_shape’.
ny
Optional[int] default = None user source
Target number of rows when planar mode is ‘resample_to_shape’.
resampling
str default = “bilinear” dev source
Resampling rule applied when planar mode is ‘resample_to_shape’.
One of: "bilinear" "average" "nearest"
vertical
in TOML:
[modflow6.sgrid.vertical]
VerticalGridConfig factory user source
Vertical layering of the solver grid.
Fields of VerticalGridConfig
genmtd_lay
str default = “constant” user source
Vertical-layering strategy.
"constant"Splits local thickness into nlay equal-fraction layers at every cell.
"decay"Grows layer thickness geometrically with depth when lay_decay is above one.
"list"Uses the explicit per-layer thickness fractions given in lay_proportions.
nlay
int | None default = 1 user source
Number of layers (required for constant/decay, ignored for list).
lay_proportions
list[float] | None default = None dev source
Explicit layer fractions when genmtd_lay=’list’ (must sum to 1).
grid_dual
str default = “voronoi” user source
Applies only to a MODFLOW 6 run on a runtime gmsh mesh; ignored for structured grids, MODFLOW-NWT and Boussinesq (which keeps its own triangulation). ‘voronoi’ uses the PEBI dual (exact CVFD orthogonality, ~half the cells) and is the default; ‘triangle’ keeps the triangulation cells as the DISV grid for simplex comparison runs.
One of: "voronoi" "triangle"
condition_top
bool default = False user source
MODFLOW 6 runtime-mesh only. Hydro-condition the DISV mesh top so it holds no closed depression. Sampling the DEM at irregular Voronoi cell centroids reintroduces local minima (pits) the raster fill removed. When true, a priority-flood epsilon fill on the mesh face graph raises only pit cells to their spill level, giving every active non-lake cell a strictly descending path to the domain boundary. Lake and boundary cells are fixed base levels; the aquifer bottom is untouched. Default false keeps the raw projected top.
condition_top_epsilon
float default = 0.001 user source
Minimal downhill increment (m) added along each filled path so conditioned cells strictly descend instead of forming flats. Only used when condition_top is true.
top_sampling
in TOML:
[modflow6.sgrid.top_sampling]
TopSamplingConfig factory user source
How the runtime-mesh top is sampled from the DEM before conditioning.
Fields of TopSamplingConfig
mode
str default = “centroid” user source
Top-sampling strategy. ‘centroid’ samples the DEM at each cell generator (fast, the current behaviour, byte-identical default). ‘zonal’ reduces every DEM pixel inside a cell with per-class stats.
One of: "centroid" "zonal"
hillslope_stat
str default = “median” user source
Zonal statistic over non-channel (hillslope) pixels inside a cell.
"mean"Averages every hillslope pixel in the cell to set its top elevation.
"median"Uses the median hillslope pixel elevation, robust to outlier pixels.
"min"Uses the lowest hillslope pixel elevation found inside the cell.
"max"Uses the highest hillslope pixel elevation found inside the cell.
"p10"Uses the 10th percentile of hillslope pixel elevations inside the cell.
"p25"Uses the 25th percentile of hillslope pixel elevations inside the cell.
channel_stat
str default = “min” user source
Zonal statistic over channel pixels inside a cell (thalweg-preserving; ‘min’ keeps the incised low).
"min"Uses the lowest channel pixel elevation, keeping the incised thalweg low.
"p10"Uses the 10th percentile of channel pixel elevations, near the thalweg low.
"p25"Uses the 25th percentile of channel pixel elevations, above the thalweg low.
"median"Uses the median channel pixel elevation, less aggressive than the thalweg low.
"mean"Averages channel pixel elevations, smoothing over the incised thalweg.
channel_source
str default = “streams_raster” user source
Where channel pixels come from when mode=’zonal’. ‘streams_raster’ uses the delineated river-network raster reprojected onto the DEM grid; ‘none’ disables the channel class (every pixel is hillslope).
One of: "none" "streams_raster"
channel_buffer_px
int default = 0 dev source
Dilate the channel pixel mask by this many pixels before reducing, to capture a channel that grazes a cell without a pixel centre on it.
spike_guard_tol_m
float default = 2.0 dev source
Revert a hillslope cell’s zonal value to the centroid sample when it deviates more than this many metres (guards nodata/edge spikes); channel cells are exempt since they are lowered on purpose. 0 disables the guard.
min_pixels
int default = 3 dev source
Minimum DEM pixels inside a cell to trust a hillslope zonal statistic; below this the cell falls back to the centroid sample. A channel cell uses its channel stat from a single thalweg pixel.
min_thickness_m
float default = 0.1 dev source
Minimum layer-0 thickness (m) kept after zonal top lowering, so a carved channel top never collides with the aquifer bottom.
network_safety_net
bool default = False user source
Before the priority-flood fill, carve the channel cells into a monotone descending thalweg (lower-only) and pin them so the fill never raises them. Fixes the fill re-raising a zonal-lowered channel; needs a channel source (mode=’zonal’ with channel_source!=’none’). Off by default.
max_channel_lowering_m
float default = 5.0 dev source
Cap (m) on how far the network safety net may carve a single channel cell below its sampled top.
Starter TOML snippet#
Click to expand a copy-pasteable [modflow6] 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.
[modflow6]
[modflow6.sgrid]
# planar = ... # factory default
# vertical = ... # factory default
# grid_dual = "voronoi"
# condition_top = false
# condition_top_epsilon = 0.001
# top_sampling = ... # factory default
Cases using this section#
Validation gallery cases that reference fields from this section:
Entity-relationship diagram#
Click to zoom and pan. Press Esc or click outside to close.