SUSTAIN: Sustainable Use Scenario Tool for Analysis and Informing Nebraskans

SUSTAIN consists of four main windows that provide four major aspects operations:

• View watershed model data
• Modify groundwater pumping or recharge
• View groundwater budget
• View groundwater levels

Introduction

Background

Installation

Currently, installing SUSTAIN is very simple.

• Download the version for the groundwater you like to use.
• Uncompress the file
• Execute main.exe

What’s new

TODO: links to download the app

Windows

These are the documents for ech window.

Main Window

The Main window is the first window that appears when the application starts.

It is the container for all other windows using the Multiple Document Interface (MDI) framework.

There are four buttons in the Main window. Each button will open a new window with different functions. These windows are introduced as follows.

Configuration Window

The Configuration window is used to specify the settings Baseline Name File and Scenario Output Dir to have SUSTAIN properly operated.

• Baseline Name File is the file path of the SUSTAIN name file, which includes the information to run the models # (See SUSTAIN name file).
• Scenario Output Dir defines the output directory of the current analysis. All the new model input and output files generated will be placed in this directory.

When the Configuration window starts, it will load the configuration file config.ini # (See Config file) in the same directory of the application. The configuration file includes the saved settings of Baseline Name File and Scenario Output Dir.

There are four buttons in the Main window. Each button will open a new window with different functions. These windows are introduced as follows.

When the Configuration window is closed, the current settings in the window will be automatically saved to the configuration file.

Watershed Model Data

The Watershed Model Data window shows watershed model data including land use, and groundwater pumping and recharge estimated with the watershed model CropSim.

• Data zonation area
  • Show Zones activate a new window displaying the distribution map of the selected output zones (See Zone Plot Window).
  • Load Results load the results from the model files and calculate the pumping, recharge and land cover area for each output zone. It can take a while and the program will be frozen during the reading process.
• Selection area provide the filtering function on the data. Users can select specific variable, zone, crop type and irrigation type for plotting or export. In each selection block, one or more items can be selected. To select multiple items, press the Ctrl when clicking the items or check the boxes. If no item is selected when plotting, the program assumes that all the items are selected (no filtering).
  • Variables Selection Block provide the option of variables to be plotted or exported. Currently, user can select annual groundwater pumping, groundwater recharge or/and land use acres.
  • Zones Selection Block provide the option of zones to be plotted or exported. The items provided in this block will change when the output zone is changed.
  • Crops Selection Block provide the option of crop types to be plotted or exported. The items in this block depends on the crop types used in the waterhsed model and usually include corn, pasture (past), sugar beets, edible beans, alfalfa, winter wheat and soybean.
  • Irrigation Selection Block selection block provides the option of irrigation types to be plotted or exported. There are four irrigation types including dryland (no irrigation), groundwater irrigated, surface water irrigated and commingle irrigated.
• Plot control area include controls to customize the plots.
  • Plot type control if the data are plotted as lines, bars or areas.
  • Stacked Checkbox stack the bar and area plots. Note that the bar and area plots will be stacked based on all other dimensions except the time.
  • Cumulative Checkbox plot the cumulative values instead of the annual values.
  • Sum Zones Checkbox sum the values based on zones. For example, if the user want to plot the total pumping in Box Butte and Cherry counties, the user can select Groundwater pumping and these two counties for data, and check this Agg.Zones checkbox.
  • Sum Crops Checkbox is similar to Sum Zones but it sums over crop types instead of zones.
  • Sum IrrTypes Checkbox is similar to Sum Zones but it sums over irrigation types instead of zones.
  • xAxis Label make change to the title of the x-axis of the plot.
  • yAxis Label make change to the title of the y-axis of the plot.
  • Plot Title make change to the plot title.
  • Plot make the plot based on the selected data and options.
  • Export Data export the plotting data as a spreadsheet. Note that the plotting data can saved only after they are plotted.
• Plotting area is on the right of the window. It includes the plotting figure and the navigation tool bar.
  • Plotting figure occupy the most plotting area. When user resize the window, the size of the plotting figure will change accordingly.
  • Navigation tool bar at the bottom of the plotting area control the view of the figure. The detailed usage of each button can be found on this page: https://matplotlib.org/users/navigation_toolbar.html.

Groundwater Budget

The Groundwater Budget window is similar to the Watershed Model Data window. But it shows groundwater flow data including groundwater pumping, baseflow and groundwater storage change estimated with the MODFLOW groundwater model.

