feat(specified flux boundaries): implement general specified flux perimeter boundary

docs/source/concepts/perimeter-bcs.rst

@@ -7,12 +7,14 @@ Often the area we are trying to model is part of a larger flow system, and we mu
 
 Features and Limitations
 -------------------------
-* Currently, specified head perimeter boundaries are supported via the MODFLOW 6 Constant Head (CHD) Package; specified flux boundaries using the MODFLOW 6 Well (WEL) Package are in `active development <https://github.com/aleaf/modflow-setup/issues/25>`_. It is envisioned that specified flux perimeter cells will follow the same basic structure/conceptualization as specified heads.
+* Currently, specified head perimeter boundaries are supported via the MODFLOW Constant Head (CHD) Package; specified flux boundaries are supported via the MODFLOW Well (WEL) Package.
 * The parent model solution (providing the values for the boundaries) is assumed to align with the inset model time discretization.
 * The parent model may have different length units.
 * The parent model may be of a different MODFLOW version (e.g. MODFLOW 6 inset with a MODFLOW-NWT parent)
-* The inset model grid need not align with the parent model grid; values from the parent model solution are interpolated linearly to the cell centers along the inset model perimeter in the x, y and z directions (using a barycentric triangular method similar to :py:func:`scipy.interpolate.griddata`). However, this means that there may be some mismatch between the parent and inset model solutions along the inset model perimeter, in places where there are abrupt or non-linear head gradients. Boundaries for inset models should always be set sufficiently far away that they do not appreciably impact the model solution in the area(s) of interest. The :ref:`LGR capability <Pleasant Lake test case>` of Modflow-setup can help with this.
+* For specified head perimeter boundaries, the inset model grid need not align with the parent model grid; values from the parent model solution are interpolated linearly to the cell centers along the inset model perimeter in the x, y and z directions (using a barycentric triangular method similar to :py:func:`scipy.interpolate.griddata`). However, this means that there may be some mismatch between the parent and inset model solutions along the inset model perimeter, in places where there are abrupt or non-linear head gradients. Boundaries for inset models should always be set sufficiently far away that they do not appreciably impact the model solution in the area(s) of interest. The :ref:`LGR capability <Pleasant Lake test case>` of Modflow-setup can help with this.
+* Specified flux boundaries are currently limited to the parent and inset models being colinear.
 * The perimeter may be irregular. For example, the edge of the model active area may follow a major surface water feature along the opposite side.
+* Specified perimeter heads in MODFLOW-NWT models will have ending heads for each stress period assigned from the starting head of the next stress period (with the last period having the same starting and ending heads). The MODFLOW 6 Constant Head Package only supports assignment of a single head per stress period. This distinction only matters for models where stress periods are subdivided by multiple timesteps.
 
 
 Input
@@ -36,14 +38,25 @@ Input to set up perimeter boundaries are specified in two places:
 
 2) In a ``perimeter_boundary:`` sub-block for the relevant package (only specified heads via CHD are currently supported).
 
-    Input example:
+    Input example (specified head):
 
     .. code-block:: yaml
 
       chd:
         perimeter_boundary:
             parent_head_file: 'data/pleasant/pleasant.hds'
 
+    Input example (specified flux, with optional shapefile defining an irregular perimeter boundary,
+    and the MODFLOW 6 binary grid file, which is required for reading the cell budget output from MODFLOW 6 parent models):
+
+    .. code-block:: yaml
+
+      wel:
+        perimeter_boundary:
+          shapefile: 'shellmound/tmr_parent/gis/irregular_boundary.shp'
+          parent_cell_budget_file: 'shellmound/tmr_parent/shellmound.cbc'
+          parent_binary_grid_file: 'shellmound/tmr_parent/shellmound.dis.grb'
+
 
 Time discretization
 -------------------

docs/source/input/basic-stress.rst

@@ -5,10 +5,6 @@ Specifying boundary conditions with the 'basic' MODFLOW stress packages
 .. note::
    This page is a work in progress and needs some more work.
 
