Skip to content

feat(tsp): allow the GWT and GWE idomain to be a subset of the GWF idomain - #2986

Open
jdhughes-dev wants to merge 15 commits into
MODFLOW-ORG:developfrom
jdhughes-dev:feat-gwt-gwe-idomain-subset
Open

jdhughes-dev wants to merge 15 commits into
MODFLOW-ORG:developfrom
jdhughes-dev:feat-gwt-gwe-idomain-subset

Conversation

@jdhughes-dev

@jdhughes-dev jdhughes-dev commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

The transport IDOMAIN of a GWF-GWT or GWF-GWE exchange can now exclude cells that are active in GWF, including with GWT-GWT and GWE-GWE exchanges and in parallel; water that crosses the boundary of the reduced domain enters or leaves at the cell concentration or temperature and is reported as a DOMAIN-BOUNDARY budget term. The GWE-GWE interface model now takes its equation scaling factor from the GWE model rather than from CND, without which almost no energy crossed the exchange. #2931 makes the same change for PRT.

Closes #2962

Checklist of items for pull request

  • Replaced section above with description of pull request
  • Closed issue Allow the GWT and GWE IDOMAIN to be a subset of the GWF IDOMAIN #2962
  • Referenced issue or pull request feat(prt): support domain subsetting #2931
  • Added new test or modified an existing test
  • Ran ruff on new and modified python scripts in .doc, autotests, doc, distribution, pymake, and utils subdirectories.
  • Formatted new and modified Fortran source files with fprettify
  • Added doxygen comments to new and modified procedures
  • Updated definition files
  • Updated develop.toml with a plain-language description of the bug fix, change, feature; required for changes that may affect users
  • Removed checklist items not relevant to this pull request

For additional information see instructions for contributing and instructions for developing.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Enables GWT/GWE transport models to use an IDOMAIN that is a subset of the supplying GWF model (including exchanges and parallel runs), with FMI-based flow-imbalance correction carrying boundary fluxes; also fixes GWE-GWE interface scaling when CND is absent.

Changes:

  • Added grid/value mapping support in FMI to transfer results from a larger GWF grid onto a reduced transport grid and to remap package nodelists each timestep.
  • Updated GWF-GWT/GWF-GWE exchanges to allow subset IDOMAINs (with validation + warnings when flow-imbalance correction is off) and improved exchange matching via user node numbers.
  • Fixed GWE-GWE interface model to take equation scaling from the GWE model (not CND) and added new regression/parallel tests + docs/release notes.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
