docs(prt): describe particle track output, misc revisions (MODFLOW-US…

…GS#1818)

Add sections describing particle track binary and CSV output files

Co-authored-by: aprovost-usgs <[email protected]>

doc/mf6io/body.tex

@@ -52,7 +52,7 @@
 
 %PRT Model Input Instructions
 \newpage
-\SECTION{Particle Tracking (PRT) Model Input}
+\SECTION{Particle Tracking (PRT) Model Input and Output}
 \input{prt/prt.tex}
 
 %SWF Model Input Instructions

doc/mf6io/framework/binaryoutput.tex

@@ -653,6 +653,28 @@ \subsubsection{GWT Model LKT, MWT, SFT, and UZT Packages}
 For each stress period, time step, and data type that is saved to the LKT, MWT, SFT, and UZT Packages binary output files as \texttt{IMETH=6} budget file type. For all advanced transport packages, \texttt{NDIM1} is equal to the number of nodes, \texttt{NDIM2} is equal to 1, and \texttt{NDIM3} is equal to -1. The data that are written to the LKT, MWT, SFT, and UZT Package binary files are mass flows with entries similar to those listed in Tables~\ref{table:binarylak} to~\ref{table:binaryuzf} for the advanced flow packages.
 
 
+\newpage
+\subsubsection{Budget File Contents for the PRT Model}
+
+The type of information that is written to the budget file depends on whether or not the save flags are set.  Table \ref{table:prtbud} contains a list of the types of information that may be contained in a PRT Model budget file.  In all cases, the flows in table \ref{table:prtbud} are particle mass flows (in mass per time) to or from a PRT Model cell.  Intercell flows are written as FLOW-JA-FACE using IMETH=1.
+
+The remaining flow terms in table \ref{table:prtbud} are all written using IMETH=6.  When IMETH=6 is used, the records contain additional text descriptors and two identifying numbers.  For all records in the PRT Model budget file, TXT1ID1 is the name of the PRT Model and TXT2ID1 is also the name of the PRT Model.  These text identifiers describe what is contained in ID1.  For the PRT Model budget file, ID1 is the cell or node number in the PRT Model grid.  The second set of text identifiers refer to the information in ID2.  Unless noted otherwise in the description in table \ref{table:prtbud}, TXT1ID2 is the name of the PRT Model, TXT2ID2 is the name of the package, and ID2 is the bound number in the package.
+
+\begin{longtable}{p{3.5cm} p{2cm} p{9cm}}
+\caption{Types of information that may be contained in the PRT Model budget file.  All terms represent particle mass flows in dimensions of mass per time} 
+\tabularnewline
+\hline
+\textbf{Flow Type (TEXT)} & \textbf{Method Code (IMETH)} & \textbf{Description} \\
+\hline
+\endhead
+\hline
+\endfoot
+\texttt{FLOW-JA-FACE} & 1 & intercell particle mass flow; array of size (NJA) \\
+\texttt{PRP} & 6 & particle mass flow for particle releases \\
+\label{table:prtbud}
+\end{longtable}
+
+
 \newpage
 \subsection{Observation Output File}
 
@@ -681,3 +703,37 @@ \subsection{Observation Output File}
 \item \texttt{TIME} (floating-point) is the simulation time; and
 \item \texttt{SIMVALUE} (floating-point) is the simulated value.
 \end{description}
+
+
+\newpage
+\subsection{Particle Track File}
+
+The binary particle track file for the PRT Model contains particle track output data.  The file
+contains raw binary data and does not contain headers.  The information needed to parse the binary
+file is contained in a separate header file, which is a text file of the same name as the binary
+file, with the extra extension ``.hdr''.  The header file lists column headings that define the
+tabular data format to be used in parsing the binary data.
+
+Each record in the binary data file consists of the following fields, which are defined in the
+Particle Track Output subsection of the Particle Tracking (PRT) Model Input and Output section:
+
+\vspace{5mm}
+\noindent Field 0: \texttt{`KPER'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Field 1: \texttt{`KSTP'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Field 2: \texttt{`IMDL'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Field 3: \texttt{`IPRP'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Field 4: \texttt{`IRPT'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Field 5: \texttt{`ILAY'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Field 6: \texttt{`ICELL'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Field 7: \texttt{`IZONE'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Field 8: \texttt{`ISTATUS'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Field 9: \texttt{`IREASON'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Field 10: \texttt{`TRELEASE'} {\color{red} \footnotesize{DOUBLE}} \\
+\noindent Field 11: \texttt{`T'} {\color{red} \footnotesize{DOUBLE}} \\
+\noindent Field 12: \texttt{`X'} {\color{red} \footnotesize{DOUBLE}} \\
+\noindent Field 13: \texttt{`Y'} {\color{red} \footnotesize{DOUBLE}} \\
+\noindent Field 14: \texttt{`Z'} {\color{red} \footnotesize{DOUBLE}} \\
+\noindent Field 15: \texttt{`NAME'} {\color{red} \footnotesize{CHARACTER(LEN=LENTXT)}} \\
+
+\vspace{4mm}
+\noindent The ``NAME'' field may be empty.

doc/mf6io/mf6output.tex

@@ -5,7 +5,7 @@
                   VERSION 6.5.0.dev2 (preliminary) 02/13/2024
                                ***DEVELOP MODE***
 
-        MODFLOW 6 compiled May 16 2024 17:04:31 with GCC version 11.4.0
+        MODFLOW 6 compiled May 17 2024 07:54:54 with GCC version 11.4.0
 
 This software is preliminary or provisional and is subject to 
 revision. It is being provided to meet the need for timely best 
@@ -21,15 +21,15 @@
 
  MODFLOW runs in SEQUENTIAL mode
 
- Run start date and time (yyyy/mm/dd hh:mm:ss): 2024/05/16 18:30:39
+ Run start date and time (yyyy/mm/dd hh:mm:ss): 2024/05/17 10:08:23
 
  Writing simulation list file: mfsim.lst
  Using Simulation name file: mfsim.nam
 
     Solving:  Stress period:     1    Time step:     1
 
- Run end date and time (yyyy/mm/dd hh:mm:ss): 2024/05/16 18:30:39
- Elapsed run time:  0.021 Seconds
+ Run end date and time (yyyy/mm/dd hh:mm:ss): 2024/05/17 10:08:23
+ Elapsed run time:  0.013 Seconds
 
  Normal termination of simulation.
 \end{lstlisting}

doc/mf6io/mf6switches.tex

@@ -1,6 +1,6 @@
 {\small
 \begin{lstlisting}[style=modeloutput]
-mf6 - MODFLOW 6.5.0.dev2 (preliminary) 02/13/2024 (compiled May 16 2024 17:04:31)
+mf6 - MODFLOW 6.5.0.dev2 (preliminary) 02/13/2024 (compiled May 17 2024 07:54:54)
 usage: mf6               run MODFLOW 6 using "mfsim.nam"
    or: mf6 [options]     retrieve program information
 

doc/mf6io/prt/prt.tex

@@ -11,12 +11,85 @@
 \subsection{Units of Length and Time}
 The PRT Model formulates the particle trajectory equations without using prescribed length and time units. Any consistent units of length and time can be used when specifying the input data for a simulation. This capability gives a certain amount of freedom to the user, but care must be exercised to avoid mixing units.  The program cannot detect the use of inconsistent units.
 
-\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.
-
 \subsection{Time Stepping}
 In \mf time step lengths are controlled by the user and specified in the Temporal Discretization (TDIS) input file.  When the flow model and particle-tracking model run in the same simulation, the time step length specified in TDIS is used for both models.  If the PRT Model runs in a separate simulation, the time discretization may differ.  Instructions for specifying time steps are described in the TDIS section of this user guide; additional information on GWF and PRT configurations are in the Flow Model Interface section.  
 
+\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.
+
+\subsection{Particle Track Output}
+
+The PRT Model supports both binary and CSV particle track output files. A particle track CSV file contains the output data in tabular format. The first line of the CSV file contains column names. Each subsequent line in the file contains a row of data for a single particle track record, with the following fields:
+
+\vspace{5mm}
+\noindent Column 0: \texttt{`KPER'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Column 1: \texttt{`KSTP'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Column 2: \texttt{`IMDL'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Column 3: \texttt{`IPRP'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Column 4: \texttt{`IRPT'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Column 5: \texttt{`ILAY'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Column 6: \texttt{`ICELL'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Column 7: \texttt{`IZONE'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Column 8: \texttt{`ISTATUS'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Column 9: \texttt{`IREASON'} {\color{red} \footnotesize{INTEGER}} \\
+\noindent Column 10: \texttt{`TRELEASE'} {\color{red} \footnotesize{DOUBLE}} \\
+\noindent Column 11: \texttt{`T'} {\color{red} \footnotesize{DOUBLE}} \\
+\noindent Column 12: \texttt{`X'} {\color{red} \footnotesize{DOUBLE}} \\
+\noindent Column 13: \texttt{`Y'} {\color{red} \footnotesize{DOUBLE}} \\
+\noindent Column 14: \texttt{`Z'} {\color{red} \footnotesize{DOUBLE}} \\
+\noindent Column 15: \texttt{`NAME'} {\color{red} \footnotesize{CHARACTER(LEN=LENTXT)}} \\
+
+\vspace{2mm}
+\noindent where
+
+\begin{description} \itemsep0pt \parskip0pt \parsep0pt
+\item \texttt{KPER} is the stress period number
+\item \texttt{KSTP} is the time step number
+\item \texttt{IMDL} is the number of the model the particle originated in
+\item \texttt{IPRP} is the number of the particle release point (PRP) package the particle originated in
+\item \texttt{IRPT} is the release point number
+\item \texttt{ILAY} is the layer number
+\item \texttt{ICELL} is the cell number
+\item \texttt{IZONE} is the zone number
+\item \texttt{ISTATUS} is the particle status code
+\item \texttt{IREASON} is the reporting reason code
+\item \texttt{TRELEASE} is the particle release time
+\item \texttt{T} is the particle tracking time
+\item \texttt{X} is the particle x coordinate
+\item \texttt{Y} is the particle y coordinate
+\item \texttt{Z} is the particle z coordinate
+\item \texttt{NAME} is the name of the particle release point
+\end{description}
+
+The ISTATUS field indicates the status of the particle:
+
+\begin{description} \itemsep0pt \parskip0pt \parsep0pt
+\item \texttt{0}: particle was released
+\item \texttt{1}: particle is being actively tracked
+\item \texttt{2}: particle terminated at a boundary face
+\item \texttt{3}: particle terminated in a weak sink cell
+\item \texttt{4}: \textit{unused}
+\item \texttt{5}: particle terminated in a cell with no exit face
+\item \texttt{6}: particle terminated in a stop zone
+\item \texttt{7}: particle terminated in an inactive cell
+\item \texttt{8}: particle terminated immediately upon release into a dry cell
+\item \texttt{9}: particle terminated in a subcell with no exit face
+\end{description}
+
+The IREASON field indicates the reason the particle track record was saved:
+
+\begin{description} \itemsep0pt \parskip0pt \parsep0pt
+\item \texttt{0}: particle was released
+\item \texttt{1}: particle exited a cell
+\item \texttt{2}: time step ended
+\item \texttt{3}: particle terminated
+\item \texttt{4}: particle exited a weak sink cell
+\item \texttt{5}: user-specified tracking time
+\end{description}
+
+By default, the PRT Model reports all particle events. The user can optionally select which events are reported, as explained in the Output Control (OC) subsection. Because multiple tracking events may coincide (e.g. exiting a cell and exiting a weak sink cell), particle track records may be duplicates except for the ISTATUS and/or IREASON codes.
+
+The binary particle track file contains the same particle track data in a record-based binary format explained in the Particle Track File subsection of the Description of Binary Output Files section.
 
 
 \newpage