• Data zonation area select the spatial division of the data to be plotted.

  For example, if the NRD option is selected, the model results are aggregated in each NRD. The customized zone allows users select an existing zone file or shapefiles to define the output zone. Please see Create a customized zone.

  • Show Zones activate a new window displaying the distribution map of the selected output zones (See Zone Plot Window).
  • Load Results load the results from the model output file and calculate the pumping, baseflow and groundwaer storage change for each output zone. It can take a while and the program will be frozen during the reading process.

• Selection area provide the filtering function on the data. Users can select specific variables and zones plotting or export. In each selection block, one or more items can be selected. To select multiple items, press the Ctrl when clicking the items or check the boxes. If no item is selected when plotting, the program assumes that all the items are selected (no filtering).

  • Variables Selection Block provide the option of variables to be plotted or exported. Currently, user can select groundwater pumping, baseflow or/and groundwater storage change.
  • Zones Selection Block provide the option of zones to be plotted or exported. The items provided in this block will change when the output zone is changed.

• Plot control area include controls to customize the plots.

  • Plot type control if the data are plotted as lines, bars or areas.
  • Cumulative Checkbox plot the cumulative values instead of the annual values.
  • Sum Zones Checkbox aggregate the values based on zones. For example, if the user want to plot the total pumping in Box Butte and Cherry counties, the user can select Groundwater pumping and these two counties for data, and check this Sum Zones checkbox.
  • Sum Vars Checkbox is similar to Sum Zones but it sums up the selected variables. For example, users want to understand the total increased water availability after retiring irrigation. They can look at the sum of increased baseflow and groundwater storage by selecting these variables and this option.
  • Result type control which data to be used to plot. It includes the baseline data, scenario data and the difference between the baseline and scenario.
  • Stacked Checkbox stack the bar and area plots. Note that the bar and area plots will be stacked based on all other dimensions except the time.
  • Month Checkbox plot the data on monthly basis instead of annual.
  • xAxis Label make change to the title of the x-axis of the plot.
  • yAxis Label make change to the title of the y-axis of the plot.
  • Plot Title make change to the plot title.
  • Plot make the plot based on the selected data and options.
  • Export Data export the plotting data as a spreadsheet. Note that the plotting data can saved only after they are plotted.

• Plotting area is on the right of the window. It includes the plotting figure and the navigation tool bar. - Plotting figure occupy the most plotting area. When user resize the window, the size of the plotting figure will change accordingly. - Navigation tool bar at the bottom of the plotting area control the view of the figure. The detailed usage of each button can be found on this page: https://matplotlib.org/users/navigation_toolbar.html.

Recharge/Pumping Change

The Recharge/Pumping Change Window provides a very versatile tool to change the groundwater recharge and pumping through the WELL package of MODFLOW. It can create new MODFLOW input files based on the recharge or pumping changes you make.

• Menu includes the command buttons that you can used.
  • Add add the current change to the change table on the right of the window.
  • Delete can used to remove a change row from the change table.
  • Save transform all the changes in the change table into MODFLOW input files. When all the files are created, user will be asked whether to run the model.
  • Reset delete all the changes in the change table at once.
  • Run activate the MODFLOW run using the new input files.
  • Help show a description of how to make changes in pumping and recharge.
• Selection area provides options to specify where and when the changes to be made.
  • Input Zone select what spatial division of recharge/pumping you want to make change with. For example, if the NRD option is selected, the changes will be made in the selected NRD areas. The customized zone allows users select an existing zone file or shapefiles to define the input zone. Please see the Customized Zone section.
  • Start Year and End Year specify the years for the change. Please note that the change rate is constant over the selected years for each respective change.
  • Month filtering block specify the months for the change. The annual change rate will be equally distributed by the numbers of days in the selected months.
• Modification area provides two approaches to modify pumping and recharge by changing existing pumping wells or add new pumping/recharge wells. The textbox will be activated after users pick the modification approach.
  • Change existing wells will modify the pumping rates of the existing wells in the selected zones by percentage or by volume provided in the textbox next to it. The volume in acrefeet/yr will be equally distributed among the wells in the selected zones and time.
  • Add new wells will add new wells to each individual grid cell in the selected zones for new pumping or recharge. The volume specified in the textbox next to this option will be distributed to the cells in the selected zones.
• Change table display the changes added by users. Please note that, the changes are made subsequently. Therefore, the changes will be superimposed according to the modification table.

Groundwater Level

The Groundwater Level window display the simulated groundwater levels based on the groundwater model output file.

• Data area
  • Time specify the time of the groundwater levels for the plot.
  • Type control which data to be used to plot. It includes the baseline groundwater levels, scenario groundwater levels and the groundwater level difference between the baseline and scenario.
  • Layer specify the model layer of the groundwater levels for the plot.
