feat(docs): add perimeter boundaries and troubleshooting sections

docs/source/api/index.rst

@@ -21,3 +21,4 @@ Supporting modules
    mfsetup.fileio
    mfsetup.grid
    mfsetup.tdis
+   mfsetup.tmr

docs/source/api/mfsetup.tmr.rst

@@ -0,0 +1,8 @@
+mfsetup.tmr module
+=============================
+
+.. automodule:: mfsetup.tmr
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :exclude-members: Tmr

docs/source/concepts/perimeter-bcs.rst

@@ -2,4 +2,97 @@
 Specifying perimeter boundary conditions from another model
 ===========================================================
 
-Often the area we are trying to model is part of a larger flow system, and we must account for groundwater flow across the model boundaries.
+Often the area we are trying to model is part of a larger flow system, and we must account for groundwater flow across the model boundaries. Modflow-setup allows for perimeter boundary conditions to be specified from the groundwater flow solution of another Modflow model.
+
+
+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.
+* 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.
+* 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.
+
+
+Input
+-------------------
+Input to set up perimeter boundaries are specified in two places:
+
+1) The ``parent:`` model block, in which a parent or source model can be specified. Currently only a single parent or source model is supported. The parent or source model can be used for other properties (e.g. hydraulic conductivity) and stresses (e.g. recharge) in addition to the perimeter boundary.
+
+    Input example:
+
+    .. code-block:: yaml
+
+      parent:
+        namefile: 'pleasant.nam'
+        model_ws: 'data/pleasant/'
+        version: 'mfnwt'
+        copy_stress_periods: 'all'
+        start_date_time: '2012-01-01'
+        length_units: 'meters'
+        time_units: 'days'
+
+2) In a ``perimeter_boundary:`` sub-block for the relevant package (only specified heads via CHD are currently supported).
+
+    Input example:
+
+    .. code-block:: yaml
+
+      chd:
+        perimeter_boundary:
+            parent_head_file: 'data/pleasant/pleasant.hds'
+
+
+Time discretization
+-------------------
+By default, inset model stress period 0 is assumed to align with parent model stress period zero (``copy_stress_periods: 'all'`` in the :ref:`configuration file <The configuration file>` parent block, which is the default). Alternatively, stress periods can be mapped explicitly using a dictionary. For example:
+
+.. code-block:: yaml
+
+  copy_stress_periods:
+    0: 1
+    1: 2
+    2: 3
+
+where ``0: 1`` indicates that the first stress period in the inset model aligns with the second stress period in the parent model (stress period 1), etc.
+
+
+Specifying the locations of perimeter boundary cells
+----------------------------------------------------
+Modflow-setup provides 3 primary options for specifying the locations of perimeter cells. In all cases, boundary cells are produced by the :meth:`mfsetup.tmr.TmrNew.get_inset_boundary_cells` method, and the resulting cells (including the boundary faces) can be visualized in a GIS environment with the ``boundary_cells.shp`` shapefile that gets written to the ``tables/`` folder by default.
+
+**1) No specification of where the perimeter boundary should be applied** (e.g. a shapefile) and ``by_layer=False:`` (the default). Perimeter BC cells are applied to active cells that coincide with the edge of the maximum areal footprint of the active model area. In places where the edge of the active area is inside of the max active footprint, no perimeter cells are applied.
+
+    Input example:
+
+    .. code-block:: yaml
+
+      chd:
+          perimeter_boundary:
+            parent_head_file: 'data/pleasant/pleasant.hds'
+
+
+**2) No specification of where the perimeter boundary should be applied and ``by_layer=True:``**. This is the same as option 1), but the active footprint is defined by layer from the idomain array. This option is generally not recommended, as it may often lead to boundary cells being included in the model interior (along layer pinch-outs, for example). Users of this option should check the results carefully by inspecting the
+
+    Input example:
+
+    .. code-block:: yaml
+
+      chd:
+          perimeter_boundary:
+            parent_head_file: 'data/pleasant/pleasant.hds'
+            by_layer: True
+
+**3) Specification of perimeter boundary cells with a shapefile**. The locations of perimeter cells can be explicitly specified this way, but they still must coincide with the edge of the active extent in each layer (Modflow-setup will not put perimeter cells in the model interior). (Open) Polyline or Polygon shapefiles can be used; in either case a buffer is used to align the supplied features with the active area edge, which is determined using the :py:func:`Sobel edge detection filter in Scipy <scipy.ndimage.sobel>`.
+
+
+    Input example:
+
+    .. code-block:: yaml
+
+      chd:
+          perimeter_boundary:
+            shapefile: 'shellmound/tmr_parent/gis/irregular_boundary.shp'
+            parent_head_file: 'shellmound/tmr_parent/shellmound.hds'

docs/source/conf.py

@@ -232,5 +232,6 @@
     'numpy': ('https://docs.scipy.org/doc/numpy/', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
+    'pyproj': ('https://pyproj4.github.io/pyproj/stable/', None),
     'matplotlib': ('https://matplotlib.org', None),
 }

docs/source/contributing.rst

@@ -5,24 +5,73 @@ Contributing to modflow-setup
 which has similar guidelines to `pandas <http://pandas.pydata.org/pandas-docs/stable/contributing.html>`_
 and `xarray <http://xarray.pydata.org/en/stable/>`_.)
 
-Overview
---------
+Getting started
+----------------
+All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. If an issue that interests you isn't already listed in the `Issues tab`_, consider `filing an issue`_.
 
