Publication: Ellis, J.H, Knight, J.E., White, J.T., Sneed, M.I., Hughes, J.D., Ramage, J.K, Braun, C.L., Teeple, A.P., Foster, L., Rendon, S.H., Brandt, J., 2022, Hydrogeology, Land-Surface Subsidence, and Documentation of the Gulf Coast Land Subsidence and Groundwater-Flow (GULF) model, Southeast Texas, 1897-2018: U.S. Geological Survey Professional Paper 1877, https://doi.org/10.3133/pp1877 Data Release: Knight, J.E, Ellis, J.H, White, J.T., Sneed, M.I., Hughes, J.D., Ramage, J.K, Braun, C.L., Teeple, A.P., Foster, L., Rendon, S.H., Brandt, J., Duncan, L.L., Traylor, J.P., and Pattison, C.N., 2022, MODFLOW 6 model and ensemble used in the simulation of groundwater flow and land subsidence in the northern part of the Gulf Coast aquifer, 1897–2018: U.S. Geological Survey data release version 2.0, https://doi.org/10.5066/P9XM8A1P. Archive created: April 15, 2022 Archive updated: September 15, 2023 gulf_model_archive/ Description: ----------- This data release version 2.0 has been updated from the original version to include additional model outputs. The model inputs are identical to those included in data release version 1.0 and will produce identical results. The underlying directories contain all of the input and output files for the simulations described in the above report, MODFLOW 6 (v 6.2.1) source code, and PEST++ (v 5.1.0) source code. Executables for Windows, Mac, and Linux can be downloaded from these links below. Current versions (as of the date of archive creation) are also included in the model archive, but beware using these newer versions may produce slightly different results than the archived output. [MODFLOW 6] (https://github.com/MODFLOW-USGS/modflow6/releases/tag/6.2.1) [PEST++] (https://github.com/usgs/pestpp/releases/tag/5.1.0) Descriptions of the data in each directory are given to facilitate understanding of this data release. Files descriptions are provided for select files to provide additional information that may be of use for understanding this data release. See MODFLOW 6 or PEST++ documentation in the appropriate sub-folder of the source directory for information on file types not explicitly described herein. 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 (https://doi.org/10.3133/pp1877) to understand the purpose, construction, and limitations of the GULF model and ensemble. Reconstructing the data release from the online data report: ------------------------------------------------------------- This data release is available from: https://doi.org/10.5066/P9XM8A1P The GULF model and ensemble will run successfully only if the original directory structure is correctly recreated. This model archive relies heavily on Python scripts to run the ensemble and process output files, and these scripts rely on files being in the correct relative path locations.The data release is broken into several pieces to reduce the likelihood of download timeouts. Small files (such as 'readme_v2.txt' and 'modelgeoref.txt') are available as uncompressed files. All other files are zipped at the subdirectory level. For example, the files in the "processed_data" subdirectory are zipped into a zip file named "processed_data.zip". To assemple the model archive, create a new local directory and download each of the following files (do not extract zipped folders yet) so that they reside in the same folder, e.g.: gulf_model_archive/ 7z.exe activate_gulf_env.bat extract_gulf_files.bat gulf.zip * gulf_history_ies_gm_filter.zip gulf_history_post_base.zip * gulf_history_post_base_ancillary.zip * gulf_ies_workflow.zip * gulf_zonebudget.zip * model_plots.zip processed_data.zip * soil_water_balance.zip * source.zip source_data.zip static_packages.zip plot_gulf_model.py run_gulf_model.py run_gulf_zonebudget.py modelgeoref.txt readme_v2.txt Files denoted with * above indicate that these are not needed to run the posterior base realization, which is referred to as "The GULF Model" in the companion Professional Paper report. The two largest zipped sub-directories ('gulf_history_ies_gm_filter.zip' and 'soil_water_balance.zip') are not required to be downloaded to reproduce the posterior base realization results. For the purposes of executing the base realization of the posterior ensemble all necessary file extraction is performed by executing the batch file 'extract_gulf_files.bat'. This maintains the correct directory structure required by the python scripts to execute the GULF model and process results. NOTE: ----- THE PYTHON SCRIPT "run_gulf_model.py" MUST BE USED TO ACCURATELY REPRODUCE "The GULF Model" INPUTS AND OUTPUTS PRESENTED IN THE COMPANION PROFESSIONAL PAPER REPORT. SEE INSTRUCTIONS BELOW IN SECTION "Running the GULF model" The GULF model was developed as part of an ensemble using the PEST++ Iterative Ensemble Smoother software (pestpp-ies). All ensemble inputs and outputs can be accessed in the zipped directory "gulf_history_ies_gm_filter.zip." The scripts used to create and run the ensemble can be accessed in the zipped directory "gulf_ies_workflow.zip." Eleven Soil-Water-Balance (SWB) models spanning between 6 and 17 years cover the simulation period of the model and were used to develop the recharge inputs to the GULF model and ensemble. To execute the SWB models described in the report, only the zipped directory 'soil_water_balance.zip' needs to be downloaded. The SWB models run independently from the GULF model and can be located in a separate directory, e.g.: soil_water_balance/ SWB_output_1897_1914/ SWB_output_1915_1929/ etc... System requirements: -------------------- The model contained in the model subdirectory of this data release was run using the mf6.exe executable in the bin directory. The GULF model and ensemble have been run successfully on computers running the 64-bit Windows 10 operating system. Python 3 (https://www.python.org/download/releases/3.0/) and a number of packages need to be used in order to use the run_gulf_model.py and plot_gulf_model.py scripts included in the main directory, and to reproduce the scripted Iterative Ensemble Smoother (iES) workflow in the gulf_ies_workflow directory. A self-contained python distribution is included in the archive (gulf.zip), and is automatically extracted and activated by executing the batch file "activate_gulf_env.bat". See below for more information on extracting the model files using the .bat files. The GULF model MODFLOW 6 input files can be executed without python, but results will be unprocessed, complicating the comparison with published results. SEE IMPORTANT NOTES IN NEXT SECTION "Running the GULF model." Running the GULF model: --------------------- Open a command line/terminal in the top level directory and execute the batch script (only type the portion after ">"): \gulf_model_archive>extract_gulf_files.bat This script unzips the python environment needed to run the model, and unzips additional python packages (flopy, pyemu, spnspecs) and data directories (source_data, processed_data) needed for model execution. This batch script only needs to be executed once after downloading. It does not need to be executed before each time executing the model. A second batch file needs to then be executed to activate the python environment: \gulf_model_archive>activate_gulf_env.bat NOTE: ----- The file activate_gulf_env.bat must be executed each time a new command line/terminal is opened to run the model. After executing this script the command line will be prepended with "(gulf)" to show that the gulf python environment is active. Executing the following command without the gulf python environment activated may fail or give different results depending on the python packages and versions present in your default python environment. To run the base realization of the posterior ensemble, type: (gulf) \gulf_model_archive>python run_gulf_model.py This python script unzips the directory "gulf_history_post_base.zip" and executes the MODFLOW 6 model using PEST++. After model completion, the script formats observation data to match PEST++ ensemble style observation data for convenient plotting with python scripts that were written to handle ensemble results in the iES workflow. Depending on system configuration, model execution can take several hours. NOTE: ----- Executing the GULF model through the python script run_gulf_model.py is the safest way to ensure model inputs and outputs align with the published report. The python script calls the PEST++ executable (pestpp-ies.exe) and control file (gulf_history.pst) to build model input files, execute the MODFLOW 6 software, and process results. NOTE: ----- DO NOT EXECUTE THE MODFLOW 6 SOFTWARE "mf6.exe" ON ITS OWN. IF EXECUTED OUTSIDE OF THE run_gulf_model.py SCRIPT, MODEL INPUTS WILL NOT REFLECT THE ESTIMATED PARAMETERS OF THE POSTERIOR ENSEMBLE BASE REALIZATION, AND MODEL OUTPUTS WILL NOT ALIGN WITH THE PUBLISHED REPORT Plotting the GULF model results: --------------------- To plot the base realization results, type the command below. Plots are saved to the directory model_plots\gulf_history_post_base. (gulf) \gulf_model_archive>python plot_gulf_model.py Running Zonebudget utility on GULF model results: --------------------- To execute Zonebudget utility, type the command below. Outputs are saved to the directory \gulf_zonebudget. (gulf) \gulf_model_archive>python run_gulf_zonebudget.py NOTE: ----- The posterior base realization of the GULF model must be run to completion before attempting to execute zonebudget script. See section "Running the GULF model" above for instructions. Running the SWB models: --------------------- Open a command line/terminal in the a directory where one of the SWB models was extracted, e.g.: \soil_water_balance\SWB_output_1897_1914\SWB_CLAGM_1897_1914> Execute the following command: >SWB.bat This batch script calls the swb.exe application with an argument for the simulation control file recharge.ctl. The model can take several hours to run. Gridded data of simulated monthly and annual mean recharge is written to the output folder, and summary data is written to the directory where the batch script was executed. NOTE: ----- The model will overwrite the existing output. Each SWB model requires several GB of disk storage. File Directory: -------------- gulf.zip Description: ----------- Self-contained python environment including all packages needed to build, execute, and post-process the GULF model. Follow instructions above to extract and activate the environment using included batch scripts. gulf_history_ies_gm_filter.zip Description: ----------- Includes prior and posterior ensembles. The results from executing these ensembles appear in the companion report as filled grey regions behind a solid line representing the base realization. gulf_history_post_base.zip Description: ----------- Model input and output files for posterior base realization. Following the command line input instructions above, this directory is automatically extracted from gulf_history_post_base.zip and the model is executed by calling on the PEST++ control file. Model output in the extracted directory will be overwritten each time the model is executed. Original model output data as downloaded from the archive will remain in the zipped directory. gulf_history_post_base_ancillary.zip Description: ----------- This directory contains large model output files for posterior base realization, 1-indexed model stress period table, and groundwater level residuals summary table. It is provided for user convenience and not required to be downloaded or extracted for executing the model. Files: ------ gulf_history.cbb: MODFLOW 6 cell-by-cell budget binary output file for the GULF model. gulf_history.hds: MODFLOW 6 simulated heads binary output file for the GULF model. GULF_Model_StressPeriodTable.csv: comma delimited text file containing a table of 1-indexed model stress periods with associated start and end calendar dates and stress period lengths in days. Report_residuals_summary_table.xlsx: Microsoft Excel spreadsheet containing summary statistics of groundwater-level residuals by aquifer unit for the GULF model. gulf_ies_workflow.zip Description: ----------- This directory contains all necessary files to reproduce the workflow that produced the GULF model. The python script build_model.py generates the original MODFLOW 6 model subsequently parameterized and upgraded with the python script build_pst.py. The parameter estimation process undertaken with pestpp-ies relies on many parallel runs and is infeasible to execute on a single local machine. bin/ Description: ----------- Contains applications used in the GULF model development workflow. win_mf621_pestpp5100/ Description: ----------- Contains applications used in the GULF model development workflow. Files: ------ mf6.exe: MODFLOW 6 version 6.2.1 executable pestpp-ies.exe: PEST++ iES version 5.1.0 executable zbud6.exe: ZONEBUDGET version 6.1.1 executable Files: ------ 7z.exe: 7-Zip version 19.00 executable used in Python scripts to compress and extract files build_model.py: Python script to build and run the original MODFLOW 6 model subsequently parameterized and upgraded with PEST++ iES build_pst.py: Python script to parameterize and upgrade the original MODFLOW 6 model, resulting in prior and posterior model ensembles check_progress.py: Python script to check progress of ensemble runs gulf_model_par_bounds.csv: Table of multiplier parameter ranges to be applied in the build_pst.py script gulf_workers.sub: HTCondor worker submit file history_model_timestepping.csv: Table of model temporal discretization model_grid_with_counties.csv: 2-dimensional array of model grid denoting county coverage plot_results.py: Python script to plot results of prior and/or posterior ensembles python.zip: Stand-alone python distribution used to build and parameterize the model, but not to plot results. rmr_invest.py: Python script to analyze model realization runtimes and rates of success on parallel machines set_path.bat: Batch script used to set the path to the (unzipped) python directory wee.txt: A small test file sent to and returned from HTCondor workers worker.bat: Batch script sent to HTCondor workers to execute parallel model realizations gulf_zonebudget.zip Description: ----------- This directory contains all necessary files to execute various zonebudget calculations scripted in run_gulf_zonebudget.py GULF model results. NOTE: ----- The parameter {ZoneCoverage} is used to simplify the description of 5 different input and output datasets for Zonebudget calculations. Zonebudget was deployed for the following geographic coverages: Counties: {ZoneCoverage} = "county" in filenames Groundwater Conservation Districts: {ZoneCoverage} = "gcd" in filenames Groundwater Management Areas: {ZoneCoverage} = "gma" in filenames GULF active model domain: {ZoneCoverage} = "gulf" in filenames Regional Water Planning Groups: {ZoneCoverage} = "rwpg" in filenames Files: ------ utils-zonebudget_zones_{ZoneCoverage}.dat: Zonebudget input array of zone numbers assigned to each model cell zbud_{ZoneCoverage}.lst: Zonebudget output summary {ZoneCoverage}_lookup.csv: Table relating zone number to geographic name zbud_{ZoneCoverage}.csv: Table includes raw ZoneBudget output in model units of cubic meters per day and discretized by model stress period zbud_{ZoneCoverage}_afy.csv: Table includes ZoneBudget output converted from model units to acre-feet per year zbud_{ZoneCoverage}_afy_units_combined.csv: Table includes ZoneBudget output converted to acre-feet per year and aquifer units combined by geographic zone zbud_{ZoneCoverage}.nam: Zonebudget .nam file called when executing zonebudget utils-zonebudget_{ZoneCoverage}.zon: Zonebudget input file that points .nam file to utils-zonebudget_zones_{ZoneCoverage}.dat file model_plots.zip Description: ----------- Plotted results of the GULF model posterior base realization. gulf_history_post_base/ Description: ----------- Plotted results of the GULF model posterior base realization. NOTE: ----- Files in this directory will be overwritten without warning by executing the python script "plot_gulf_moodel.py." processed_data.zip Description: ----------- Observation and ancillary model input data. Not required to execute GULF model, but necessary for plotting results with plot_gulf_model.py processed_obs_data/ Description: ----------- Lookup tables containing information for observation sites and time series values organized by observation group. processed_rech_input/ Description: ----------- Processed SWB model output in the form of one 2-dimensional array per model stress period. In the GULF model development workflow these data are further processed to produce input data for the MODFLOW 6 recharge package. processed_well_data/ Description: ----------- Processed WEL input data in the form of two tables per model stress period representing irrigation and non-irrigation type water use. These data are used to compare model inputs with posterior simulated water use. source.zip Description: ----------- Source code for MODFLOW 6 (version 6.2.1) and PEST++ (version 5.1.0) source_data.zip Description: ----------- Geographic and wateruse source data. Not required to execute GULF model, but necessary for plotting results with plot_gulf_model.py. Leveled adjusted elevations from benchmarks on table 4 are included in a comma-separated values file in the root directory (Benchmark elevations.csv). gis/ Description: ----------- Shapefiles representing cross section locations and county boundaries used in plot_gulf_model.py gulf_grid/ Description: ----------- Shapefile representing GULF model grid used in plot_gulf_model.py, and 2-D array files of selected initial model input properties derived from shapefile attribute columns static_packages.zip Description: ----------- Python packages used by run_gulf_model.py and plot_gulf_model.py. This directory is extracted to the proper directory level by the batch script "activate_gulf_env.bat." They are stored separately from the self- contained python environment because they acquired outside of the conda download channels. flopy/ Description: ----------- FloPy python package used to create and interface with MODFLOW 6 input and output files. pyemu/ Description: ----------- PyEmu python package used to create and interface with PEST++ input and output files. spnspecs/ Description: ----------- spnspecs package used to implement USGS publishing standards on graph and map figures. soil_water_balance.zip Description: ----------- Self-contained directory of inputs and outputs associated with eleven Soil-Water-Balance models spanning the model simulation period 1897 - 2018. Files: ----- 7z.exe: 7-Zip version 19.00 executable used in batch files to extract archive directories plot_gulf_model.py: Python script to plot results of posterior base realization model run_gulf_model.py: Python script to run posterior base realization model activate_gulf_env.bat: Windows batch script to activate gulf model Python environment extract_gulf_files.bat: Windows batch script to extract zipped archive directories modelgeoref.txt: Text file containing model georeference information readme_v2.txt: (this file) describes organization and use of model archive