SWATGenXSWATGenX
ResearchDocs
Open Explorer Work with us
SWATGenXDocs

MODFLOW coupling

Applies to SWATGenX engine extensions · Updated August 2026

Steady-state MODFLOW 6 in Michigan LP, Indiana, Minnesota, Ohio, Wisconsin: the MODFLOW_250m package, SWAT+ percolation recharge, calibrated to well heads.

“SWAT+MODFLOW-6” refers to two related but different deliverables. Establish which one a given package contains before working with exchange files or BMI.

Two coupling modes (do not conflate)

  • In a groundwater study (offered in Michigan Lower Peninsula, Indiana, Minnesota, Ohio, Wisconsin): SWAT+ builds first; a sibling MODFLOW_250m steady-state grid is then built, with its recharge built from the SWAT+ model's annual-mean percolation (perc), then calibrated automatically, with the aquifer's conductivities, to measured well heads (for a build that converges and has head observations). This model runs on its own: heads and baseflow return to SWAT+ only in the engine's daily coupling, switched on by mf6.con (below). That build does not yet produce a transient MODFLOW model.
  • Pumping wells: included in Michigan, from the state's well records. In the other offered states the groundwater model currently runs without pumping.
  • Coupled mode (in the engine, not run by an automatic build): daily two-way BMI/XMI coupling inside the SWAT+ day loop. Activated only when TxtInOut contains mf6.con plus map files; the engine loads libmf6 at run time. Not included in standard packages.
An automatic build's download holds the steady-state sibling grid. If the unzipped site has MODFLOW_250m next to the SWAT+ project and no mf6.con in TxtInOut, it is that build.

Build pipeline (steady-state MODFLOW 6)

  1. In a groundwater study (in Michigan Lower Peninsula, Indiana, Minnesota, Ohio, Wisconsin), we build a SWAT+ model with a steady-state MODFLOW 6 model, or attach one to a finished SWAT+ workspace.
  2. After the SWAT+ package is ready, a 250 m MODFLOW 6 grid is built (offered in Michigan Lower Peninsula, Indiana, Minnesota, Ohio, Wisconsin); its recharge is built from the SWAT+ model's annual-mean percolation, then calibrated automatically, with the aquifer's conductivities, to measured well heads.
  3. Percolation is mapped HRU→cell (area-weighted) into RCHA: a cell with zero percolation keeps zero recharge, and a cell no HRU covers takes the covered-area mean. The grid is assembled with standard MF6 packages (RCHA, SFR/DRN/GHB/WEL, …), solved steady-state, then optionally head-calibrated when observations exist.
  4. Artifacts land as a sibling folder MODFLOW_{resolution}m under the same site directory — not inside Scenarios/.../TxtInOut.
{site}/
├── SWAT_MODEL_Web_Application/   # (or resolved model name) — SWAT+ package
│   └── Scenarios/Default/TxtInOut/
└── MODFLOW_250m/                 # sibling steady-state MF6 grid (not inside TxtInOut)
    ├── mfsim.nam
    ├── MODFLOW_250m.nam
    ├── *.dis *.npf *.ic *.ims *.oc *.sto *.tdis
    ├── *.rcha *.sfr *.drn *.ghb *.wel …
    ├── Grids_MODFLOW*
    ├── obs_vs_sim.csv / .png     # when head obs exist
    └── head_calibration_report.json
  • SWAT+ and MODFLOW download as separate archives. The standard MODFLOW folder has no README and no mf6.con / exchange maps.
  • Default grid spacing for chained builds is 250 m. A study can also attach MODFLOW to an existing finished SWAT+ workspace.
  • Groundwater studies cover Michigan Lower Peninsula, Indiana, Minnesota, Ohio, Wisconsin. The request point / HUC12 centroid must fall in coverage; sparse well density can refuse a build.
  • MF6 lengths in meters; time in days. Recharge comes from SWAT+ percolation (mm/yr → m/day). Well elevations commonly convert feet→meters (× 0.3048).
  • Spatial link: an HRU↔cell area-weighted map places recharge on the grid. No daily exchange loop in the shipped archive.
  • The stock SWAT+ gwflow module is a different mechanism and is not this external-MF6 path.

