feat(fmi): support binary grid file (#2153)

Support an optional GWFGRID entry in FMI for the flow model's binary grid file. If provided, check the grids have the same size and idomain like we do in EXG as of #2149. This makes for the same error-checking in the exg (coupled) and fmi (post-processing) cases.

Tentative idea is to make the grid file entry optional for some time (1-2 releases), then begin to require it. At which point the reader could be modified to load the full dis, and we could consolidate these haphazard checks into a robust grid comparison.

The grb file reader in zonebudget is moved to a new GridFileReader module in the main src dir. The reader now loads headers and builds an index at init time, after which variables can be read as necessary.

autotest/test_prt_fmi.py

@@ -135,9 +135,11 @@ def build_prt_sim(name, gwf_ws, prt_ws, mf6):
     gwf_name = get_model_name(name, "gwf")
     gwf_budget_file = gwf_ws / f"{gwf_name}.bud"
     gwf_head_file = gwf_ws / f"{gwf_name}.hds"
+    grb_file = gwf_ws / f"{gwf_name}.dis.grb"
     flopy.mf6.ModflowPrtfmi(
         prt,
         packagedata=[
+            ("GWFGRID", grb_file),
             ("GWFHEAD", gwf_head_file),
             ("GWFBUDGET", gwf_budget_file),
         ],

autotest/test_prt_voronoi2.py

@@ -175,9 +175,11 @@ def build_prt_sim(name, gwf_ws, prt_ws, targets, cell_ids):
     )
     gwf_budget_file = gwf_ws / f"{gwf_name}.bud"
     gwf_head_file = gwf_ws / f"{gwf_name}.hds"
+    grb_file = gwf_ws / f"{gwf_name}.disv.grb"
     flopy.mf6.ModflowPrtfmi(
         prt,
         packagedata=[
+            ("GWFGRID", grb_file),
             ("GWFHEAD", gwf_head_file),
             ("GWFBUDGET", gwf_budget_file),
         ],

doc/ReleaseNotes/develop.tex

@@ -20,7 +20,8 @@
 \textbf{\underline{BUG FIXES AND OTHER CHANGES TO EXISTING FUNCTIONALITY}} \\
 \underline{BASIC FUNCTIONALITY}
 \begin{itemize}
-	\item Previously, GWF Model exchanges with other model types (GWT, GWE, PRT) verified that the flow model and the coupled model had the same number of active nodes, but did not check that the models' IDOMAIN arrays selected precisely the same set. Exchanges will now check that model IDOMAIN arrays are identical.
+	\item GWT, GWE and PRT Models require a grid identical to the grid of the corresponding GWF Model. Previously, GWT, GWE and PRT exchanges performed a minimal check that the grids have the same number of active nodes. Exchanges will now also perform an additional check that grid IDOMAIN arrays are identical.
+	\item GWT, GWE and PRT FMI Packages can now read a GWF Model's binary grid file via a new GWFGRID entry. This allows FMI Packages to perform the same grid equivalence checks as exchanges, which guarantees identical error-checking behavior whether a GWT, GWE or PRT Model is coupled to a GWF Model or running as a post-processor. The GWFGRID file entry is optional but recommended. A future version may make the GWFGRID entry mandatory.
 	\item A regression was recently introduced into the PRT model's generalized tracking method, in which a coordinate transformation was carried out prematurely. This could result in incorrect particle positions in and near quad-refined cells. This bug has been fixed.
 	\item The PRT model previously allowed particles to be released at any time. Release times falling outside the bounds of the simulation's time discretization could produce undefined behavior. Any release times occurring before the simulation begins (i.e. negative times) will now be skipped with a warning message. If EXTEND\_TRACKING is not enabled, release times occurring after the end of the simulation will now be skipped with a warning message as well. If EXTEND\_TRACKING is enabled, release times after the end of the simulation are allowed.
 \end{itemize}

doc/mf6io/gwe/fmi.tex

@@ -31,6 +31,7 @@
 \item If the binary budget and head files have more than one time step for a single stress period, then the budget and head information must be contained within the binary file for every time step in the simulation stress period.
 \item The binary budget and head files must correspond in terms of information stored for each time step and stress period.
 \item If the binary budget and head files have information provided for only the first time step of a given stress period, this information will be used for all time steps in that stress period in the GWE simulation. If the final stress period (which may be the only stress period) in the binary budget and head files has information provided for only one time step, this information will be used for any subsequent time steps and stress periods in the GWE simulation. This makes it possible to provide flows, for example, from a steady-state GWF stress period and have those flows used for all GWE time steps in that stress period, for all remaining time steps in the GWE simulation, or for all time steps throughout the entire GWE simulation. With this option, it is possible to have smaller time steps in the GWE simulation than the time steps used in the GWF simulation. Note that this cannot be done when the GWF and GWE models are run in the same simulation, because in that case, both models are solved for each time step in the stress period, as listed in the TDIS Package. This option for reading flows from a previous GWF simulation may offer an efficient alternative to running both models in the same simulation, but it comes at the cost of having potentially very large budget files.
+\item The binary grid file is optional but recommended, as it allows \mf to verify that the GWF and GWE model grids are identical.
 \end{itemize}
 
 \end{itemize}

doc/mf6io/gwt/fmi.tex

@@ -31,6 +31,7 @@
 \item If the binary budget and head files have more than one time step for a single stress period, then the budget and head information must be contained within the binary file for every time step in the simulation stress period.
 \item The binary budget and head files must correspond in terms of information stored for each time step and stress period.
 \item If the binary budget and head files have information provided for only the first time step of a given stress period, this information will be used for all time steps in that stress period in the GWT simulation. If the final stress period (which may be the only stress period) in the binary budget and head files has information provided for only one time step, this information will be used for any subsequent time steps and stress periods in the GWT simulation. This makes it possible to provide flows, for example, from a steady-state GWF stress period and have those flows used for all GWT time steps in that stress period, for all remaining time steps in the GWT simulation, or for all time steps throughout the entire GWT simulation. With this option, it is possible to have smaller time steps in the GWT simulation than the time steps used in the GWF simulation. Note that this cannot be done when the GWF and GWT models are run in the same simulation, because in that case, both models are solved for each time step in the stress period, as listed in the TDIS Package. This option for reading flows from a previous GWF simulation may offer an efficient alternative to running both models in the same simulation, but it comes at the cost of having potentially very large budget files.
+\item The binary grid file is optional but recommended, as it allows \mf to verify that the GWF and GWT model grids are identical.
 \end{itemize}
 
 \end{itemize}

doc/mf6io/mf6ivar/dfn/gwe-fmi.dfn

@@ -33,7 +33,7 @@ type string
 tagged false
 reader urword
 longname flow type
-description is the word GWFBUDGET, GWFHEAD, GWFMOVER or the name of an advanced GWF stress package.  If GWFBUDGET is specified, then the corresponding file must be a budget file from a previous GWF Model run.  If an advanced GWF stress package name appears then the corresponding file must be the budget file saved by a LAK, SFR, MAW or UZF Package.
+description is the word GWFBUDGET, GWFHEAD, GWFGRID, GWFMOVER or the name of an advanced GWF stress package from a previous model run.  If GWFBUDGET is specified, then the corresponding file must be a budget file.  If GWFHEAD is specified, the file must be a head file.  If GWFGRID is specified, the file must be a binary grid file. If GWFMOVER is specified, the file must be a mover file.  If an advanced GWF stress package name appears then the corresponding file must be the budget file saved by a LAK, SFR, MAW or UZF Package.
 
 block packagedata
 name filein

doc/mf6io/mf6ivar/dfn/gwt-fmi.dfn

@@ -33,7 +33,7 @@ type string
 tagged false
 reader urword
 longname flow type
-description is the word GWFBUDGET, GWFHEAD, GWFMOVER or the name of an advanced GWF stress package.  If GWFBUDGET is specified, then the corresponding file must be a budget file from a previous GWF Model run.  If an advanced GWF stress package name appears then the corresponding file must be the budget file saved by a LAK, SFR, MAW or UZF Package.
+description is the word GWFBUDGET, GWFHEAD, GWFMOVER or the name of an advanced GWF stress package.  If GWFBUDGET is specified, then the corresponding file must be a budget file. If GWFHEAD is specified, the file must be a head file.  If GWFGRID is specified, the file must be a binary grid file.  If an advanced GWF stress package name appears then the corresponding file must be the budget file saved by a LAK, SFR, MAW or UZF Package.
 
 block packagedata
 name filein

doc/mf6io/mf6ivar/dfn/prt-fmi.dfn

@@ -25,7 +25,7 @@ type string
 tagged false
 reader urword
 longname flow type
-description is the word GWFBUDGET or GWFHEAD.  If GWFBUDGET is specified, then the corresponding file must be a budget file from a previous GWF Model run.
+description is the word GWFBUDGET, GWFHEAD, or GWFGRID.  If GWFBUDGET is specified, then the corresponding file must be a budget file.  If GWFHEAD is specified, the file must be a head file.  If GWFGRID is specified, the file must be a binary grid file.
 
 block packagedata
 name filein

doc/mf6io/prt/fmi.tex

@@ -28,6 +28,7 @@
 \item If the binary budget and head files have more than one time step for a single stress period, then the budget and head information must be contained within the binary file for every time step in the simulation stress period.
 \item The binary budget and head files must correspond in terms of information stored for each time step and stress period.
 \item If the binary budget and head files have information provided for only the first time step of a given stress period, this information will be used for all time steps in that stress period in the PRT simulation. If the final (or only) stress period in the binary budget and head files contains data for only one time step, this information will be used for any subsequent time steps and stress periods in the PRT simulation. This makes it possible to provide flows, for example, from a steady-state GWF stress period and have those flows used for all PRT time steps in that stress period, for all remaining time steps in the PRT simulation, or for all time steps throughout the entire PRT simulation. With this option, it is possible to have smaller time steps in the PRT simulation than the time steps used in the GWF simulation. Note that this cannot be done when the GWF and PRT models are run in the same simulation, because in that case, both models are solved over the same sequence of time steps and stress periods, as listed in the TDIS Package. The option to read flows from a previous GWF simulation via Flow Model Interface may offer an efficient alternative to running both models in the same simulation, but comes at the cost of having potentially very large budget files.
+\item The binary grid file is optional but recommended, as it allows \mf to verify that the GWF and PRT model grids are identical.
 \end{itemize}
 
 \end{itemize}

make/makefile

@@ -1,4 +1,4 @@
-# makefile created by pymake (version 1.2.11.dev0) for the 'mf6' executable.
+# makefile created by pymake (version 1.4.0.dev0) for the 'mf6' executable.
 
 
 include ./makedefaults
@@ -249,6 +249,7 @@ $(OBJDIR)/BudgetFileReader.o \
 $(OBJDIR)/TimeArraySeriesLink.o \
 $(OBJDIR)/ObsUtility.o \
 $(OBJDIR)/ObsContainer.o \
+$(OBJDIR)/Disv1dGeom.o \
 $(OBJDIR)/BudgetTerm.o \
 $(OBJDIR)/Budget.o \
 $(OBJDIR)/TimeArraySeriesManager.o \
@@ -258,6 +259,13 @@ $(OBJDIR)/NumericalPackage.o \
 $(OBJDIR)/Particle.o \
 $(OBJDIR)/PackageBudget.o \
 $(OBJDIR)/HeadFileReader.o \
+$(OBJDIR)/GridFileReader.o \
+$(OBJDIR)/Disv.o \
+$(OBJDIR)/Disv2d.o \
+$(OBJDIR)/Disv1d.o \
+$(OBJDIR)/Disu.o \
+$(OBJDIR)/Dis.o \
+$(OBJDIR)/Dis2d.o \
 $(OBJDIR)/BudgetObject.o \
 $(OBJDIR)/BoundaryPackage.o \
 $(OBJDIR)/CellDefn.o \
@@ -332,7 +340,6 @@ $(OBJDIR)/MethodCellTernary.o \
 $(OBJDIR)/MethodCellPollockQuad.o \
 $(OBJDIR)/MethodCellPollock.o \
 $(OBJDIR)/MethodCellPassToBot.o \
-$(OBJDIR)/Disv1dGeom.o \
 $(OBJDIR)/VectorInterpolation.o \
 $(OBJDIR)/swf-cxs.o \
 $(OBJDIR)/CellWithNbrs.o \
@@ -342,9 +349,6 @@ $(OBJDIR)/tsp-oc.o \
 $(OBJDIR)/tsp-obs.o \
 $(OBJDIR)/tsp-mvt.o \
 $(OBJDIR)/tsp-adv.o \
-$(OBJDIR)/Disv.o \
-$(OBJDIR)/Disu.o \
-$(OBJDIR)/Dis.o \
 $(OBJDIR)/gwf-uzf.o \
 $(OBJDIR)/tsp-apt.o \
 $(OBJDIR)/gwt-mst.o \
@@ -371,7 +375,6 @@ $(OBJDIR)/Double2dReader.o \
 $(OBJDIR)/Double1dReader.o \
 $(OBJDIR)/MethodCellPool.o \
 $(OBJDIR)/CellUtil.o \
-$(OBJDIR)/Disv1d.o \
 $(OBJDIR)/swf-dfw.o \
 $(OBJDIR)/swf-ic.o \
 $(OBJDIR)/VirtualExchange.o \
@@ -426,8 +429,6 @@ $(OBJDIR)/swf-oc.o \
 $(OBJDIR)/swf-obs.o \
 $(OBJDIR)/swf-flw.o \
 $(OBJDIR)/swf-cdb.o \
-$(OBJDIR)/Disv2d.o \
-$(OBJDIR)/Dis2d.o \
 $(OBJDIR)/GridConnection.o \
 $(OBJDIR)/DistributedVariable.o \
 $(OBJDIR)/gwt.o \

msvs/mf6core.vfproj

@@ -628,6 +628,7 @@
 		<File RelativePath="..\src\Utilities\DevFeature.f90"/>
 		<File RelativePath="..\src\Utilities\ErrorUtil.f90"/>
 		<File RelativePath="..\src\Utilities\GeomUtil.f90"/>
+		<File RelativePath="..\src\Utilities\GridFileReader.f90"/>
 		<File RelativePath="..\src\Utilities\HashTable.f90"/>
 		<File RelativePath="..\src\Utilities\HeadFileReader.f90"/>
 		<File RelativePath="..\src\Utilities\HGeoUtil.f90"/>