• Plot control area include controls to customize the plots.
  • vmin and vmax are the minimum and maximum values used to define the colors in the plot. When the groundwater level data is changed, the program will calculate these values and show them in the textboxes. The data range is also shown in the textbox at the bottom. These values can also be modified after the plot is made in order to, for example, decrease the range to show higher color variability.
  • xAxis Label make change to the title of the x-axis of the plot.
  • yAxis Label make change to the title of the y-axis of the plot.
  • Plot Title make change to the plot title.
  • Plot make the plot based on the selected data and options.
  • Export as Shapefiles export the groundwater levels as shapefiles for further spatial analysis using GIS tools such as ArcMap.
  • Export as Text export the groundwater levels to a ascii text file.
• Plotting area is on the right of the window. It includes the plotting figure and the navigation tool bar.

• Plotting figure occupy the most plotting area. When user resize the window, the size of the plotting figure will change accordingly.
• Navigation tool bar at the bottom of the plotting area control the view of the figure. The detailed usage of each button can be found on this page: https://matplotlib.org/users/navigation_toolbar.html.

Zone Plot Window

The Zone Plot window shows the map of zone distribution used to summarize the gridded model input or output data.

Show Spatial Reference sets whether to include the georeferencing points in the zone plot (see SUSTAIN name file).

Files

To run SUSTAIN, you need to have the App files and the data files. The App files include the SUSTAIN executable and its dependence. The data files include the Watershed model data and MODFLOW model data. The file structures are shown below.

App file tree:

|   SUSTAIN.bat
|
+---main
|   |   main.exe
|   |   SUSTAIN dependence files

Data file structure:

|   SUSTAIN namefile
+---bin
|   |   MODFLOW and other executables
+---baseline
|   |   historical simulation
|   |   future simulation
+---modflow
|   |   modflow data files
+---rswb
|   |   watershed data fiels
+---zones
|   |   zone files

These are the documents for important files used by SUSTAIN.

SUSTAIN name file

The SUSTAIN program reads a name file that contains instructions as to which files to read and write and the parameters to control how the calculations to be performed. A baseline name file is provided with the model files. If you could not find the baseline name file, please contact us for support. Otherwise, you could follow the file format listed below to construct a new name file, or modify the example name file provided below.

Variables

In the SUSTAIN name file, the lines starting with ‘#’ are comments and will not be read by SUSTAIN. An effective line starts with a variable name followed by the value of the variable. Attentions:

1. a variable and its value must and can only be separated by at least one space
2. variable names are case insensitive
3. The variables in the name file can appear in any order.

Below is a list of the variables that may appear in the parameter file. Other variables not in the list will be skipped.

Global variables

PROJNAME projectName

The PROJNAME variable is the project name, e.g. baseline.

MASTER masterDir

The MASTER variable is used to specify the master directory. This variable must be reset to your local computer setting after you download the data or transfer the data. All other directories are set relative to the master directory.

OUTDIR outputDir

The OUTDIR variable sets the output directory. In this directory, you should find the RAW directory generated with the watershed model or other MODFLOW output files. All the new files generated by SUSTAIN will be placed in this directory. The output directory must created before writing any data to it.

Temporal variables

HisSDATE historical_startDate

The HisMFSDATE variable specifies the starting date of the historical simulation. It needs to be in the format YYYY-MM-DD such as 2001-01-01.

FutSDATE future_startDate

The MFSDATE variable specifies the starting date of the future simulation. It needs to be in the format YYYY-MM-DD such as 2001-01-01.

Spatial variables

DIM nLay nRow nCol

DIM sets the model grid dimensions naming numbers of layers, rows and columns.

LowerLeft Xll Yll

The LowerLeft variable sets the real-world coordinates (usually in the Nebraska State Plane Coordinate System with feet as unit) of the lower left corner of the model grid.

GEOREF CSV

The GEOREF variable sets the file path of the CSV file containing the locations of georeferencing locations used as in map (zones or groundwater level) plots. Note that a *.csv(comma delimited) file needed to be used. The CSV file must contains the X, Y and Name columns.

MASK maskFile

The MASK variable sets the file path of the mask that specifies the MODFLOW active areas.

Watershed model variables

HisYr historical_call_year_table

The HisYr variable sets the file path for the historical call year tables (CSV file). A call year table include two columns including the model year and the actual year.

FutYr future_call_year_table

The FutYr variable sets the file path for the future call year tables (CSV file). A call year table include two columns including the model year and the actual year. For future simulation, it usually repeats the historical simulation. The call year table defines the actual historical years are used for each future model years.

CROP InCropTypes

The IRRI variable sets the crop names used in the watershed input files.

LUCROP OutCropTypes

The LUCROP variable sets the crop names used in the raw watershed output files.