src/Utilities/PackageBudget.f90 Adds support for locally owned (mapped) nodelists and per-timestep remapping from the flow model.
src/Model/TransportModel/tsp-mvt.f90 Prevents accessing transport state for providers outside reduced transport domains.
src/Model/TransportModel/tsp-fmi.f90 Triggers value remapping each timestep when transport grid is mapped to a larger flow grid.
src/Model/ModelUtilities/FlowModelInterface.f90 Implements grid/connection mapping and per-timestep transfer of heads/sat/spdis/flowja/storage for subset domains.
src/Model/Connection/GweGweConnection.f90 Fixes interface model equation scaling factor source when CND is inactive.
src/Exchange/exg-gwfgwt.f90 Allows subset IDOMAIN for GWT, builds mapping early, warns on missing imbalance correction, and matches exchanges by user nodes.
src/Exchange/exg-gwfgwe.f90 Same as GWT but for GWE, and stores filename for better error context.
src/Exchange/DisConnExchange.f90 Adds helper to compare exchanges by user node numbers for robust matching under differing reductions/parallel.
doc/mf6io/mf6ivar/dfn/gwt-dis*.dfn Documents subset-IDOMAIN behavior and FMI correction recommendation for GWT.
doc/mf6io/mf6ivar/dfn/gwe-dis*.dfn Documents subset-IDOMAIN behavior and FMI correction recommendation for GWE.
doc/ReleaseNotes/develop.toml Adds feature + fix entries describing subset-IDOMAIN support and GWE-GWE scaling fix.
autotest/test_par_gwt_idomain_subset_gwtgwt.py Adds parallel regression for reduced-domain GWT-GWT exchange spanning a process boundary.
autotest/test_par_gwe_idomain_subset_gwegwe.py Adds parallel regression for reduced-domain GWE-GWE exchange spanning a process boundary.
autotest/test_gwt_idomain_subset_gwtgwt.py Adds regression for exchange matching by user nodes under reduced domains (+ TVD/XT3D boundary-layer expectations).
autotest/test_gwt_idomain_subset.py Adds regressions for reduced-domain GWT with FMI correction + error cases (non-subset IDOMAIN, advanced package outside domain).
autotest/test_gwe_idomain_subset_gwegwe.py Adds regression for exchange matching by user nodes under reduced domains for GWE (+ TVD/XT3D boundary-layer expectations).
autotest/test_gwe_idomain_subset.py Adds regressions for reduced-domain GWE with FMI correction + error cases (non-subset IDOMAIN, advanced package outside domain).

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread src/Model/TransportModel/tsp-mvt.f90 Resolved
Comment thread src/Utilities/PackageBudget.f90 Resolved
Comment thread src/Exchange/exg-gwfgwt.f90 Resolved
Comment thread src/Exchange/DisConnExchange.f90 Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Critical and moderate findings remain in package mapping, APT validation, and mapped FMI cleanup.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

src/Model/ModelUtilities/FlowModelInterface.f90:407

  • This cleanup is implemented only in the base FlowModelInterfaceType::fmi_da, but TspFmiType overrides fmi_da with gwtfmi_da and does not call the base routine. Consequently mapped GWT/GWE models skip this block: the grid maps remain allocated, and the mapped storage arrays are also not released because gwtfmi_da only frees them when flows_from_file is true. Move the mapped cleanup into the transport override or invoke the base deallocator so mapped simulations do not leak these memory-manager objects.

src/Model/TransportModel/tsp.f90:708

  • This loop dereferences packobj%flowbudptr during exg_df, but the exchange is defined before model_ar; the APT-specific flowbudptr is assigned by find_*_package from apt_read_dimensions during model_ar. For any advanced transport package this pointer is still unassociated here, so the new validation can fail before producing the intended domain error. Defer this check until after APT package initialization or validate against data available during exg_df.
        do j = 1, packobj%flowbudptr%budterm(packobj%idxbudgwf)%nlist
          nf = packobj%flowbudptr%budterm(packobj%idxbudgwf)%id2(j)
          if (this%fmi%gwfnodeinv(nf) > 0) cycle
  • Files reviewed: 22/22 changed files
  • Comments generated: 2
  • Review effort level: Lite

Comment thread src/Model/TransportModel/tsp.f90 Resolved
Comment thread src/Utilities/PackageBudget.f90 Resolved
@jdhughes-dev

Copy link
Copy Markdown
Contributor Author

On the two suppressed Copilot comments:

  • FlowModelInterface.f90:407: correct, gwtfmi_da does not call the base routine. The grid maps, mapped storage arrays, and IGWFMAPPED are now freed there (b6562e0).
  • tsp.f90:708: flowbudptr is associated when exg_df runs. apt_read_dimensions sets it during model_df, using the gwfbndlist pointer set when the exchange is created, and the idomapt cases exercise this check. No change.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

A critical reduced-grid mapping concern remains unresolved, and the scope warrants human review before approval.

Review details
  • Files reviewed: 27/27 changed files
  • Comments generated: 1
  • Review effort level: Lite

Comment thread src/Model/TransportModel/tsp.f90 Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

One critical and two moderate exchange-validation and matching findings remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

