docs(prt): several fixes/clarifications (#1885)

Improve source code comments and MF6IO descriptions:

* top/bottom IFLOWFACE settings were not mentioned
* clarify comment on IFLOWFACE mapping in PRT FMI
* clarify that TRACK_EXIT includes model/subcell exits
* rerun doc/mf6io/mf6ivar/mf6ivar.py

Author: wpbonelli

doc/SuppTechInfo/particle-tracking-model.tex

@@ -22,7 +22,7 @@ \subsection{Tracking Approach} \label{sec:trackingapproach}
 
 \noindent On DISV grids, which can contain a mix of rectangular, quad-refined, and non-rectangular cells, the PRT Model identifies the geometry of each cell and applies the most efficient tracking method possible. Rectagular cells do not need to be aligned with the model coordinate axes to be recognized as rectangular. Because measures of the cell geometry are compared with numerical tolerances, it is recommended that the cell vertex coordinates be written to double precision in the model input for a DISV grid.
 
-By default, flows associated with stress packages are assumed to be distributed uniformly over the volume of a cell, as in MODPATH 7. Distributed external inflows and outflows are reflected in the cell-cell flows calculated by the GWF Model, but they are not directly involved in determining the normal face velocities used to track a particle through the cell. The user can optionally assign a flow associated with a stress package to any face of the cell. In MODPATH 7, this is done by setting the value of an input parameter called IFACE to a value that corresponds to one of the six faces of a rectangular cell (left, right, front, back, bottom, and top). In the PRT Model, assignment of external flows is done by setting the value of an input parameter called IFLOWFACE to a value that corresponds to one of the cell faces. To accommodate non-rectangular cells, the face numbering scheme in the PRT Model is different from that in MODPATH 7 and is based on clockwise ordering of the cell faces, as described in the \mf input instructions.
+By default, flows associated with stress packages are assumed to be distributed uniformly over the volume of a cell, as in MODPATH 7. Distributed external inflows and outflows are reflected in the cell-cell flows calculated by the GWF Model, but they are not directly involved in determining the normal face velocities used to track a particle through the cell. The user can optionally assign a flow associated with a stress package to any face of the cell. In MODPATH 7, this is done by setting the value of an input parameter called IFACE to a value that corresponds to one of the six faces of a rectangular cell (left, right, front, back, bottom, and top). In the PRT Model, assignment of external flows is done by setting the value of an input parameter called IFLOWFACE to a value that corresponds to one of the cell faces. To accommodate non-rectangular cells, the face numbering scheme in the PRT Model is different from that in MODPATH 7, as described in the \mf input instructions.
 
 \subsection{Generalized Pollock's Method For Non-Rectangular Cells} \label{sec:genpollockmethod}
 

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

@@ -157,7 +157,7 @@ type keyword
 reader urword
 optional true
 longname track transitions
-description keyword to indicate that particle tracking output is to be written when a particle exits a cell
+description keyword to indicate that particle tracking output is to be written when a particle exits a feature (a model, cell, or subcell)
 
 block options
 name track_timestep

doc/mf6io/mf6ivar/md/mf6ivar.md

@@ -1096,7 +1096,10 @@
 | GWF | STO | OPTIONS | SS_CONFINED_ONLY | KEYWORD | keyword to indicate that compressible storage is only calculated for a convertible cell (ICONVERT>0) when the cell is under confined conditions (head greater than or equal to the top of the cell). This option has no effect on cells that are marked as being always confined (ICONVERT=0).  This option is identical to the approach used to calculate storage changes under confined conditions in MODFLOW-2005. |
 | GWF | STO | OPTIONS | TVS6 | KEYWORD | keyword to specify that record corresponds to a time-varying storage (TVS) file.  The behavior of TVS and a description of the input file is provided separately. |
 | GWF | STO | OPTIONS | FILEIN | KEYWORD | keyword to specify that an input filename is expected next. |
-| GWF | STO | OPTIONS | TVS_FILENAME | STRING | defines a time-varying storage (TVS) input file.  Records in the TVS file can be used to change specific storage and specific yield properties at specified times or stress periods. |
+| GWF | STO | OPTIONS | TVS6_FILENAME | STRING | defines a time-varying storage (TVS) input file.  Records in the TVS file can be used to change specific storage and specific yield properties at specified times or stress periods. |
+| GWF | STO | OPTIONS | EXPORT_ARRAY_ASCII | KEYWORD | keyword that specifies input grid arrays, which already support the layered keyword, should be written to layered ascii output files. |
+| GWF | STO | OPTIONS | DEV_ORIGINAL_SPECIFIC_STORAGE | KEYWORD | flag indicating the original storage specific storage formulation should be used |
+| GWF | STO | OPTIONS | DEV_OLDSTORAGEFORMULATION | KEYWORD | development option flag for old storage formulation |
 | GWF | STO | GRIDDATA | ICONVERT | INTEGER (NODES) | is a flag for each cell that specifies whether or not a cell is convertible for the storage calculation. 0 indicates confined storage is used. $>$0 indicates confined storage is used when head is above cell top and a mixed formulation of unconfined and confined storage is used when head is below cell top. |
 | GWF | STO | GRIDDATA | SS | DOUBLE PRECISION (NODES) | is specific storage (or the storage coefficient if STORAGECOEFFICIENT is specified as an option). Specific storage values must be greater than or equal to 0. If the CSUB Package is included in the GWF model, specific storage must be zero for every cell. |
 | GWF | STO | GRIDDATA | SY | DOUBLE PRECISION (NODES) | is specific yield. Specific yield values must be greater than or equal to 0. Specific yield does not have to be specified if there are no convertible cells (ICONVERT=0 in every cell). |
@@ -1592,7 +1595,7 @@
 | PRT | OC | OPTIONS | TRACKCSV | KEYWORD | keyword to specify that record corresponds to a CSV track file.  Each PRT Model's OC Package may have only one CSV track file. |
 | PRT | OC | OPTIONS | TRACKCSVFILE | STRING | name of the comma-separated value (CSV) file to write tracking information. |
 | PRT | OC | OPTIONS | TRACK_RELEASE | KEYWORD | keyword to indicate that particle tracking output is to be written when a particle is released |
-| PRT | OC | OPTIONS | TRACK_EXIT | KEYWORD | keyword to indicate that particle tracking output is to be written when a particle exits a cell |
+| PRT | OC | OPTIONS | TRACK_EXIT | KEYWORD | keyword to indicate that particle tracking output is to be written when a particle exits a feature (a model, cell, or subcell) |
 | PRT | OC | OPTIONS | TRACK_TIMESTEP | KEYWORD | keyword to indicate that particle tracking output is to be written at the end of each time step |
 | PRT | OC | OPTIONS | TRACK_TERMINATE | KEYWORD | keyword to indicate that particle tracking output is to be written when a particle terminates for any reason |
 | PRT | OC | OPTIONS | TRACK_WEAKSINK | KEYWORD | keyword to indicate that particle tracking output is to be written when a particle exits a weak sink (a cell which removes some but not all inflow from adjacent cells) |
@@ -1800,6 +1803,7 @@
 | SWF | OC | PERIOD | FREQUENCY | INTEGER | save at the specified time step frequency. This keyword may be used in conjunction with other keywords to print or save results for multiple time steps. |
 | SWF | OC | PERIOD | STEPS | INTEGER (<NSTP) | save for each step specified in STEPS. This keyword may be used in conjunction with other keywords to print or save results for multiple time steps. |
 | SWF | STO | OPTIONS | SAVE_FLOWS | KEYWORD | keyword to indicate that cell-by-cell flow terms will be written to the file specified with ``BUDGET SAVE FILE'' in Output Control. |
+| SWF | STO | OPTIONS | EXPORT_ARRAY_ASCII | KEYWORD | keyword that specifies input grid arrays, which already support the layered keyword, should be written to layered ascii output files. |
 | SWF | STO | PERIOD | IPER | INTEGER | integer value specifying the starting stress period number for which the data specified in the PERIOD block apply.  IPER must be less than or equal to NPER in the TDIS Package and greater than zero.  The IPER value assigned to a stress period block must be greater than the IPER value assigned for the previous PERIOD block.  The information specified in the PERIOD block will continue to apply for all subsequent stress periods, unless the program encounters another PERIOD block. |
 | SWF | STO | PERIOD | STEADY-STATE | KEYWORD | keyword to indicate that stress period IPER is steady-state. Steady-state conditions will apply until the TRANSIENT keyword is specified in a subsequent BEGIN PERIOD block. |
 | SWF | STO | PERIOD | TRANSIENT | KEYWORD | keyword to indicate that stress period IPER is transient. Transient conditions will apply until the STEADY-STATE keyword is specified in a subsequent BEGIN PERIOD block. |

doc/mf6io/mf6ivar/tex/gwf-sto-desc.tex

@@ -13,7 +13,9 @@
 
 \item \texttt{FILEIN}---keyword to specify that an input filename is expected next.
 
-\item \texttt{tvs\_filename}---defines a time-varying storage (TVS) input file.  Records in the TVS file can be used to change specific storage and specific yield properties at specified times or stress periods.
+\item \texttt{tvs6\_filename}---defines a time-varying storage (TVS) input file.  Records in the TVS file can be used to change specific storage and specific yield properties at specified times or stress periods.
+
+\item \texttt{EXPORT\_ARRAY\_ASCII}---keyword that specifies input grid arrays, which already support the layered keyword, should be written to layered ascii output files.
 
 \end{description}
 \item \textbf{Block: GRIDDATA}

doc/mf6io/mf6ivar/tex/gwf-sto-options.dat

@@ -2,5 +2,6 @@ BEGIN OPTIONS
   [SAVE_FLOWS]
   [STORAGECOEFFICIENT]
   [SS_CONFINED_ONLY]
-  [TVS6 FILEIN <tvs_filename>]
+  [TVS6 FILEIN <tvs6_filename>]
+  [EXPORT_ARRAY_ASCII]
 END OPTIONS

doc/mf6io/mf6ivar/tex/prt-oc-desc.tex

@@ -23,7 +23,7 @@
 
 \item \texttt{TRACK\_RELEASE}---keyword to indicate that particle tracking output is to be written when a particle is released
 
-\item \texttt{TRACK\_EXIT}---keyword to indicate that particle tracking output is to be written when a particle exits a cell
+\item \texttt{TRACK\_EXIT}---keyword to indicate that particle tracking output is to be written when a particle exits a feature (a model, cell, or subcell)
 
 \item \texttt{TRACK\_TIMESTEP}---keyword to indicate that particle tracking output is to be written at the end of each time step
 

doc/mf6io/mf6ivar/tex/swf-sto-desc.tex

@@ -5,6 +5,8 @@
 \begin{description}
 \item \texttt{SAVE\_FLOWS}---keyword to indicate that cell-by-cell flow terms will be written to the file specified with ``BUDGET SAVE FILE'' in Output Control.
 
+\item \texttt{EXPORT\_ARRAY\_ASCII}---keyword that specifies input grid arrays, which already support the layered keyword, should be written to layered ascii output files.
+
 \end{description}
 \item \textbf{Block: PERIOD}
 

doc/mf6io/mf6ivar/tex/swf-sto-options.dat

@@ -1,3 +1,4 @@
 BEGIN OPTIONS
   [SAVE_FLOWS]
+  [EXPORT_ARRAY_ASCII]
 END OPTIONS

doc/mf6io/prt/prt.tex

@@ -16,7 +16,7 @@ \subsection{Time Stepping}
 
 \subsection{Specifying Cell Face Flows using IFLOWFACE}
 
-By default, flows associated with stress packages are assumed to be distributed uniformly over the volume of a cell. Distributed external inflows and outflows are reflected in the cell-cell flows calculated by the GWF Model, but they are not directly involved in determining the normal face velocities used to track a particle through the cell. The user can optionally assign a flow associated with a stress package to any face of the cell. Assignment of external flows is done by setting the value of an auxiliary package variable called IFLOWFACE to a value that corresponds to one of the cell faces. To accommodate non-rectangular cells, the face numbering scheme in the PRT Model is based on clockwise ordering of the cell faces. For a DIS-grid cell, face 1 is the ``western'' face, i.e., the face parallel to the y axis that has the lesser x coordinate. For a DISV-grid cell, face 1 is the face that extends in the clockwise direction from the first vertex listed for that cell in the CELL2D input block.
+By default, flows associated with stress packages are assumed to be distributed uniformly over the volume of a cell. Distributed external inflows and outflows are reflected in the cell-cell flows calculated by the GWF Model, but they are not directly involved in determining the normal face velocities used to track a particle through the cell. The user can optionally assign a flow associated with a stress package to any face of the cell. Assignment of external flows is done by setting the value of an auxiliary package variable called IFLOWFACE to a value that corresponds to one of the cell faces. To accommodate non-rectangular cells, the IFLOWFACE numbering scheme in the PRT Model is based on clockwise ordering of the lateral cell faces. For a DIS-grid cell, IFLOWFACE = 1 corresponds to the ``western'' face, i.e., the face parallel to the y axis that has the lesser x coordinate. For a DISV-grid cell, IFLOWFACE = 1 corresponds to the face that extends in the clockwise direction from the first vertex listed for that cell in the CELL2D input block. IFLOWFACE numbering of lateral cell faces proceeds in clockwise direction. IFLOWFACE = -2 corresponds to the cell bottom, and IFLOWFACE = -1 corresponds to the cell top.
 
 \subsection{Particle Mass Budget}
 A summary of all inflow (sources) and outflow (sinks) of particle mass is called a mass budget.  The particle mass budget is printed to the PRT Model Listing File for selected time steps.  In the current implementation, each particle is assigned unit mass, and the numerical value of the flow can be interpreted as particles per time.

src/Model/ParticleTracking/prt-fmi.f90

@@ -197,7 +197,8 @@ subroutine accumulate_flows(this)
         iflowface = 0
         if (iauxiflowface > 0) then
           iflowface = NINT(this%gwfpackages(ip)%auxvar(iauxiflowface, ib))
-          if (iflowface < 0) iflowface = iflowface + MAX_POLY_CELLS + 1 ! bot -> 9, top -> 10; see note re: max faces below
+          ! this maps bot -2 -> 9, top -1 -> 10; see note re: max faces below
+          if (iflowface < 0) iflowface = iflowface + MAX_POLY_CELLS + 1
         end if
         if (iflowface .gt. 0) then
           ioffset = (i - 1) * MAX_POLY_CELLS