IRRI InIrrigationTypes

The IRRI variable sets the irrigation types used in the watershed input files.

LUIRRI OutIrrigationTypes

The LUIRRI variable sets the irrigation types used in the raw watershed output files.

COEFF

The COEFF variable sets the file path of the watershed coefficients for varying zone and soil combinations. The columns in this file can include Zone, Soil, DryETAdj, IrrETadj, NIRadjFactor, AEgadj, Fslgw, DryETtoRO, AEsadj, Fslsw, PertoRchg, DPadj, ROadj, CMsplit.

COEFFRO

The COEFFRO variable sets the CSV file path of the runoff coefficient (loss_per_mile) table whose rows are zones and columns are soils.

CELLLOC

The CELLLOC variable sets the file path of the coefficient location file. The columns in this file can include Cell, Soil, CoefZone, ROZone, MiToGage.

Groundwater model variables

HisMFNAM historical_MF_namefile

The MFNAM variable sets the file path of the MODFLOW name files of the historical MODFLOW simulation. # (See ../files/mfname).

FutMFNAM future_MF_namefile

The MFNAM variable sets the file path of the MODFLOW name files of the future MODFLOW simulation. # (See ../files/mfname).

NCBB cbbFileNum

The NCBB variable sets the file number for the cell-cy-cell flow file output by the baseline MODFLOW model.

NHDS hdsFileNum

The NHDS variable sets the file number for the groundwater head file output by the baseline MODFLOW model.

NDDN dnnFileNum

The NDDN variable sets the file number for the drawdown file output by the baseline MODFLOW model.

### TODO: Update Example

Example name file

# Comment starts with '#'
# Attentions:
#   1. a variable and its value must and can be separated by at one or more spaces
#   2. variable names are case insensitive

###########################################################
#################### Global Parameter #####################
###########################################################

PROJNAME baseline
MASTER D:\UNW\gui-lite\unw-full
OUTDIR rswb\Run019\Results



###########################################################
##################### Grid Parameter ######################
###########################################################

DIM 2  92  135
SHPGEOREF city.shp
SHPGEOREFLBL
SHPGRID zones\UNW_WholeGrid.shp
SHPGRIDROW ROW
SHPGRIDCOL COL
MASK modflow\ibound.txt


###########################################################
################### Watershed Section #####################
###########################################################
YEARS   rswb\Run019\Inputs\historicalyear.csv rswb\Run019\Inputs\futureyear.csv
COEFF   rswb\Run019\Inputs\CoefTest_MZ.txt
COEFFRO rswb\Run019\Inputs\ROZoneCoef.txt
CELLLOC rswb\Run019\Inputs\CellLoc3mz.csv
CROP Corn SugarBeets EdibleBeans Alfalfa WinterWheat Potatoes Milo Sunflower SoyBeans SmallGrain Fallow Past
LUCROP Corn Sugar_Beets E_Beans Alfalfa W_Wheat Potatoes Sorghum Sunflower Soybeans S_Grains Fallow Pasture
IRRI Dry GW SW CO
LUIRRI Dry GW SW CO


###########################################################
#################### MODFLOW Section ######################
###########################################################


MFNAM baseline\historical.nam baseline\future.nam
MFSDATE 1960-01-01 2011-01-01
MFDISSKIP 3873

NCBB 50
NHDS 30
NDDN 31

MFHDRY -1.000000e+030

Config file

The config.ini file is placed in the same directory as the SUSTAIN executable. This file sets the file paths used in the Main window. The purpose of this file is to let the App remember the user settings. Each setting occupies one line of the file. Currently, only two settings are save in this file.

1. baseline name file path
2. Output directory

The file is usually saved by SUSTAIN through the Configuration window (See Configuration Window). However, experienced user can also modify the config.ini file using text editing tools.

Executable and batch files

SUSTAIN Executable

SUSTAIN is developed using wxPython. It also uses several packages for a range of tasks. The SUSTAIN executable for Windows will be compiled and distributed (for other OS, please contact us) for each version. The SUSTAIN executable is named as main.exe. With the SUSTAIN executable file, there are also other dependence files that used by SUSTAIN. To start SUSTAIN, double-click main.exe or the batch file SUSTAIN.bat which is a shortcut to the executable.

How to

These guides provide some tutorials.

Add a new canal in the model

todoList

Create a customized zone

There are two methods to create customized zones.

Increase pumping rate by 10%

todoList

Frequently Asked Questions

Why my application isn’t running?

todoList

Can I export the plot?

todoList

Can I export the plotting data?

todoList

Can I use SUSTAIN for other models?

todoList

Indices and tables

• Index
• Module Index
• Search Page

In Progress