src/Exchange/exg-gwfgwe.f90:323

  • This candidate loop selects a GWF-GWF connection solely by matching endpoint user nodes. It never verifies that gwfConn connects the two GWF models named by this GWE-GWE exchange, so when multiple GWF exchanges reuse the same endpoint nodes, the first same-shaped exchange can be linked to the wrong GWE connection. Add the same gwfmodelname1/2 checks used by the GWT matching path before calling same_exchange_cells.
          areEqual = same_exchange_cells(gwfConn%prim_exchange, &
                                         gweConn%prim_exchange)

src/Exchange/exg-gwfgwe.f90:352

  • The legacy-exchange fallback has the same ambiguity: it accepts any GWF exchange with the same endpoint user nodes, without checking gwfmodelname1/2. With multiple GWF exchanges between the same cells, this can attach the GWE exchange to an unrelated flow exchange; apply the model-name checks here as well, as the GWT fallback does.
            areEqual = same_exchange_cells(gwfEx, gweConn%prim_exchange)
  • Files reviewed: 28/28 changed files
  • Comments generated: 1
  • Review effort level: Lite

Comment thread src/Exchange/DisConnExchange.f90 Resolved
@jdhughes-dev

Copy link
Copy Markdown
Contributor Author

On the two suppressed Copilot comments on exg-gwfgwe.f90 (lines 323 and 352): the GWE-GWE exchange has no GWFMODELNAME1/GWFMODELNAME2 input, so there are no model names to check as the GWT path does. GWE matching on develop also compares cells only, so this is unchanged by this pull request. No change.

@wpbonelli wpbonelli left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lots here that the corresponding PRT work can take advantage of, node mapping etc.

Comment thread src/Exchange/exg-gwfgwt.f90 Resolved
Comment thread src/Model/TransportModel/tsp.f90 Resolved

@mjr-deltares mjr-deltares left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice development. I have a few minor comments though.

  • I think we should be careful with the verbosity in the dfn files and the release notes. The pitfall would be to replicate (parts of) the user manual there. The extent we have been using seemed a good compromise to me, but with AI we are pushing it a bit
  • Wouldn't it be confusing to mix the flow imbalance error (a measure for the quality of the solution) with the flows leaving the domain? It could also have its own budget term. Maybe discuss if we can have a dedicated budget accounting.
  • The new boundary condition is applied implicitly and uniformly at the reduced boundary. What would be cases that validate the use of this condition? The ones that I can think of would be equally well served with a zero concentration condition. If people need it though, maybe we can provide the explicit "natural" boundary condition (the zero quantity gradient in/outflow) so that it can also be used at the conventional model boundary?

@jdhughes-dev
jdhughes-dev force-pushed the feat-gwt-gwe-idomain-subset branch from 1933d34 to 1e0a5be Compare October 19, 2026 15:56
@jdhughes-dev

Copy link
Copy Markdown
Contributor Author

@mjr-deltares

  • Verbosity: the IDOMAIN additions in the six GWT and GWE discretization dfn files are now two sentences, and the two release notes are two or three sentences each (1e0a5be, 87cb4e9).
  • Budget term: agreed. Flow across the connections that a reduced domain excludes is now its own DOMAIN-BOUNDARY budget term instead of part of the flow imbalance, so a reduced domain no longer needs FLOW_IMBALANCE_CORRECTION (87cb4e9). The GWT and GWE subset tests now run without the correction.
  • Boundary condition: water that crosses the reduced boundary enters or leaves at the cell concentration, with no dispersion, which is the natural boundary you describe. The case that needs it is a plume leaving a trimmed domain: a zero-concentration condition there also removes mass by dispersion toward the boundary. Where the concentration outside the domain is known, it should be specified with CNC. Making the same natural boundary available at a conventional model boundary would be a separate feature, and I can open an issue for it.

@jdhughes-dev

Copy link
Copy Markdown
Contributor Author

@mjr-deltares, one more point on the review, for discussion before I change anything.