-.. note::
-   Basic stress packages are currenly only supported for Modflow 6, except
-   for the Constant Head (CHD) package in the context of perimeter boundary conditions.
-
 This page describes configuration file input for the basic MODFLOW stress packages, including
 the CHD, DRN, GHB, RCH, RIV and WEL packages. The EVT package is not currently supported by Modflow-setup. The supported packages can be broadly placed into two categories. Feature or list-based packages such as CHD, DRN, GHB, RIV and WEL often represent discrete phenomena such as surface water features, pumping wells, or even lines that denote a perimeter boundary. Input to  these packages in MODFLOW is tabular, consisting of a table for each stress period, with rows specifying stresses at individual grid cells representing the boundary features. In contrast, continuous or grid-based packages represent a stress field that applies to a large area, such as areal recharge. In past versions of MODFLOW, input to these packages was array-based, with values specified for all model cells, at each stress period. In MODFLOW 6, input to these packages can be array or list-based. The Recharge (RCH) Package is currently the only grid-based stress package supported by Modflow-setup. In keeping with the current structured grid-based paradigm of Modflow-setup, Modflow 6 recharge input is generated for the array-based recharge package (Langevin and others, 2017).
 
@@ -59,7 +55,11 @@ Input for list-based basic stress packages follows a similar pattern to other pa
             * scalar values (items) are applied globally to the variable
             * rasters can be used to specify steady-state values that vary in space; values supplied with a raster are mapped to the model grid using zonal statistics. If the raster contains projection information (GeoTIFFs are preferred in part because of this), any reprojection to the model coorindate reference system (CRS) will be performed automatically as needed. Otherwise, the raster is assumed to be in the model projection.
             * (Not implemented yet) NetCDF input for gridded values that vary in time and space. Due to the lack of standardization in NetCDF coordinate reference information, automatic reprojection is currently not supported for NetCDF files; the data are assumed to be in the model CRS.
+    * ``mfsetup_options:`` Configuration options for Modflow-setup. General options that apply to all basic stress packages include:
+            * ``external_files:`` Whether to write the package input as external text arrays or tables (i.e., with ``open/close`` statements). By default ``True`` except in the case of list-based or tabular files for MODFLOW-NWT models, which are not supported. Adding support for this may require changes to Flopy, which handles external list-based files differently for MODFLOW-2005 style models.
+            * ``external_filename_fmt:`` Python string format for external file names. By default, ``"<package or variable abbreviation>_{:03d}.dat"``. which results in filenames such as ``wel_000.dat``, ``wel_001.dat``, ``wel_002.dat``... for stress periods 0, 1, and 2, for example.
 
+            Other Modflow-setup options specific to individual packages are described below.
 
 Constant Head (CHD) Package
 ++++++++++++++++++++++++++++++
@@ -87,7 +87,7 @@ Input consists of specified head values that may vary in time or space.
 
     .. literalinclude:: ../../../mfsetup/tests/data/shellmound.yml
         :language: yaml
-        :lines: 285-296
+        :lines: 285-298
 
 
 Drain DRN Package
@@ -136,7 +136,7 @@ Input consists of head elevations and conductances that may vary in time or spac
 
     .. literalinclude:: ../../../mfsetup/tests/data/shellmound.yml
         :language: yaml
-        :lines: 316-335
+        :lines: 316-337
 
 River (RIV) package
 ++++++++++++++++++++
@@ -162,7 +162,7 @@ Input consists of stages, river bottom elevations and conductances,
 
     .. literalinclude:: ../../../mfsetup/tests/data/shellmound.yml
         :language: yaml
-        :lines: 338-356
+        :lines: 338-358
 
     Example of setting up the RIV package using SFRmaker (via the ``sfr:`` block):
 
@@ -206,7 +206,7 @@ Input consists of flux rates that may vary in time or space.
 
             .. literalinclude:: ../../../mfsetup/tests/data/shellmound.yml
                 :language: yaml
-                :lines: 359-386
+                :lines: 359-388
 
     * ``wdnr_dataset`` block
         .. note::
