docs(netcdf): update mf6io extended (#2094)

* baseline content for netcdf in mf6io

* fix spelling

* consolidate extended sections at end of document

* reformat mf6ivar.py

* update readasarrays for netcdf

* fix spelling

* restore prt dis and disv dfns

* adjustments to export_netcdf tag

* minor cleanup

* fix quoting in extended_modflow.tex

doc/mf6io/body.tex

@@ -9,10 +9,6 @@
 \SECTION{Running a Simulation}
 \input{running_simulation.tex}
 
-%Instructions for running a simulation
-\SECTION{Extended MODFLOW}
-\input{extended_modflow.tex}
-
 %General form of input instructions
 \SECTION{Form of Input Instructions}
 \input{framework/form_of_input.tex}
@@ -39,11 +35,6 @@
 \SECTION{Adaptive Time Step (ATS) Utility}
 \input{utl_ats.tex}
 
-%HPC configuration file
-\newpage
-\SECTION{High Performance Computing (HPC) Utility -- \textcolor{red}{Extended MODFLOW only}}
-\input{utl_hpc.tex}
-
 %GWF Model Input Instructions
 \newpage
 \SECTION{Groundwater Flow (GWF) Model Input}
@@ -109,6 +100,11 @@
 \SECTION{Description of Binary Output Files}
 \input{framework/binaryoutput}
 
+%Instructions for running a simulation
+\newpage
+\SECTION{Extended MODFLOW}
+\input{extended_modflow.tex}
+
 \newpage
 \ifx\usgsdirector\undefined
 \addcontentsline{toc}{section}{\hspace{1.5em}\bibname}

doc/mf6io/extended_modflow.tex

@@ -1,3 +1,35 @@
 Next to the standard \mf executable, a second, extended version of the program is made available. This version comes with more advanced functionality for which it partially relies on third-party libraries. Currently this concerns the parallel computing capability and the use of NetCDF4 for I/O data. Because the external dependencies increase the complexity of the installation procedure, \mf will remain available in its core set of functionality.
 
-Extended \mf contains all features available in the standard edition, runs on the same input configuration, and produces the same results. Reversely, when running with the standard executable, some features described in this document (HPC Utility, NetCDF4 I/O) will not be available and their configuration will be ignored or an error is reported. These features will be labeled accordingly below.
+Extended \mf contains all features available in the standard edition, runs on the same input configuration, and produces the same results. Reversely, when running with the standard executable, some features described in this document (HPC Utility, NetCDF4 I/O) will not be available and their configuration will be ignored or an error is reported. These features will be labeled accordingly below.
+
+\subsection{NetCDF Export Files}
+
+The extended build of \mf can optionally create model NetCDF export files.  \mf supports two types of NetCDF exports, referred to here as ``structured'' and ``mesh''.
+
+\mf NetCDF exports by default contain model dependent variable timeseries data, e.g. head.  In addition, \mf package griddata input arrays can be configured to be written to the export file.  Creating export files containing only one or the other of these these types of data form two distinct uses for the exports.  Generating exports of these two types will described below.
+
+These capabilities are dependent on the earlier described Input Data Processor (IDP).  In particular, the package array export capability described below is limited to packages currently supported by IDP.
+
+\subsubsection{Mesh Exports}
+\mf mesh exports comply with UGRID 1.0 conventions and are based on the UGRID 3D layered mesh topology.  A UGRID based NetCDF file explicitly describes the grid with a set of variables that gridded data can be associated with.  \mf mesh exports can be generated with a DIS or DISV based GWF, GWT, or GWE model.
+
+\subsubsection{Structured Exports}
+\mf structured NetCDF exports define x and y geometric coordinate variables and are not based on the UGRID specification.  \mf structured exports can be generated with a DIS based GWF, GWT, or GWE model.
+
+\subsubsection{Dependent variable exports}
+A typical use case creates an export that capture timeseries output for the model dependent variable.  This export can be optioned simply by adding the ``EXPORT\_NETCDF'' keyword to a GWF, GWT, or GWE model name file.  This keyword takes an argument for the NetCDF export type, either ``STRUCTURED'' or ``MESH'' (or alternatively, ``UGRID'').  Configured in this way, the export will contain only the mesh or x and y coordinate variables and the dependent variable(s).  Additional configuration options are possible when a NetCDF configuration package (UTL-NCF) is created, such as per-variable compression, chunking options, and options meant to support visualization in post-processing tools like QGIS.  This package is described below.
+
+\subsubsection{Exporting array input}
+Packages that support exporting griddata input arrays to model NetCDF files support the ``EXPORT\_ARRAY\_NETCDF'' keyword.  Using this keyword, when model NetCDF export also is active, has the effect of writing all package griddata arrays to the NetCDF export.  Writing candidate arrays to a NetCDF file offers an alternative to storing them in an ascii or binary input file.
+
+One approach to converting existing ascii or binary inputs to NetCDF inputs is described next.  \mf supports a validate mode option intended to support error checking.  In this mode no matrix equations are assembled or solved and no solution based outputs are created.  Input, however, is still read in validate mode and thus can be written to NetCDF exports when configured. Specific IDP supported packages can be configured to export griddata array input by using the ``EXPORT\_ARRAY\_NETCDF'' package option when running the simulation in validate mode.  When configured in this way, \mf will generate a NetCDF export file, absent a dependent or time coordinate variable, that can serve as a separate input file for model gridded package data.
+
+\subsection{NetCDF as simulation input}
+\mf can read NetCDF files as model inputs containing package griddata array input. Files generated using the validate method described in the previous section are suitable as inputs- note that \mf expects specific annotations for NetCDF input variables and that these are written by default into \mf NetCDF exports. An example follows showing a model name file that configures a NetCDF input and IC and NPF input files that specify specific griddata parameters should be read from the model NetCDF input:
+\input{netcdf_input.tex}
+
+\subsection{High Performance Computing (HPC) Utility}
+\input{utl_hpc.tex}
+
+\subsection{NetCDF configuration (NCF) Utility}
+\input{utl_ncf.tex}

doc/mf6io/framework/array_data.tex

@@ -102,6 +102,8 @@ \subsubsection{READARRAY Examples}
 
 Here, the initial heads for the model are provided in the \texttt{strt} array.  If the optional LAYERED keyword is present, then a separate array is provided for each layer.  If the LAYERED keyword is not present, then the entire starting head array is read at once.  The LAYERED keyword may be useful to discretization packages of type DIS and DISV, which support the concept of layers.  Models defined with the DISU Package are not layered.
 
+Note that the \mf Extended build also supports an optional NETCDF keyword.  This keyword is not compatible with the LAYERED keyword and is a valid option only if a model NetCDF input file is configured.  This type of workflow is covered in the section which describes Extended \mf.
+
 For a structured DIS model, the READARRAY utility is used to read arrays that are dimensioned to the full size of the grid (of size \texttt{nlay*nrow*ncol}). This utility first reads an array name, which associates the input to be read with the desired array.  For these arrays, an optional keyword ``LAYERED'' can be located next to the array name.  If ``LAYERED'' is detected, then a control line is provided for each layer and the array is filled with values for each model layer.  If the ``LAYERED'' keyword is absent, then a single control line is used and the entire array is filled at once.
 
 For example, the following block shows one way the \mf GWF model starting head array (STRT) could be specified for a model with 4 layers.  Following the array name and the ``LAYERED'' keyword are four control lines, one for each layer.

doc/mf6io/framework/form_of_input.tex

@@ -24,6 +24,8 @@ \subsection{Block and Keyword Input}
 \end{lstlisting}
 This example shows the items that may be specified with this OPTIONS block.  Optional items are enclosed between ``['' and ``]'' symbols.  The ``\texttt{<}'' and ``\texttt{>}'' symbols indicate a variable that must be provided by the user.  In this case, \texttt{auxiliary} is an array of size \texttt{naux}.  Because there are bracket symbols around the entire item, the user it not required to specify anything for this item.  Likewise, the user may or may not invoke the ``\texttt{PRINT\_INPUT}'' option.  Lastly, the user can specify ``\texttt{MAXIMUM\_ITERATION}'' followed by a numeric value for ``\texttt{maxsfrit}''.  If the user does not specify an optional item, then a default condition will apply.  Behavior of the default condition is described in the input instructions for that item.
 
+Note that text color in the input instructions is indicative of special features or behaviors associated with the variables printed in that color.  Specifically, the text color of blue is reserved to indicate a variable that may be represented with a time series.  The text color of red is reserved for keywords or variables that are supported only in the extended build of \mf.  The extended build is covered in its own section in this document.
+
 \vspace{6pt}\noindent A valid user input block for OPTIONS might be:
 
 \begin{lstlisting}[style=inputfile]

doc/mf6io/mf6io.nightlybuild.tex

@@ -45,6 +45,7 @@
 }
 \lstdefinestyle{blockdefinition}{
   moredelim=**[is][\color{blue}]{@}{@},
+  moredelim=**[is][\color{red}]{\$}{\$},
 }
 %usage: \lstinputlisting[style=blockdefinition]{./mf6ivar/tex/gwf-chd-dimensions.dat}
 \lstdefinestyle{inputfile}{

doc/mf6io/mf6io.tex

@@ -37,6 +37,7 @@
 }
 \lstdefinestyle{blockdefinition}{
   moredelim=**[is][\color{blue}]{@}{@},
+  moredelim=**[is][\color{red}]{\$}{\$},
 }
 %usage: \lstinputlisting[style=blockdefinition]{./mf6ivar/tex/gwf-chd-dimensions.dat}
 \lstdefinestyle{inputfile}{

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

@@ -35,6 +35,7 @@ optional true
 mf6internal export_nc
 longname export array variables to netcdf output files.
 description keyword that specifies input griddata arrays should be written to the model output netcdf file.
+extended true
 
 # --------------------- gwe cnd griddata ---------------------
 
@@ -44,6 +45,7 @@ type double precision
 shape (nodes)
 reader readarray
 layered true
+netcdf true
 optional true
 longname longitudinal dispersivity in horizontal direction
 description longitudinal dispersivity in horizontal direction.  If flow is strictly horizontal, then this is the longitudinal dispersivity that will be used.  If flow is not strictly horizontal or strictly vertical, then the longitudinal dispersivity is a function of both ALH and ALV.  If mechanical dispersion is represented (by specifying any dispersivity values) then this array is required.
@@ -54,6 +56,7 @@ type double precision
 shape (nodes)
 reader readarray
 layered true
+netcdf true
 optional true
 longname longitudinal dispersivity in vertical direction
 description longitudinal dispersivity in vertical direction.  If flow is strictly vertical, then this is the longitudinal dispsersivity value that will be used.  If flow is not strictly horizontal or strictly vertical, then the longitudinal dispersivity is a function of both ALH and ALV.  If this value is not specified and mechanical dispersion is represented, then this array is set equal to ALH.
@@ -64,6 +67,7 @@ type double precision
 shape (nodes)
 reader readarray
 layered true
+netcdf true
 optional true
 longname transverse dispersivity in horizontal direction
 description transverse dispersivity in horizontal direction.  This is the transverse dispersivity value for the second ellipsoid axis.  If flow is strictly horizontal and directed in the x direction (along a row for a regular grid), then this value controls spreading in the y direction.  If mechanical dispersion is represented (by specifying any dispersivity values) then this array is required.
@@ -74,6 +78,7 @@ type double precision
 shape (nodes)
 reader readarray
 layered true
+netcdf true
 optional true
 longname transverse dispersivity in horizontal direction
 description transverse dispersivity in horizontal direction.  This is the transverse dispersivity value for the third ellipsoid axis.  If flow is strictly horizontal and directed in the x direction (along a row for a regular grid), then this value controls spreading in the z direction.  If this value is not specified and mechanical dispersion is represented, then this array is set equal to ATH1.
@@ -84,6 +89,7 @@ type double precision
 shape (nodes)
 reader readarray
 layered true
+netcdf true
 optional true
 longname transverse dispersivity when flow is in vertical direction
 description transverse dispersivity when flow is in vertical direction.  If flow is strictly vertical and directed in the z direction, then this value controls spreading in the x and y directions.  If this value is not specified and mechanical dispersion is represented, then this array is set equal to ATH2.
@@ -94,6 +100,7 @@ type double precision
 shape (nodes)
 reader readarray
 layered true
+netcdf true
 optional true
 longname thermal conductivity of the simulated fluid
 description thermal conductivity of the simulated fluid.   Note that the CND Package does not account for the tortuosity of the flow paths when solving for the conductive spread of heat.  If tortuosity plays an important role in the thermal conductivity calculation, its effect should be reflected in the value specified for KTW.
@@ -104,6 +111,7 @@ type double precision
 shape (nodes)
 reader readarray
 layered true
+netcdf true
 optional true
 longname thermal conductivity of the aquifer material
 description thermal conductivity of the aquifer material

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

@@ -58,6 +58,7 @@ optional true
 mf6internal export_nc
 longname export array variables to netcdf output files.
 description keyword that specifies input griddata arrays should be written to the model output netcdf file.
+extended true
 
 block options
 name ncf_filerecord
@@ -77,6 +78,7 @@ tagged true
 optional false
 longname ncf keyword
 description keyword to specify that record corresponds to a netcdf configuration (NCF) file.
+extended true
 
 block options
 name filein
@@ -98,6 +100,7 @@ optional false
 tagged false
 longname file name of NCF information
 description defines a netcdf configuration (NCF) input file.
+extended true
 
 # --------------------- gwe dis dimensions ---------------------
 
@@ -135,6 +138,7 @@ name delr
 type double precision
 shape (ncol)
 reader readarray
+netcdf true
 longname spacing along a row
 description is the column spacing in the row direction.
 default_value 1.0
@@ -144,6 +148,7 @@ name delc
 type double precision
 shape (nrow)
 reader readarray
+netcdf true
 longname spacing along a column
 description is the row spacing in the column direction.
 default_value 1.0
@@ -153,6 +158,7 @@ name top
 type double precision
 shape (ncol, nrow)
 reader readarray
+netcdf true
 longname cell top elevation
 description is the top elevation for each cell in the top model layer.
 default_value 1.0
@@ -163,6 +169,7 @@ type double precision
 shape (ncol, nrow, nlay)
 reader readarray
 layered true
+netcdf true
 longname cell bottom elevation
 description is the bottom elevation for each cell.
 default_value 0.
@@ -173,6 +180,7 @@ type integer
 shape (ncol, nrow, nlay)
 reader readarray
 layered true
+netcdf true
 optional true
 longname idomain existence array
 description is an optional array that characterizes the existence status of a cell.  If the IDOMAIN array is not specified, then all model cells exist within the solution.  If the IDOMAIN value for a cell is 0, the cell does not exist in the simulation.  Input and output values will be read and written for the cell, but internal to the program, the cell is excluded from the solution.  If the IDOMAIN value for a cell is 1, the cell exists in the simulation.  If the IDOMAIN value for a cell is -1, the cell does not exist in the simulation.  Furthermore, the first existing cell above will be connected to the first existing cell below.  This type of cell is referred to as a ``vertical pass through'' cell.

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

@@ -58,6 +58,7 @@ optional true
 mf6internal export_nc
 longname export array variables to netcdf output files.
 description keyword that specifies input griddata arrays should be written to the model output netcdf file.
+extended true
 
 block options
 name ncf_filerecord
@@ -77,6 +78,7 @@ tagged true
 optional false
 longname ncf keyword
 description keyword to specify that record corresponds to a netcdf configuration (NCF) file.
+extended true
 
 block options
 name filein
@@ -98,6 +100,7 @@ optional false
 tagged false
 longname file name of NCF information
 description defines a netcdf configuration (NCF) input file.
+extended true
 
 # --------------------- gwe disv dimensions ---------------------
 
@@ -132,6 +135,7 @@ name top
 type double precision
 shape (ncpl)
 reader readarray
+netcdf true
 longname model top elevation
 description is the top elevation for each cell in the top model layer.
 
@@ -141,6 +145,7 @@ type double precision
 shape (ncpl, nlay)
 reader readarray
 layered true
+netcdf true
 longname model bottom elevation
 description is the bottom elevation for each cell.
 
@@ -150,6 +155,7 @@ type integer
 shape (ncpl, nlay)
 reader readarray
 layered true
+netcdf true
 optional true
 longname idomain existence array
 description is an optional array that characterizes the existence status of a cell.  If the IDOMAIN array is not specified, then all model cells exist within the solution.  If the IDOMAIN value for a cell is 0, the cell does not exist in the simulation.  Input and output values will be read and written for the cell, but internal to the program, the cell is excluded from the solution.  If the IDOMAIN value for a cell is 1, the cell exists in the simulation.  If the IDOMAIN value for a cell is -1, the cell does not exist in the simulation.  Furthermore, the first existing cell above will be connected to the first existing cell below.  This type of cell is referred to as a ``vertical pass through'' cell.

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

@@ -17,6 +17,7 @@ optional true
 mf6internal export_nc
 longname export array variables to netcdf output files.
 description keyword that specifies input griddata arrays should be written to the model output netcdf file.
+extended true
 
 # --------------------- gwe ic griddata ---------------------
 
@@ -26,6 +27,7 @@ type double precision
 shape (nodes)
 reader readarray
 layered true
+netcdf true
 longname starting temperature
 description is the initial (starting) temperature---that is, the temperature at the beginning of the GWE Model simulation.  STRT must be specified for all GWE Model simulations. One value is read for every model cell.
 default_value 0.0

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

@@ -40,7 +40,8 @@ reader urword
 optional true
 mf6internal export_netcdf
 longname export model output netcdf file.
-description keyword that specifies timeseries data for the dependent variable should be written to a model output netcdf file.  No value or ``UGRID'' (ugrid based export) values are supported.
+description keyword that specifies timeseries data for the dependent variable should be written to a model output netcdf file.  ``STRUCTURED'' or ``MESH'' (ugrid based export) values are supported.
+extended true
 
 block options
 name nc_filerecord
@@ -49,7 +50,7 @@ reader urword
 tagged true
 optional true
 longname
-description netcdf config filerecord
+description netcdf filerecord
 
 block options
 name netcdf
@@ -60,6 +61,7 @@ tagged true
 optional false
 longname netcdf keyword
 description keyword to specify that record corresponds to a netcdf input file.
+extended true
 
 block options
 name filein
@@ -82,6 +84,7 @@ tagged false
 longname netcdf input filename
 description defines a netcdf input file.
 mf6internal netcdf_fname
+extended true
 
 # --------------------- gwe nam packages ---------------------