Starting concentrations or temperatures are read for every cell, but values in cells that are active in the GWF Model and excluded from the transport model are discarded, so a user could read a non-zero value there as solute or heat in the excluded area. check_gwf_domain could check these cells, since the full-grid STRT input is available when the exchange is set up.

  • Proposal: a single warning, "N cells are excluded from the GWT Model but have a non-zero starting concentration; these values are not used", listing the first 20 cells. Zero and DNODATA would both be accepted without a warning.
  • Why not an error: a single STRT for the whole grid is common, for example a background salinity or a GWE ambient temperature, and an error would require an array only to blank the excluded cells. Starting values in inactive cells are ignored elsewhere in MODFLOW 6.
  • No effect on results: water that crosses the reduced boundary enters at the concentration of the active cell, not at the STRT of the excluded cell, and excluded cells are written as 1e30 in the concentration output.

Would a warning be useful, or would you rather leave this out?

@mjr-deltares

Copy link
Copy Markdown
Contributor

hey @jdhughes-dev

No need to start on that feature as far as I'm concerned, can be done in a later stage too. But, the most natural condition would be the prevailing concentration for outflow, but maybe use zero concentration for inflow? (or is that what you had in mind eventually, I forgot)

On the initial conditions. I think there are more places where a model could have non-trivial gwt/gwe information that is being cut out by the idomain reduction. For example, the SSM could have features outside the GWT idomain. Maybe best to let all of that be the responsibility of the user?

@jdhughes-dev
jdhughes-dev force-pushed the feat-gwt-gwe-idomain-subset branch from 87cb4e9 to be55e51 Compare November 16, 2026 02:26
@jdhughes-dev

Copy link
Copy Markdown
Contributor Author

@mjr-deltares

  • Inflow concentration: inflow across the reduced boundary still enters at the concentration of the cell, so there is no jump in concentration at the boundary, which is what a plume leaving a trimmed domain needs. A zero concentration for inflow would dilute the boundary cells wherever the water outside the domain carries solute. Where the concentration outside the domain is known, it can be given with CNC, and a zero-concentration inflow option can be added later if users need it.
  • Starting values and SSM features in excluded cells: agreed, these are left to the user, and no warning is added.
  • Since the review: the IDOMAIN descriptions in the six GWT and GWE discretization dfn files are shortened further, as AGENTS.md asks, and the boundary behavior is described in the GWT and GWE FMI sections of the input and output guide (c336fd3). The branch is rebased onto develop.

@jdhughes-dev

Copy link
Copy Markdown
Contributor Author

@mjr-deltares, to be specific about "the concentration of the cell": the flow across a transport cell's excluded connections is summed into one net flow for the cell, which enters or leaves at the cell's current simulated concentration (a diagonal term in the transport equation, reported as DOMAIN-BOUNDARY). Starting concentrations of excluded cells are not used. Because the water crosses at the cell's own concentration, the boundary flow does not change that concentration, inflow or outflow; the cell's concentration changes only through its exchanges with active cells, sources and sinks, and reactions. A boundary cell with inflow keeps feeding the interior at its current concentration, so a non-zero starting concentration at an inflow edge persists, much like a constant concentration, until water from interior cells, dispersion, or decay changes it. A zero-concentration inflow option would instead dilute such a cell; if users need that, it can be added as an option later.

A GWF-GWT exchange required the two models to have identical IDOMAIN
arrays, so transport always had to be simulated for every active flow
cell. The transport model may now exclude cells that are active in the
flow model; a cell that is active in the transport model must still be
active in the flow model.

FMI gains a mapped mode with node, connection, and dropped-connection
maps that are built in exg_df, before the transport arrays are
allocated. In that mode FMI owns the flow arrays, sized on the transport
grid, and refills them from the flow model in fmi_ad, so the transport
packages are unchanged. Boundary package nodelists are remapped each
time step through PackageBudgetType, with entries in excluded cells set
to zero.