@@ -219,9 +219,9 @@ Input consists of flux rates that may vary in time or space.
 
         * Example:
 
-            .. literalinclude:: ../../../examples/pleasant_lgr_inset.yml
+            .. literalinclude:: ../../../mfsetup/tests/data/pfl_nwt_test.yml
                 :language: yaml
-                :lines: 79-86
+                :lines: 113-118
 
     **The** ``vertical_flux_distribution:`` **sub-block**
         * This sub-block specifies how Well Packages fluxes should be distributed vertically.

docs/source/philosophy.rst

@@ -27,8 +27,8 @@ In contrast to Flopy, which is completely general, modflow-setup limits model co
 
 
 
-.. _Configuration File Gallery: https://aleaf.github.io/modflow-setup/docs/build/html/examples.html#configuration-file-gallery
-.. _Release History: https://aleaf.github.io/modflow-setup/release-history.html
+.. _Configuration File Gallery: https://usgs.github.io/modflow-setup/docs/build/html/examples.html#configuration-file-gallery
+.. _Release History: https://usgs.github.io/modflow-setup/release-history.html
 .. _hydrosense: https://ngwa.onlinelibrary.wiley.com/doi/abs/10.1111/j.1745-6584.2012.00936.x
 
 .. _step-wise modeling: https://www.haitjema.com/stepwise.html

docs/source/release-history.rst

@@ -2,19 +2,23 @@
 Release History
 ===============
 
-Version 0.1 Initial release (2022-04-01)
+Version 0.1 Initial release (2022-xx-xx)
 ----------------------------------------
 * support for constructing MODFLOW-NWT or MODFLOW-6 models from scratch
 * supported source dataset formats include GeoTiff, Arc-Ascii grids, shapefiles, NetCDF, and CSV files
 * automatic reprojection of source datasets that have CRS information (GeoTiffs, shapefiles, etc.)
-* model input can also be supplied from parent model package input or MODFLOW binary output
-* supported MODFLOW-NWT packages: DIS, BAS6, OC, UPW, RCH, GHB, SFR2, LAK, WEL, MNW2, HYD, GAGE, NWT
+* supported MODFLOW-NWT packages: DIS, BAS6, OC, UPW, RCH, GHB, SFR2, LAK, WEL, MNW2, HYD, GAGE, NWT, CHD, DRN, GHB, RIV
 * supported MODFLOW-6 packages: DIS, IC, OC, NPF, RCHA, SFR, LAK, WEL, OBS, IMS, TDIS, CHD, DRN, GHB, RIV
-* Lake observations are set up automatically (one output file per lake)
+* Lake observations are set up automatically (one output file per lake); basic stress package observations are also setup up automatically
 * SFR observations can be set up via ``observations`` block in the SFR package ``source_data``
 * Telescopic mesh refinement (TMR) insets from MODFLOW-NWT or MODFLOW 6 models
-    * support for specified head boundaries from parent head solution
-    * specified head boundaries can be along model perimeter or irregular polygon of model active area
+    * support for specified head or flux perimeter boundaries from the parent model solution
+    * perimeter boundaries can be along the model bounding box perimeter, or an irregular polygon of the active model area
+    * model input can also be supplied from grid-independent source data, parent model package input (except for SFR, LAK, CHD, DRN, GHB, RIV), or MODFLOW binary output (perimeter boundaries and starting heads)
+
 * Local grid refinement (LGR) insets supported for MODFLOW-6 models.
-  * The water mover (MVR) package is set up automatically at the simulation level for LGR models with SFR packages in the parent and inset model.
-* see .yml configuation files in mfsetup/tests/data folder for examples of valid input to modflow-setup
+    * The water mover (MVR) package is set up automatically at the simulation level for LGR models with SFR packages in the parent and inset model.
+
+* see the `Configuration File Gallery`_ or the ``*.yml`` configuation files in mfsetup/tests/data folder for examples of valid input to modflow-setup
+
+.. _Configuration File Gallery: https://usgs.github.io/modflow-setup/docs/build/html/examples.html#configuration-file-gallery