Python toolkit using GRASS GIS to generate inputs for the USGS hydrologic model "GSFLOW".

GSFLOW is the US Geological Survey's combined groundater (MODFLOW) and surface water (PRMS) model. GSFLOW-GRASS builds a stream network and its "hydrologic response units" -- here, watershed sub-basins -- that combine to form a surface-water hydrologic network (PRMS). It then links these to a regular finite difference grid to compute groundwater flow using MODFLOW.

These instructions are meant to take an user familiar with computers but new to (or a beginner with) GSFLOW and GRASS GIS through the basics of how to get GSFLOW-GRASS to work. Please leave a message if you have trouble working with GSFLOW-GRASS; your comments could assist both you and the more general improvement of this documentation.

When you use GSFLOW-GRASS, please contact us; a reference (Ng et al.) will be noted here as soon as the paper is made available.

This manual is written in the style of a quick(-ish) start guide that allows users to get GSFLOW up and running for their target watershed using mostly default options in our toolkit and without modifying GRASS-GIS or Python scripts. Additional customization is possible by more advanced users by editing our GRASS GIS and input file building scripts to extend the set of parameters incorporated \todo{Andy: make section on adding GRASS parameters; perhaps just a small part at the end with appropriate links}.

• GSFLOW 1.2
• GRASS GIS 7.3+ and extensions (described below)
• Python 2.7.X
• GSFLOW-GRASS Toolkit (this software)