Flow across connections that the transport model does not have is
subtracted from the flowja diagonal so that it is carried by the FMI
flow imbalance correction. For advection with upstream weighting this
reproduces the full-domain solution in the retained cells.

Errors are reported for a transport cell that is inactive in the flow
model, a transport connection that does not exist in the flow model, an
advanced transport package connected to a cell outside the transport
domain, a GWT-GWT exchange, and a parallel simulation. A warning is
written when FLOW_IMBALANCE_CORRECTION is not activated.
Extend the reduced transport domain to GWE. GWT and GWE share the FMI
package, so the grid maps, the mapped flow arrays, and the remapped
boundary package nodelists are reused unchanged; only the GWF-GWE
exchange needed the subset check, the mapped wiring, and the guards for
advanced packages, GWE-GWE exchanges, and parallel simulations. The
exchange now stores its input file name so that errors are reported
against it.

The flow imbalance correction accounts for advection only, so the
boundary of a reduced transport domain is a zero dispersive-flux
boundary in GWT and a zero conductive-flux boundary in GWE. The GWT and
GWE idomain descriptions now say so.
A GWT or GWE model with a reduced transport domain can now also be
coupled to another transport model through a GWT-GWT or GWE-GWE
exchange.

The interface model already reads the flow arrays from each transport
model's own FMI package through the distributed variable
synchronization, so it picks up the mapped values unchanged. What did
need changing is how a transport exchange is matched to the flow
exchange it draws its flows from. The reduced node numbers of the two
exchanges differ as soon as an excluded cell precedes an exchange cell
in the same model, so same_exchange_cells compares the cells as user
node numbers instead. Reduced node numbers are still compared when a
model is not local, because its discretization is not available to
convert them.
…model

The GWE-GWE interface model took its equation scaling factor from the
CND package of the underlying GWE model, so a GWE model without a CND
package left the interface model with its default value of one instead
of the product of the density and the heat capacity of water. Advective
energy transport across the exchange was reduced by that factor, about
4.2 million for the default water properties, so essentially no energy
crossed the exchange and temperatures accumulated in the upgradient
model while the model budgets continued to close.

The scaling factor is now taken from the GWE model, which is where the
CND package obtained it, so results are unchanged when CND is active.

The GWE-GWE idomain subset test no longer needs a CND package with no
conductivity to work around this and covers the fixed path instead.
A reduced GWT or GWE domain was rejected in a parallel simulation. The
virtual models already carry the mapped FMI arrays in the transport
model index space and a flow model shares a rank with the transport
model it supplies, so the transfer of flow results is a local operation
in parallel exactly as it is in serial.

What did need changing is how a transport exchange is matched to the
flow exchange it draws its flows from. The node numbers of a model on
another process are synchronized in the numbering of the process that
owns it, so a reduced transport model and its flow model report
different values for the same cell. same_exchange_cells now compares a
side only where both models are local, and each process compares the
side it owns, so both sides are still checked.

Adds a case with TVD advection and XT3D dispersion or conduction to each
transport exchange test, which widens the stencil at the transport
boundary, and parallel variants of both tests on two processes.
The GWF-GWT and GWF-GWE exchanges each carried an identical routine that
checks the transport IDOMAIN is a subset of the flow IDOMAIN, builds the
FMI grid maps, and rejects an advanced transport package connected to an
excluded cell. The two differed only in the model type and the model
label written in the error messages.

The check is now check_gwf_domain on TransportModelType, which labels its
messages with the model acronym, and both exchanges call it. The error
messages are unchanged. The exchange arguments of same_exchange_cells are
now declared intent(in).
An advanced transport package (LKT, SFT, MWT, UZT, LKE, SFE, MWE, UZE)
takes the cell of each connection from the GWF term of its flow package,
which holds flow model node numbers, and used that number directly to
index the transport model. With a reduced transport domain the two
numberings differ whenever an excluded cell precedes a connected cell, so
the package coupled to the wrong cell and the transport budget did not
close.

