MODEL ARCHIVE
Created July 31, 2017.

# Reference to the model documentation report with doi.
Nadler, C.A., Allander, K.K., Pohll, G.M., Morway, E.D., Naranjo, R.C., Huntington, J.L., 2017, Evaluation of Bias Associated with Capture Maps Derived from Nonlinear Groundwater Flow Models, Groundwater xxx, xx p, http://dx.doi.org/10.1111/gwat.12597

# Reference to the model data release with doi.
Nadler, C.A., Allander, K.K., Pohll, G.M., Morway, E.D., Naranjo, R.C., Huntington, J.L., 2017, Hypothetical Stream-Aquifer System to Assess Capture Map Bias: U.S. Geological Survey data release, https://doi.org/10.5066/F7639NN9.

A MODFLOW model of a hypothetical stream-aquifer system is presented for the evaluation and characterization of capture map bias.  The hypothetical model is a 
single-layer model constructed with 30 rows and 100 columns.  The MODFLOW model includes a stream (represented with the MODFLOW SFR or CHD Packages), mountain block
recharge (represented with the MODFLOW RCH Package), and evapotransipration (represented with the MODFLOW EVT Package).

The hypothetical model is used to create capture maps and capture difference maps.  Map regions with large capture and depletion fraction differences are evaluated
with new methods to compute capture map bias.  The hypothetical stream-aquifer system model is used for sensitivity analyses to characterize capture map bias.

The underlying directories contain model input and out files, a batch file, Excel workbooks, and supporting utilities used for the simulations described in the 
journal article.  Descriptions of the data in each subdirectory are given to facilitate understanding of this data release.  File descriptions are provided for select 
files to provide additional information that may be of use for understanding this data release.
      
The model simulations were run with MODFLOW-NWT version 1.0.9.