\todo{This isn't actual directory structure now. Change after finalizing. Will need to make sure everything still runs, i.e., can find dependent files etc}

• GSFLOW-GRASS -> domain_builder GRASS GIS Python scripts to build the watershed and MODFLOW geometries
• GSFLOW-GRASS -> input_file_builder Python scripts to create input files for GSFLOW, including the control file, paramers file for PRMS, and input file for MODFLOW (NWT)
  • GSFLOW_print_controlfile_current.py
  • GSFLOW_print_PRMSparamfile_current.py
  • print_MODFLOW_inputs_res_NWT_current.py
  • -> MODFLOW_scripts \todo{consider doing away with this sub-directory?}
    • MODFLOW_NWT_lib_current.py \todo{modify to read in down-gradient cell of discharge point}
• Create_hydcond_array.py
• GSFLOW-GRASS -> Run ->
  • settings_template.ini
  • settings_test.py
  • run_Python_GSFLOW_current.sh \todo{re-name as go-GSFLOW.sh}
  • run_Python_GSFLOW_current_Win.bat \todo{re-name as go-GSFLOW.bat}
• GSFLOW-GRASS -> visualization
  • Plot_MODFLOW_inputs.py
  • plot_gsflow_csv.py
  • gsflow_csv_table.py
  • Plot_MODFLOW_3D_head3.py
  • Plot_MODFLOW_3D_uzf.py \todo{Andy: put GRASS-GIS scripts for plotting HRU-distributed variables here? Or above with domain-builder scripts?}
• GSFLOW-GRASS -> examples
  • Shullcas
  • Santa Rosa \todo{space here?}

Use settings_template.ini as a template for creating your own Settings File, which can have any name. Boldface options are required. This files includes:

\todo{MAKE EVERYTHING REQUIRED BOLD}

\todo{how to run GRASS module? From Pre-Processing + Run File? Or separately?}

\todo{increment list number if need separate step for GRASS module}

The Go-GSFLOW File (go-GSFLOW.sh on Linux and go-GSFLOW.bat on Windows) is executed for pre-processing and running GSFLOW.

\todo{change file name; currently `run_Python_GSFLOW_current.sh.' Also, update Windows batch file}

At the top of the file, the user should customize:

• preproc_dir full pathname for location of GSFLOWGRASS_toolkit] \todo{scripts might end up in directory w/in preproc_dir; make changes accordingly.}
• settings_file Full pathname for Settings File (customized in Step 1).

The rest of the file will execute pre-processor scripts to set up certain inputs (climate forcing data and hydraulic conductivity) according to the Settings File, and to create GSFLOW input files (control file, PRMS parameter file, and MODFLOW input files); it then runs GSFLOW. In the default implementation, the user does not need to change the bottom part of the file with Python scripts. However, certain lines may be commented out or changed, as described in the following:

• python2.7 \${preproc_dir}settings_test.py} Imports all the values set in Settings File. This line must always be included.
• python2.7 \${preproc_dir}Create_hydcond_array.py: If fl_create_hydcond=1 in Settings File, this script creates spatially distributed hydraulic conductivity values; see top of script to select from options. This line may be changed to a different script name if the user writes their own script for creating spatially distributed hydraulic conductivity. If fl_create_hydcond=0, this line may be left in; nothing will be done in the script.
• python2.7 \${preproc_dir}GSFLOW_print_data_climatehru_files1_metric.py If fl_print_climate_hru=1 in Settings File, this script creates climate_hru files with spatially uniform conditions, based on data from climate_data_file in Settings File. This line may be changed to a different script name if the user writes their own script for creating spatially distributed climate inputs. If fl_print_climate=0, this line may be left in; nothing will be done in the script.
• python2.7 \${preproc_dir}GSFLOW_print_controlfile_current.py: This script creates GSFLOW control file. This line generally should be included, but it may be commented out if the user has already run the script previously and will be using the same file in its same location.
• python2.7 \${preproc_dir}GSFLOW_print_PRMSparamfile_current.py: This script creates the PRMS parameter file. This line generally should be included, but it may be commented out if the user has already run the script previously and will be using the same file in its same location.
• python2.7* \${preproc_dir}print_MODFLOW_inputs_res_NWT_current.py: This script creates all the MODFLOW input files. This line generally should be included, but it may be commented out if the user has already run the script previously and will be using the same files in their same location.
• python2.7* \${preproc_dir}run_GSFLOW.py: This script executes the GSFLOW model. This line generally should be included, but it may be commented out if the user only wishes to create the input files without running the model.

For the default implementation, the user can proceed to Step 3. However, extra steps are needed if the user has specified any of the following:

• Settings File, fl_create_hydcond=1: Set options at the top of \${preproc_dir}Create_hydcond_array.py script for different spatial distribution configurations. Other steps may be needed if the user replaces this script with their own to create spatially distributed hydraulic conductivity fields.
• Settings File, fl_print_climate=1: Create file specified climate_data_file, which should have climate data time series from one weather station for daily minimum temperature, maximum temperature, and precipitation. See example problems for the file format (e.g., in Shullcas -> UserData -> ), which should be the following:
  • line 1: comment
  • line 2: tmax for daily maximum temperature, 1 for number of weather stations
  • line 3: tmin for daily minimum temperature, 1 for number of weather stations
  • line 4: precip for daily precipitation, 1 for number of weather stations
  • line 5: #################################### to indicate start of data
  • line 6: YYYY Month Day 0 0 0 (value for tmax) (value for tmin) (value for precip), etc. for all dates in daily time series

All temperature data in this file are assumed to be in [°C], and precipitation data in [mm/d] (these are eventually converted to [°C] and [in/d] for the PRMS model component). This file can be expanded to include relative humidity (in [%]) (used if Penman-Monteith option is selected for the potential ET module) and solar radiation (in [MJ/m²]) if available. Other steps may be needed if the user replaces this script with their own to create spatially distributed hydraulic conductivity fields.

Settings File, fl_print_climate_hru=0: RESUME HERE

Two options:

• Cross-platform binaries: https://grass.osgeo.org/download/software/
• Instructions to build from source:
  • https://grasswiki.osgeo.org/wiki/Compile_and_Install
  • https://grasswiki.osgeo.org/wiki/Compile_and_Install_Ubuntu

If you choose to compile GRASS GIS from source, A. Wickert has used these configuration flags many times on Ubuntu (configure_ubuntu.sh):

CFLAGS="-O2 -Wall" LDFLAGS="-s" ./configure \
--enable-largefile=yes \
--with-nls \
--with-cxx \
--with-readline \
--with-pthread \
--with-proj-share=/usr/share/proj \
--with-geos=/usr/bin/geos-config \
--with-wxwidgets \
--with-cairo \
--with-opengl-libs=/usr/include/GL \
--with-freetype=yes --with-freetype-includes="/usr/include/freetype2/" \
--with-postgres=yes --with-postgres-includes="/usr/include/postgresql" \
--with-sqlite=yes \
--with-mysql=yes --with-mysql-includes="/usr/include/mysql" \
--with-odbc=no \
--with-netcdf=/usr/bin/nc-config

Before running GSFLOW, the user should:

\todo{Andy, this is where to put ways to customize GRASS GIS code; mostly links should be OK} \todo{Also link this to Crystal's code}