The connection cell is now obtained from get_cell_node, which converts
the flow model node to the transport model node when the transport grid
is mapped. Results are unchanged when the two models use the same cells.

The GWT and GWE subset tests add a case that drops the upgradient cells
and keeps a well handled by MWT or MWE, with well-bore conduction for
MWE, and compare against the full-domain model. Without the fix the GWT
budget discrepancy is 76 percent and the GWE simulation fails.
…zero

The transport FMI deallocation overrides the base routine, so the flow
model grid maps, the mapped storage arrays, and IGWFMAPPED were never
deallocated for a GWT or GWE model with a reduced transport domain.

A flow package entry with no groundwater cell, such as an SFR reach with
a cellid of NONE, has a node of zero, which was used to index the node
map. Such an entry now stays zero in the mapped nodelist and is skipped
by SSM as before.
The domain check skipped the grid maps whenever the transport and flow
models had the same number of active cells. A DIS or DISV cell with an
IDOMAIN of -1 is not counted but connects the cells above and below it,
so a transport model that gives that cell an IDOMAIN of 0 has the same
cells and different connections. The transport model then read the flow
model FLOWJA with its own connection positions.

The maps are now skipped only when the cells and the connections are
both identical. A flow model connection is also treated as excluded when
both cells are retained but the transport model does not connect them,
so the flow through a pass-through cell is carried by the flow imbalance
correction.

Add test_gwt_idomain_subset_vpt.py, in which the transport model excludes
a vertical pass-through cell of the flow model. Without the fix the
transport budget discrepancy is 99.7 percent.
…anges

An exchange cell outside the active domain is stored with a node of -1
and reported as an input error, but the simulation continues until the
errors are counted. same_exchange_cells converted that node to a user
node number, which indexes the node map out of bounds for a reduced grid.
A nonpositive node now ends the comparison without a match.
…F-GWE

The GWF-GWT and GWF-GWE exchanges each connected the transport model
to the flow model head, saturation, specific discharge, and flowja with
separate mapped and unmapped branches. FMI now does this in
set_gwf_flowja and set_gwf_state, and the warning for a reduced domain
without FLOW_IMBALANCE_CORRECTION is written by check_gwf_domain.
The values mapped each time step are transferred in a single loop over
the transport nodes.

check_gwf_domain compared only the number of user nodes, so two grids
of a different type or shape with the same number of cells passed. The
grids must now be the same type and shape, and each cell active in both
models must have the same top, bottom, and area.
Shorten the IDOMAIN descriptions in the GWT and GWE discretization
definition files and the release notes, and move the release notes to
doc/ReleaseNotes/items.
…arately

Flow across the connections that a reduced transport domain excludes
was removed from the flowja diagonal, so it entered the transport model
through the FLOW_IMBALANCE_CORRECTION and was mixed with the error of
the flow solution. FMI now sums that flow for each cell and applies it
as its own DOMAIN-BOUNDARY budget term, in which water enters or leaves
at the cell concentration or temperature. A reduced domain no longer
needs FLOW_IMBALANCE_CORRECTION, and the warning for it is removed.

The GWT and GWE subset tests now run without the correction and check
for the new term, and the IDOMAIN descriptions and release note state
the boundary condition.
Keep the transport IDOMAIN descriptions concise, as AGENTS.md asks, and
describe the flow across the boundary of a reduced transport domain in the
GWT and GWE FMI sections of the input and output guide.
The boundary flow of a reduced transport domain crosses at the cell's own concentration or temperature, so it does not change it, and a starting value at an inflow edge persists until exchanges with active cells change it.
@jdhughes-dev
jdhughes-dev force-pushed the feat-gwt-gwe-idomain-subset branch from 93ca315 to d3bdd00 Compare November 16, 2026 15:17

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Allow the GWT and GWE IDOMAIN to be a subset of the GWF IDOMAIN

4 participants