Support is provided for correcting errors in the data release and clarification of the modeling conducted by the U.S. Geological Survey. Users are encouraged to 
review the model documentation report (http://dx.doi.org/10.1111/gwat.12597) to understand the purpose, construction, and limitations of this model.

Reconstructing the data release from the online data release :
-------------------------------------------------------------
        This data release is available from:
        
         https://doi.org/10.5066/F7639NN9
        
The model will run successfully only if the original directory structure is correctly restored. The data release is divided into several pieces to reduce the 
likelihood of download timeouts. Small files (readme.txt and modelgeoref.txt) are available as uncompressed files. All other files are zipped at the subdirectory 
level. For example, the files in the "georef" subdirectory are zipped into a zip file named "georef.zip". All zip files should be unzipped into a directory with 
the same name as the zip file name without the .zip extension. 

The highest-level directory structure of the original data release is:
        
            CMB/
                ancillary/
                bin/
                georef/
                model/
                output/
                source/
                
The full directory structure of the data release and the zip files associated with each subdirectory are listed below. 

The model was run on a Windows 10 64-bit operating system. Windows is a requirement for performing actions outside of running the model and viewing model results.
Microsoft Excel workbooks were used to post-process model results for generating report figures and tables.
         
Running the model:
The groundwater-flow model can be run from a batch file. In the model directory, the batch file RunModflow.bat 
does the following task:
1. Runs the hypothetical stream-aquifer system model.
2. Generates model output files in the CMB\model\output directory.  Files in the CMB\model\output directory can be compared
   with models in the CMB\output directory.

readme.txt
This ASCII text file describes the organization of the model archive structure, batch file, MODFLOW input and output files, and Microsoft Excel workbooks
used for post-processing model results.

modelgeoref.txt
This ASCII text file defines the four corners of the location of the Nevada Water Science Center, where the hypothetical stream-aquifer system model
was created.  Coordinates are given in decimal degrees.

ancillary directory:
This directory contains model input data and post-processing utilities related to capture maps, capture difference maps, and capture map bias.
The ancillary directory contains 8 subdirectories and 1 file:

1. Figure1:   contains model output files and a ModelMuse text file to generate the included Figure_1.png
2. Figure2:   contains model post-processing utilities for creating capture maps for the hypothetical stream-aquifer system model
3. Figures3:  contains post-processing utilities to evaluate the relationship between capture fracitons and the pumping rate used to calculate the capture fraction
4. Figure4:   contains model post-processing utilities for creating capture difference maps for the hypothetical stream-aquifer system model
5. Figure5:   contains post-processing utilities to evaluate capture and depletion bias through time
6. Figure6:   contains post-processing utilities to calculate capture map bias sensitivity to select model parameters and conceptualization
7. Table1:    contains a list of model paramters used in the model input files
8. Table2:    contains post-processing utilities to conduct sensitivity analyses on capture map bias
9. readme.txt:  contains the figures and tables generated from model output, files used in their creation, and a note on post-processing with Python scripts

The Figure1 directory contains 5 files:
1. CMB_hypothetical_model.cbc: MODFLOW output cell-by-cell file with spatiotemporal ETg data for Figure 1.
2. CMB_hypothetical_model.fdn: MODFLOW output file with spatiotemporal drawdown data used for Figure 1.
3. CMB_hypothetical_model.gpt: ModelMuse Text File used to create Figure 1.
4. Figure_1.png: PNG File of ETg distribution in steady-state and after 200 years of pumping, as well as contoured drawdown after 200 years of pumping.
5. readme.txt: Instruction file to create Figure 1.

The Figure2 directory contains 3 subdirectories and 2 files:
1. Associated_Files: Text files used to define active cells and the location of the stream for the provided Python script.
2. Capture_and_Depletion_Maps_and_Data_T30: Text files of data arrays used for capture maps and associated capture maps (PNG files), as well as an Excel workbook that generates the provided capture maps.
3. Python_Script: Python script and configuration file used to generate capture maps.
4. Figure_2.png: PNG File of capture maps for the hypothetical model.
5. readme.txt: Instruction file to create Figure 2.

The Figure3 directory contains 4 files:
1. CMB_well_location_for_figure_3.txt: Text file with the row and column location of the well used to characterize the relationship between capture fraction and pumping rate.
2. Figure_3.pdf: PDF of capture and depletion fractions vs. pumping rates used to calculate the fractions for a well in the location given in CMB_well_location_for_figure_3.txt after 30 years of pumping.
3. Figure3.xlsx: Excel workbook with capture and depletion fractions derived from different pumping rates (Data sheet) and the plotted data (Figure3 sheet).
4. readme.txt: Instruction file to create Figure 3.

The Figure4 directory contains 3 subdirectories and 2 files:
1. Associated_Files: Text files used to define active cells and the location of the stream for the provided Python script.
2. Capture_and_Depletion_Difference_Maps_and_Data_T30: Text files of data arrays used for capture difference maps and associated capture difference maps (PNG files), as well as an Excel workbook that generates the provided capture difference maps.
3. Python_Script: Python script and configuration file used to generate capture difference maps.
4. Figure_2.png: PNG File of capture difference maps for the hypothetical model.
5. readme.txt: Instruction file to create Figure 4.

The Figure5 directory contains 2 subdirectories and 5 files:
1. Python_Scripts: Python scripts and configuration file used to generate capture data used to computer capture map bias as well as an instruction file and an example batch file to run the scripts.
2. Well_Locations: Text files with row and column locations of wells used to evaluate the relationship between capture difference maps and capture map bias.
3. CMB_high_fraction_difference_bias.txt: Text file of capture and depletion bias through time for wells placed in the region of high capture fraction differences.
4. CMB_low_fraction_difference_bias.txt:  Text file of capture and depletion bias through time for wells placed in the region of low capture fraction differences.
5. Figure_5.pdf: PDF of capture map bias for wells placed in a region of high capture fraction difference (solid lines) and wells placed in a region of low capture fraction difference (dashed lines).
6. Figure5.xlsx: Excel workbook with data from CMB_high_fraction_difference_bias.txt and CMB_low_fraction_difference_bias.txt as well as a plot of the data (Figure 5).
7. readme.txt: Instruction file to create Figure 5.

The Figure6 directory contains 3 files:
1. Figure_6.pdf: A PDF of capture bias sensitivity to selected model parameters and model design.
2. Figure6.xlsx: An Excel workbook with a copy of Table 2 (includes capture and depletion bias values for selected parameters and model design), calculations of maximum differences in bias per model parameter/design component, and the generation of Figure 6.
3. readme.txt: Instruction file to create Figure 6.

The Table1 directory contains 1 subdirectory and 2 files:
1. Model_Files: Includes model input files in which model input parameters can be found.
2. readme.txt: Information file about Table 1.
3. Table1.xlsx: Excel workbook with model parameters and associated input files found in Table 1 in the journal article.

The Table2 directory contains 3 subdirectories and 2 files:
1. Additional_Model_Info_Files: Model input files used to change model design and parameterization for select components of the capture map bias sensitivity analyses.
2. Associated_Bias_Files: Text files with capture map bias through time resulting from variations of the model of the hypothetical stream-aquifer system.
3. Python_Scripts: Python scripts and configuration file used to generate capture data used to computer capture map bias as well as an instruction file and an example batch file to run the scripts.
4. readme.txt: Instruction file to create Table 2.
5. Table2.xlsx: Table of model parameter or component of model design that was changed for the bias sensitivity analyses as well as the resulting maximum capture and depletion biases.  This table also lists the associated text files with bias data and model input files used in the particular model run.
     
bin directory: 
This directory contains the compiled executables for MODFLOW-NWT and ModelMuse and an informational text file (readme.txt)
  MODFLOW EXECUTABLE
    MODFLOW-NWT.exe      - USGS MODFLOW-NWT executable
  MODELMUSE EXECUTABLE
    ModelMuse.exe        - USGS ModelMuse executable

georef directory:
This directory contains a polygon shapefile of the Nevada Water Science Center where the hypothetical stream-aquifer system model was developed.

model directory:
This directory contains 1 subdirectory and 1 file:

CMB_hypothetical:    contains model input files and a batch file to run the forward MODFLOW model
readme.txt:          contains an explanation of the CMB_hypothetical subdirectory 

The CMB_hypothetical directory contains 11 groundwater-flow model input files:
1.  CMB_hypothetical_model.bas: MODFLOW Basic Package
2.  CMB_hypothetical_model.dis: MODFLOW Discretization Package
3.  CMB_hypothetical_model.evt: MODFLOW Evapotranspiration Package
4.  CMB_hypothetical_model.gsf: MODFLOW Grid Specification File
5.  CMB_hypothetical_model.nam: MODFLOW Name File
6.  CMB_hypothetical_model.nwt: MODFLOW Newton Solver
7.  CMB_hypothetical_model.oc:  MODFLOW Output Control File
8.  CMB_hypothetical_model.rch: MODFLOW Recharge Package
9.  CMB_hypothetical_model.sfr: MODFLOW Streamflow-Routing Package
10. CMB_hypothetical_model.upw: MODFLOW Upstream Weighting Package
11. CMB_hypothetical_model.wel: MODFLOW Well Package

The CMB_hypothetical directory also includes a batch file to run the model and generate a new model\output directory with model output files.  
A readme.txt file is provided with instructions to run the model. 
A USGS reference file is provided.

output directory:
This directory contains 1 subdirectory and 1 file:

output.CMB_hypthetical:    contains model output files
readme.txt:                contains an explanation of the output.CMB_hypothetical directory

The output.CMB_hypothetical directory contains model output results and an informational file (readme.txt). Model output results include:
1. CMB_hypothetical_model.cbc: MODFLOW cell-by-cell flow file
2. CMB_hypothetical_model.fdn: MODFLOW drawdown file
3. CMB_hypothetical_model.fhd: MODFLOW head file
4. CMB_hypothetical_model.lst: MODFLOW list file
5. CMB_hypothetical_model.wel_dewater: MODFLOW well dewater file

source directory:
This directory contains the source code that was developed as part of the project to run the model and view model results in ModelMuse. 
  MODFLOW EXECUTABLE
    MODFLOW-NWT_1.0.9    - USGS MODFLOW-NWT version 1.0.9 source code
  NOTE: MODELMUSE CAN BE OBTAINED AT THE FOLLOWING WEBSITE: https://water.usgs.gov/nrp/gwsoftware/ModelMuse/ModelMuse.html