Running the MODFLOW package locally

  1. Install USGS MODFLOW 6 (mf6). FloPy is optional for inspection/edits; the platform already ran MF6 at build time.
  2. Unzip the MODFLOW_* package; keep the tree intact (mfsim.nam at the root of that folder).
  3. From that directory, run mf6 (or point your runner at mfsim.nam). Re-read heads (.hds), budget (.cbc), and listing files.
  4. SWAT+ still runs from Scenarios/Default/TxtInOut with a SWAT+ executable — independently of mf6 unless you assemble the coupled mode below.

Daily two-way BMI/XMI coupling (research)

Daily two-way coupling is in the public SWAT+ fork (the engine's coupled mode); an automatic build does not run it yet. Its design, each SWAT+ day: percolation is pushed to MF6 recharge; SFR groundwater exchange is aggregated back to SWAT+ channels, meant to replace the native aquifer return. The current engine still adds that exchange on top of the native return (a double count being fixed), and no model we deliver runs this mode. An optional PFAS leach map feeds groundwater transport when present.

./mf6               ! 1: folder (inside TxtInOut) holding mfsim.nam
1                   ! 2: groundwater FLOW step, in days (1 = daily)
30                  ! 3: groundwater TRANSPORT step, in days (30 = monthly)
1.0                 ! 4: recharge multiplier for calibration (1.0 = none)
/path/to/libmf6.so  ! 5: full path to USGS libmf6.so (the default exists only on our servers)
  • Place mf6.con in TxtInOut. Convention: MF6 workspace at TxtInOut/mf6/ containing mfsim.nam. Absent mf6.con ⇒ plain SWAT+ (no-op).
  • Name the groundwater model MODFLOW_SFR. The coupler binds three fixed MF6 addresses: MODFLOW_SFR/RCHA_0/RECHARGE (recharge down), MODFLOW_SFR/SFR_0/GWFLOW and MODFLOW_SFR/SFR_0/IGWFNODE (exchange back to channels). mf6.con has no field to change them. A delivered MODFLOW_250m build names its model MODFLOW_250m in mfsim.nam (in either case, on the gwf6 line and the ims6 line); rename it to MODFLOW_SFR in both places. Its packages are already rcha_0 and sfr_0 in MODFLOW_250m.nam (MF6 names are case-insensitive), so they bind as they are.
  • Check the run log for BOTH lines: 'recharge map: N HRU-cell links onto M MF6 cells' and 'baseflow map: N SFR reaches -> SWAT+ channels'. Each is printed only when its address binds. Without the first, SWAT+ is not driving recharge and MF6 runs with its own RCHA input; without the second, no groundwater exchange returns to the SWAT+ channels.
  • Maps next to mf6.con: mf6_recharge.map (HRU→cell), mf6_baseflow.map (SFR reach→channel), optional pfas_leach.map.
  • Needs a coupler-enabled swatplus binary (see Compile the SWAT+ fork) plus USGS libmf6.so, named by its full path on line 5 of mf6.con.
  • Standard packages do not ship mf6.con or the exchange maps; assemble them only for the research daily-coupling path.

Failure modes

  • Expected mf6.con missing — standard archives intentionally omit it; the BMI path requires adding con + maps + a coupler binary.
  • MF6 fails to open packages — run from the MODFLOW_* directory; do not nest it inside TxtInOut unless assembling research daily coupling.
  • Library not opened — when libmf6.so does not open at the path on line 5 of mf6.con (or at the default, which exists only on our servers), the coupler prints "MF6 COUPLER: dlopen failed for" and the path, and the run goes on as plain SWAT+.
  • Coupling silently off — if the model is not named MODFLOW_SFR (or a map file is truncated), the coupler logs a trace and continues with that half uncoupled: no error, and MF6 keeps its own recharge. A missing 'recharge map:' or 'baseflow map:' line in the run log is the only sign.
  • Map built for another grid — the coupler takes the array sizes from the map files' own headers and does not check them, or the cell indices, against the MF6 model. A map from a different grid writes into the wrong cells, or past the end of MF6's arrays, with no error, and an HRU id outside the model is skipped without a message. Make mf6_recharge.map and mf6_baseflow.map from the same MODFLOW grid and SFR network you run.

MODFLOW_250m package contents

File-by-file contents of the sibling MODFLOW_{resolution}m folder a coupled build produces. Assembled as a standard MODFLOW 6 simulation; the archive contains the entire folder.

The standard deliverable (offered in Michigan Lower Peninsula, Indiana, Minnesota, Ohio, Wisconsin) is a standalone steady-state MODFLOW 6 model built with your SWAT+ model; its recharge is built from the SWAT+ model's annual-mean percolation, then calibrated automatically, with the aquifer's conductivities, to measured well heads. Pumping wells: included in Michigan, from the state's well records. In the other offered states the groundwater model currently runs without pumping. Lengths are meters, time is days. Run it locally with mf6 from the folder root (mfsim.nam). The archive (MODFLOW_Model_{site}_{res}m.zip) contains the whole tree, including intermediate rasters and grids.

MODFLOW 6 packages in the archive

FileDescriptionUnits / key values
mfsim.namSimulation namefile: TDIS + GWF model + IMS solver—
{name}.tdisSingle steady stress periodTIME_UNITS days; period (1.0, 1, 1.0)
{name}.imsNewton / BiCGSTAB solver settingsouter head close 0.1 m; inner 0.01 m
{name}.namGWF package listdis, ic, npf, sto, ghb, rcha, sfr/riv, drn, wel, oc
{name}.disStructured grid (delr/delc/top/botm/idomain)LENGTH_UNITS meters
{name}.npfNode property flow: k, k33, icelltypeK in m d⁻¹
{name}.icStarting heads = land surface (top), all layersm
{name}.stoStorage; stress period 0 steady-state—
{name}.rchaArray recharge built from SWAT+ annual-mean percolation (a zero-percolation cell keeps 0; a cell no HRU covers takes the covered-area mean), then scaled by the automatic calibration to measured well headsm d⁻¹ (mm yr⁻¹ ÷ 1000 ÷ 365.25); without per-HRU percolation, the basin's own mean percolation on every cell; 5.5e-4 only when both are missing
{name}.ghbPerimeter general-head boundary to kriged water tablehead m; conductance m² d⁻¹ (K × thickness)
{name}.sfrStreamflow routing (default stream representation)lengths m; bed K m d⁻¹; inflow m³ d⁻¹; TIME_CONVERSION 86400
{name}.rivRIV fallback only if the SFR build failsstage/rbot m; conductance m² d⁻¹
{name}.drnSurface-seepage drains (default lake representation)elevation m; conductance m² d⁻¹ (capped 1e5)
{name}.welPumping wells from Michigan state well records; outside Michigan the package has no wellsflux m³ d⁻¹ (gpm × 5.678, negative = extraction)
{name}.ocOutput controlwrites {name}.hds + {name}.cbc
{name}.hds / .cbc / .lstRun outputs: heads, cell budgets, listingheads m; budgets m³ (per day)
{name}.sfr.stage / .sfr.cbcSFR stage and budget outputsstage m; flows m³ d⁻¹

Companion files (not MF6 packages)

FileDescription
Grids_MODFLOW_centroids.parquetCell centroids (row, col, geometry) in the projected CRS — used for well placement and GIS joins
Grids_MODFLOW.geojson / Grids_MODFLOW/*.shpCell polygons (GeoJSON only when cell count ≤ 120,000; shapefile alongside)
obs_vs_sim.csvHead observations vs simulated: wellid, row, col, obs_head_m, sim_head_m, restricted_source (obs = land surface − 0.3048 × SWL_ft). Where the source agency restricts public display of its records, obs_head_m is left empty and restricted_source names that source; those wells are not plotted in obs_vs_sim.png.
obs_vs_sim.pngObserved-vs-simulated head scatter
head_calibration_report.jsonDifferential-evolution head calibration report (multipliers, NSE, cal/val metrics) — present only after the head-calibration pass, not the initial build
{name}_overview.pngModel overview figure
lake_raster.tif, swat_river.tif, rasters_input/Intermediate build rasters (included because the ZIP archives the whole folder)
The standard folder intentionally contains no mf6.con and no exchange-map files: it is an automatic build's steady-state model; the engine's daily two-way coupling needs mf6.con and the exchange maps. See mf6.con and exchange maps below.

mf6.con and exchange maps

The four TxtInOut files that activate daily two-way SWAT+/MODFLOW 6 BMI/XMI coupling: mf6.con and the mf6_recharge.map, mf6_baseflow.map, pfas_leach.map exchange maps.

Coupling activates when TxtInOut contains mf6.con and a coupler-enabled swatplus binary can dlopen libmf6.so. Absent mf6.con → plain SWAT+ (no-op). Comments after ! are stripped on every line of every coupling file.

mf6.con

./mf6               ! 1: folder (inside TxtInOut) holding mfsim.nam
1                   ! 2: groundwater FLOW step, in days (1 = daily)
30                  ! 3: groundwater TRANSPORT step, in days (30 = monthly)
1.0                 ! 4: recharge multiplier for calibration (1.0 = none)
/path/to/libmf6.so  ! 5: full path to USGS libmf6.so (the default exists only on our servers)
LineDescriptionTypeDefault
1MF6 workspace path relative to TxtInOut (folder holding mfsim.nam)path"." (required in practice)
2Groundwater FLOW step cadence in days (clamped to ≥ 1)integer1
3Groundwater TRANSPORT step cadence in days (< 1 falls back to the flow cadence)integer30
4 (optional unless 5 is given)Recharge multiplier rch_mult applied to every pushed recharge valuereal1.0
5Full path to USGS libmf6.so (required outside our servers)patha path on our servers
Some example mf6.con comments mislabel line 4 as the library path. The engine parser is the authority: it reads the values in order, skipping blank and ! lines, so line 4 is the recharge multiplier and line 5 the library path. Write line 4 (1.0 for none) whenever you give line 5.

mf6_recharge.map — HRU → cell (down-coupling)

Optional; absent → MF6 keeps its own recharge. Header line, then one row per HRU–cell overlap link. Each day the coupler overwrites MF6 RECHARGE with Σ sepbtm(hru)/1000 × weight × rch_mult (SWAT+ mm/day → MF6 m/day).

FieldDescriptionTypeUnits
N_ENTRIESHeader: number of overlap linksinteger—
N_CELLSHeader: RECHARGE array size (NROW × NCOL)integer—
NCOL / N_HRUHeader: grid columns and max HRU id (written by the builder; unused by the coupler)integers—
cell_indexRow value 1: 0-based cell index (row × NCOL + col)integer—
hruRow value 2: SWAT+ HRU id (1-based)integer—
weightRow value 3: overlap area ÷ cell arearealdimensionless

mf6_baseflow.map — SFR reach → channel (up-coupling)

Optional; absent → up-coupling off. Header N_LINKS N_REACHES, then one row per link. The coupler reads SFR GWFLOW (m³/day; positive = stream→aquifer) and adds −GWFLOW as baseflow to the mapped SWAT+ channel. It is meant to replace the native aquifer return; the current engine still adds it on top (a double count being fixed).

FieldDescriptionTypeUnits
N_LINKSHeader: number of reach→channel linksinteger—
N_REACHESHeader: SFR GWFLOW array lengthinteger—
reach_indexRow value 1: 0-based SFR reach indexinteger—
gis_channelRow value 2: SWAT+ channel GIS idinteger—

pfas_leach.map — HRU → GWT source cell (PFAS down-coupling)

Optional; requires the PFAS module and a GWT model with an SRC package. Daily push: SRC load = Σ perc(kg/ha) × overlap_ha × 1e9 (µg/day); GWT concentrations are treated as ng/L on the way back.

FieldDescriptionTypeUnits
N_ENTRIESHeader: number of HRU→source linksinteger—
N_SRCCELLSHeader: SRC BOUND array lengthinteger—
src_indexRow value 1: 0-based SRC list indexinteger—
hruRow value 2: SWAT+ HRU idinteger—
overlap_haRow value 3: HRU–cell overlap arearealha

How maps are produced, and coupled-run outputs

  • Exchange maps are assembled offline from the SWAT+ HRU geometry and the MF6 grid (area-weighted HRU→cell for recharge / PFAS leach; SFR reach→channel for baseflow). They are not written by a standard website build.
  • A research daily-coupling workspace also needs a daily-TDIS MF6 (and optional GWT+SRC) model next to mf6.con — typically under TxtInOut/mf6/.
  • Coupled-run outputs under TxtInOut/mf6/: pfas.ucn (groundwater PFAS concentration per cell over time), pfas.lst (transport mass budget + percent discrepancy), MODFLOW_sfr.lst (flow budget incl. stream–aquifer exchange) — standard MODFLOW 6 formats.
  • An automatic build's package holds none of these coupling files; it carries the steady-state sibling MODFLOW_250m archive.