-Contributions to modflow-setup are very welcome.  They are likely to
-be accepted more quickly if they follow these guidelines.
+Bug reports and enhancement requests
+------------------------------------------------
+Bug reports are an important part of improving Modflow-setup. Having a complete bug report
+will allow others to reproduce the bug and provide insight into fixing. See
+`this stackoverflow article <https://stackoverflow.com/help/mcve>`_ and
+`this blogpost <https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports>`_
+for tips on writing a good bug report.
 
-In general, modflow-setup follows the conventions of the pandas project
-where applicable.
+Trying the bug-producing code out on the *develop* branch is often a worthwhile exercise
+to confirm the bug still exists. It is also worth searching existing bug reports and pull requests
+to see if the issue has already been reported and/or fixed.
+
+To file a bug report or enhancement request, from the issues tab on the `Modflow-setup GitHub page <https://github.com/aleaf/modflow-setup>`_, select "New Issue".
+
+Bug reports must:
+
+#. Include a short, self-contained Python snippet reproducing the problem, along with the contents of your configuration file and the full error traceback.
+   You can format the code nicely by using `GitHub Flavored Markdown
+   <https://github.github.com/github-flavored-markdown/>`_::
+
+      ```python
+      >>> import mfsetup
+      >>> m = MF6model.setup_from_yaml('pleasant_lgr_parent.yml')
+      ```
+
+   e.g.::
+
+      ```yaml
+      <paste configuration file contents here>
+      ```
+
+      ```python
+      <paste error traceback here>
+      ```
+
+#. Include the version of Modflow-setup that you are running, which can be obtained with:
+
+   .. code-block:: python
+
+       import mfsetup
+       mfsetup.__version__
+
+   Depending on the issue, it may also be helpful to include information about the version(s)
+   of python, key dependencies (e.g. numpy, pandas, etc) and operating system. You can get the versions of packages in a conda python environment with::
+
+        conda list
+
+#. Explain why the current behavior is wrong/not desired and what you expect instead.
+
+The issue will then be visible on the `Issues tab`_ and open to comments/ideas from others.
+
+
+Code contributions
+------------------------------
+Code contributions to Modflow-setup to fix bugs, implement new features or improve existing code are encouraged. Regardless of the context, consider `filing an issue`_ first to make others aware of the problem and allow for discussion on potential approaches to addressing it.
+
+In general, Modflow-setup trys to follow the conventions of the pandas project where applicable. Contributions to Modflow-setup are likely to be accepted more quickly if they follow these guidelines.
 
 In particular, when submitting a pull request:
 
 - All existing tests should pass.  Please make sure that the test
   suite passes, both locally and on
-  `Travis CI <https://travis-ci.org/modflow-setup/modflow-setup>`_.  Status on
-  Travis will be visible on a pull request.  If you want to enable
-  Travis CI on your own fork, please read the pandas guidelines link
-  above or the
-  `getting started docs <https://docs.travis-ci.com/user/tutorial/>`_.
+  `GitHub Actions <https://github.com/aleaf/modflow-setup/actions>`_. Status with GitHub Actions will be visible on a pull request.
 
 - New functionality should include tests.  Please write reasonable
   tests for your code and make sure that they pass on your pull request.
@@ -283,3 +332,6 @@ From the root of the modflow-setup repository, you should then install the
    $ pre-commit install
 
 Then ``isort`` will be run automatically each time you commit changes. You can skip these checks with ``git commit --no-verify``.
+
+.. _filing an issue: https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/creating-an-issue
+.. _Issues tab: https://github.com/aleaf/modflow-setup/issues

docs/source/index.rst

@@ -28,6 +28,7 @@ Modflow-setup is intended to facilitate automated setup of MODFLOW models, from
    Basic program structure and usage <structure>
    The configuration file <config-file>
    Concepts and Methods <concepts/index.rst>
+   Troubleshooting <troubleshooting>
 
 
 .. toctree::

docs/source/troubleshooting.rst

@@ -0,0 +1,25 @@
+Troubleshooting
+================
+
+My script doesn't run
+----------------------
+Before filing a :ref:`bug report <Bug reports and enhancement requests>`, check these possible solutions:
+
+Updating your python environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Check the versions of python and the various package dependencies (especially Numpy) in the environment that you are using with ``conda list``.
+
+* Is your python version more than 1 minor release out of date (e.g. 3.7 if the current version is 3.9)?
+* Has it been a year or more since your conda environment was created or updated?
+
+**It might be time for a fresh environment.** Modflow-setup mostly follows the `Numpy guidelines for package support <https://numpy.org/neps/nep-0029-deprecation_policy.html>`_, which means that the two latest minor versions of Python (e.g. 3.9 and 3.8) and their associated Numpy versions will be supported.
+
+:ref:`Instructions for updating your conda environment <Keeping the Conda environment up to date>`
+
+Updating Modflow-setup
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``conda list`` can also be used to check if you Modflow-setup is up to date.
+
+* if you installed Modflow-setup from GitHub and you need to incorporate a recently pushed bug fix: ``pip install --upgrade git+git://github.com/aleaf/modflow-setup@develop``
+* if you cloned the Modflow-setup source code and need to incorporate a recently pushed bug fix, you will need to pull (``git pull``) and possibly reinstall (``pip install --upgrade -e .`` in the root folder of the source code).
+* in both cases, the version reported by ``conda list`` should match the latest commit hash. For example version ``0.post250.dev0+g9af1c61`` for the commit hash starting with ``9af1c61``.