feat: make binary grid file name configurable (#2228)

Add option to all discretization packages to configure the grb output file path, usage GRB6 OUTFILE <filepath>. Motivated by modflowpy/flopy#2462.

Author: wpbonelli

autotest/test_gwf_disu.py

@@ -6,7 +6,7 @@
 in binary grid file is correct.
 """
 
-import os
+from pathlib import Path
 
 import flopy
 import numpy as np
@@ -15,6 +15,7 @@
 from framework import TestFramework
 
 cases = ["disu01a", "disu01b"]
+grb_filename = "disu.grb"
 
 
 def build_models(idx, test):
@@ -43,7 +44,7 @@ def build_models(idx, test):
     tdis = flopy.mf6.ModflowTdis(sim)
     gwf = flopy.mf6.ModflowGwf(sim, modelname=name)
     ims = flopy.mf6.ModflowIms(sim, print_option="SUMMARY")
-    disu = flopy.mf6.ModflowGwfdisu(gwf, **disukwargs)
+    disu = flopy.mf6.ModflowGwfdisu(gwf, grb_filerecord=grb_filename, **disukwargs)
     ic = flopy.mf6.ModflowGwfic(gwf, strt=0.0)
     npf = flopy.mf6.ModflowGwfnpf(gwf)
     spd = {0: [[(0,), 1.0], [(nrow * ncol - 1), 0.0]]}
@@ -52,9 +53,7 @@ def build_models(idx, test):
 
 
 def check_output(idx, test):
-    name = test.name
-
-    fname = os.path.join(test.workspace, name + ".disu.grb")
+    fname = Path(test.workspace) / grb_filename
     grbobj = flopy.mf6.utils.MfGrdFile(fname)
     nodes = grbobj._datadict["NODES"]
     ia = grbobj._datadict["IA"]

autotest/test_gwf_disv.py

@@ -7,7 +7,7 @@
 in binary grid file is correct.
 """
 
-import os
+from pathlib import Path
 
 import flopy
 import numpy as np
@@ -16,6 +16,7 @@
 from framework import TestFramework
 
 cases = ["disv01a", "disv01b"]
+grb_filename = "disv.grb"
 
 
 def build_models(idx, test):
@@ -46,7 +47,7 @@ def build_models(idx, test):
     tdis = flopy.mf6.ModflowTdis(sim)
     gwf = flopy.mf6.ModflowGwf(sim, modelname=name)
     ims = flopy.mf6.ModflowIms(sim, print_option="SUMMARY")
-    disv = flopy.mf6.ModflowGwfdisv(gwf, **disvkwargs)
+    disv = flopy.mf6.ModflowGwfdisv(gwf, grb_filerecord=grb_filename, **disvkwargs)
     ic = flopy.mf6.ModflowGwfic(gwf, strt=0.0)
     npf = flopy.mf6.ModflowGwfnpf(gwf)
     spd = {0: [[(0, 0), 1.0], [(0, nrow * ncol - 1), 0.0]]}
@@ -55,9 +56,7 @@ def build_models(idx, test):
 
 
 def check_output(idx, test):
-    name = test.name
-
-    fname = os.path.join(test.workspace, name + ".disv.grb")
+    fname = Path(test.workspace) / grb_filename
     grbobj = flopy.mf6.utils.MfGrdFile(fname)
     ncpl = grbobj._datadict["NCPL"]
     ia = grbobj._datadict["IA"]

doc/ReleaseNotes/develop.tex

@@ -8,6 +8,7 @@ \subsection{Version mf6.6.1---February 7, 2025}
 \begin{itemize}
 	\item Support for adjusting time step lengths using the adaptive time stepping (ATS) capability was added to the GWT Advection (ADV) Package of the Groundwater Transport (GWT) Model in release 6.6.0.  The same functionality that was added to GWT is now available with the Groundwater Energy Transport (GWE) Model.  A description of how this functionality works and how to activate it can be found in the release notes for version 6.6.0 (Appendix A) and in the MODFLOW 6 input-output guide.
 	\item The binary grid file written by MODFLOW 6 for DISU models did not include the IDOMAIN array.  The binary grid file now includes IDOMAIN for all discretization types, including DISU.
+	\item The binary grid file's name may now be specified in all discretization packages with option GRB6 FILEOUT followed by a file path. If this option is not provided, the binary grid file will be named as before, identical to the discretization file name plus a ``.grb'' extension. Note that renaming the binary grid file may break downstream integrations which expect the default name.
 %	\item xxx
 \end{itemize}
 

doc/mf6io/framework/binaryoutput.tex

@@ -6,7 +6,7 @@
 
 \newpage
 \subsection{Binary Grid File}
-\mf~writes a binary grid file that can be used for post processing model results.  The file structure was designed to be self-documenting so that it can evolve if necessary.  The file name is assigned automatically by the program by adding ``.grb'' to the end of the discretization input file name.  The structure of the binary grid file depends on the type of discretization package that is used.  The following subsections summarize the binary grid file for the different grid types.  The red text is not written to the binary grid file, but is shown here to explain the file content.  The binary grid file is written for the GWF Model, but is not written for the GWT Model.
+\mf~writes a binary grid file that can be used for post processing model results.  The file structure was designed to be self-documenting so that it can evolve if necessary.  By default, the file name is assigned automatically by the program by adding ``.grb'' to the end of the discretization input file name.  Alternatively, the binary grid file name may be specified in the relevant discretization input file.  The structure of the binary grid file depends on the type of discretization package that is used.  The following subsections summarize the binary grid file for the different grid types.  The red text is not written to the binary grid file, but is shown here to explain the file content.  The binary grid file is written for the GWF Model, but is not written for the GWT Model.
 
 \newpage
 \subsubsection{DIS Grids}

doc/mf6io/mf6ivar/dfn/chf-disv1d.dfn

@@ -16,6 +16,48 @@ optional true
 longname do not write binary grid file
 description keyword to deactivate writing of the binary grid file.
 
+block options
+name grb_filerecord
+type record grb6 fileout grb6_filename
+reader urword
+tagged true
+optional true
+longname
+description
+
+block options
+name grb6
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname grb keyword
+description keyword to specify that record corresponds to a binary grid file.
+extended true
+
+block options
+name fileout
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname file keyword
+description keyword to specify that an output filename is expected next.
+
+block options
+name grb6_filename
+type string
+preserve_case true
+in_record true
+reader urword
+optional false
+tagged false
+longname file name of GRB information
+description defines a binary grid output file. If this option is not provided, the output file will have the same name as the discretization input file, plus extension ``.grb''.
+extended true
+
 block options
 name xorigin
 type double precision

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

@@ -17,6 +17,48 @@ optional true
 longname do not write binary grid file
 description keyword to deactivate writing of the binary grid file.
 
+block options
+name grb_filerecord
+type record grb6 fileout grb6_filename
+reader urword
+tagged true
+optional true
+longname
+description
+
+block options
+name grb6
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname grb keyword
+description keyword to specify that record corresponds to a binary grid file.
+extended true
+
+block options
+name fileout
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname file keyword
+description keyword to specify that an output filename is expected next.
+
+block options
+name grb6_filename
+type string
+preserve_case true
+in_record true
+reader urword
+optional false
+tagged false
+longname file name of GRB information
+description defines a binary grid output file. If this option is not provided, the output file will have the same name as the discretization input file, plus extension ``.grb''.
+extended true
+
 block options
 name xorigin
 type double precision

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

@@ -16,6 +16,48 @@ optional true
 longname do not write binary grid file
 description keyword to deactivate writing of the binary grid file.
 
+block options
+name grb_filerecord
+type record grb6 fileout grb6_filename
+reader urword
+tagged true
+optional true
+longname
+description
+
+block options
+name grb6
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname grb keyword
+description keyword to specify that record corresponds to a binary grid file.
+extended true
+
+block options
+name fileout
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname file keyword
+description keyword to specify that an output filename is expected next.
+
+block options
+name grb6_filename
+type string
+preserve_case true
+in_record true
+reader urword
+optional false
+tagged false
+longname file name of GRB information
+description defines a binary grid output file. If this option is not provided, the output file will have the same name as the discretization input file, plus extension ``.grb''.
+extended true
+
 block options
 name xorigin
 type double precision

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

@@ -17,6 +17,48 @@ optional true
 longname do not write binary grid file
 description keyword to deactivate writing of the binary grid file.
 
+block options
+name grb_filerecord
+type record grb6 fileout grb6_filename
+reader urword
+tagged true
+optional true
+longname
+description
+
+block options
+name grb6
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname grb keyword
+description keyword to specify that record corresponds to a binary grid file.
+extended true
+
+block options
+name fileout
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname file keyword
+description keyword to specify that an output filename is expected next.
+
+block options
+name grb6_filename
+type string
+preserve_case true
+in_record true
+reader urword
+optional false
+tagged false
+longname file name of GRB information
+description defines a binary grid output file. If this option is not provided, the output file will have the same name as the discretization input file, plus extension ``.grb''.
+extended true
+
 block options
 name xorigin
 type double precision

doc/mf6io/mf6ivar/dfn/gwf-dis.dfn

@@ -17,6 +17,48 @@ optional true
 longname do not write binary grid file
 description keyword to deactivate writing of the binary grid file.
 
+block options
+name grb_filerecord
+type record grb6 fileout grb6_filename
+reader urword
+tagged true
+optional true
+longname
+description
+
+block options
+name grb6
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname grb keyword
+description keyword to specify that record corresponds to a binary grid file.
+extended true
+
+block options
+name fileout
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname file keyword
+description keyword to specify that an output filename is expected next.
+
+block options
+name grb6_filename
+type string
+preserve_case true
+in_record true
+reader urword
+optional false
+tagged false
+longname file name of GRB information
+description defines a binary grid output file. If this option is not provided, the output file will have the same name as the discretization input file, plus extension ``.grb''.
+extended true
+
 block options
 name xorigin
 type double precision

doc/mf6io/mf6ivar/dfn/gwf-disu.dfn

@@ -16,6 +16,48 @@ optional true
 longname do not write binary grid file
 description keyword to deactivate writing of the binary grid file.
 
+block options
+name grb_filerecord
+type record grb6 fileout grb6_filename
+reader urword
+tagged true
+optional true
+longname
+description
+
+block options
+name grb6
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname grb keyword
+description keyword to specify that record corresponds to a binary grid file.
+extended true
+
+block options
+name fileout
+type keyword
+in_record true
+reader urword
+tagged true
+optional false
+longname file keyword
+description keyword to specify that an output filename is expected next.
+
+block options
+name grb6_filename
+type string
+preserve_case true
+in_record true
+reader urword
+optional false
+tagged false
+longname file name of GRB information
+description defines a binary grid output file. If this option is not provided, the output file will have the same name as the discretization input file, plus extension ``.grb''.
+extended true
+
 block options
 name xorigin
 type double precision