Latest revision as of 18:53, 20 May 2008

There are two required output files for each GSSHA simulation. These two files are specified with the OUTLET_HYDRO and SUMMARY project file cards, and contain the hydrograph at the catchment outlet and a summary of model performance, respectively (Table 21).

In addition to specified outputs GSSHA automatically outputs a file called MASKMAP which is an GRASS ASCII map of the cell numbers as stored internally within GSSHA. This file can be used to locate problem cells when GSSHA gives a message referring to the cell number, instead of the i and j location. When continuous simulations are performed GSSHA also outputs a file called evap_out which list basin wide average hourly values of: soil moisture, potential evaporation (cm hr^-1), actual ET (cm hr^-1), infiltration rate (cm hr^-1), groundwater recharge (cm hr^-1), continuous frozen ground index, temperature (C), gridded temperature (C), surface soil temperature (C).

14.1 Required Flags and Files

Table 21 – Required output cards

The outlet hydrograph file has no header, and contains two columns of real values. The first column contains the time in minutes since the beginning of the simulation for event simulations, the time in decimal years for continuous simulations, or the strict Julian date if the STRICT_JULIAN_DATE card is used in the project file. The second column contains the discharge, m³s^-1 default, or ft³s^-1 if the QOUT_CFS project card is present.

14.2 Run Summary File

The run summary contains a summary for each event simulated and simulation totals after the last event summary. For each event the run summary file contains a number of sections: title, start-up inputs, mass-conservation, warnings, and outputs. If Richards’ equation is used to simulate the unsaturated zone a separate mass-conservation section is included in each event summary. If saturated groundwater is simulated then a separate mass-conservation is included in each event summary. The following is an example of the run summary file output for a continuous simulation with a single event. In this example Richards’ equation is used to simulate the unsaturated zone and lateral groundwater flow is calculated, along with interaction with the stream network.

_________GSSHA start-up information________
Run parameters read from WMS project file: 10gw.prj
reading watershed mask from file: test.mask
number of grid cells in watershed: 110
reading elevation map from file: elev_file
reading soil map from file: test.mask
reading water table map from file: test.wt
reading aquifer bottom map from file: test.gwb
Inital volume of water in root zone= 4989.621857 
 
Inital volume of water in soil column= 574165.748622 
 
reading groundwater boundary file: test.bound
reading hyd. cond. map from file: hycond_file
reading link map from file: test2.link
reading node map from file: test2.node
reading channel input data from file test.chan1
Initial soil water volume= 24948.109285 
writing output for optimization to file 
using precipitation data from file: one_event.gag
Running.... 

       GSSHA LONG-TERM RUNOFF SIMULATION SUMMARY- EVENT 1
Event began on strict Julian date:                    2445113.04166667
Event ended on strict Julian date:                    2445113.66111111
Event began on 05/23/1982 at 13:00  GMT -6.0 hours.

GSSHA used NCDC/SAMSON hydrometeorological data from the MEMPHIS                station
Hydrometeorology data began on: 05/24/1982 at  3:00
and ended on:                   07/01/1982 at  0:00
The following number of hydromet. data points were repaired:0
Penman-Monteith evapo-transpiration was calculated.

With raingage data using Thiessen polygon interpolation.

time step                                  60.0 seconds
elevation and gridsize are in meters
initial basin-averaged soil water content:16.21 percent
number of time steps with rain:             630
elapsed time when rain began:             2204.00
 
peak occured on strict Julian date:                 2445113.45486111
date/time of peak discharge:           5/23/1982  22:55:00
peak discharge (cms):                      4.22
 
initial volume on overland (cu. m):        0.0
initial volume in channels (cu. m):        0.0
inital volume of snow (cu. m):             0.0
 
volume of rainfall (cubic meters):    225500.0
volume of discharge (cu. m):          122219.5
volume of infiltrated water (cu. m):   99579.3
volume of water exfiltrated (cu. m):       0.0
volume of lateral inflow (cu. m):     122652.2
volume of gw to chan (cu. m):           -402.6
volume from overland point sources         0.0

volume remaining on surface (cu. m):    2005.3
final volume in channels (cu. m):         29.9
final volume of snow (cu. m):              0.0
 
mass conservation error:             0.0001 percent

 
 Richard's EQ. Computations 
 
volume lost due to dir. evap (cu. m):     1263.3
net vol infiltrated to soil (cu. m.):    99354.7
volume to deep ground water (cu. m):      1025.9
Initial volume in soils (cu. m.):       574198.2
Final volume in soils (cu. m.):         670524.7
Richard equation mass balance error         -0.1902 percent
Number of cells at start of event           9595
Number of cells at end of event             9589
net volume of infiltration is infiltration minus evaporation

 
 GROUNDWATER CALCULATION SUMMARIES FOR EVENT 
 
volume of water directly to surface from groundwater (cu. m):       0.0
beginning vol of water exfiltrated this event (cu. m):              0.0
total vol of water exfiltrated this run (cu. m):                    0.0
vol from gw to unsat this event (cu. m):                         -910.1
vol from gw to chan  this event (cu. m):                         -402.6

final basin-averaged soil water content:74.69 percent

 THE FOLLOWING WARNINGS ARE GIVEN:
No Warnings.

 THE FOLLOWING INPUTS WERE READ:
A WMS Project File was used.
Floating point GRASS maps were read.

 THE FOLLOWING PROCESSES WERE SIMULATED:
Explicit diffusive-wave channel routing.
Uniform overland roughness.
Infiltration by Richards Eq.

 THE FOLLOWING OUTPUT MAPS WERE WRITTEN EVERY 60 TIME STEP(S):
ASCII WMS maps of:
     overland flow depth.

 THE FOLLOWING ASCII OUTPUT FILES WERE WRITTEN TO EVERY 1 TIME STEP(S):
     hydrograph at the catchment outlet.

 
SIMULATION TOTALS
 
GROUNDWATER CALCULATIONS 

GW volume start =                  58878050.00 
GW volume end =                    58880266.51 
Sat/unsat. trickery =                     0.00 
Exfiltration back on overland =           0.00 
Infiltration to groundwater =           900.98 
Total inputs to groundwater=           2212.47 
Mass Balance error =                     -0.00 

 
GLOBAL MASS BALANCE CALCULATIONS 
All volumes are in cubic meters 
 
Initial volume on surface=                 0.00 
Initial volume in channels=                0.00 
Initial volume in soils=              574165.75 
Initial volume in groundwater=      58878050.00 
 
Final volume on surface=                2005.27 
Final volume in channels=                 29.94 
Final volume in soils=                670524.67 
Final volume in groundwater=        58880266.51 
Final volume of snow=                      0.00 
 
Total amount of precip=               225500.00
Total amount of infiltration=          99579.28
Total amount of evaporation=            1576.53
Total direct evaporation=               1263.26
Total flux from unsat to gw=             900.98
Total amount of discharge=            122219.46
Total flux of gw across bounds=            0.00
Total flux from gw to river=            -402.57
Total amount of exfiltration=              0.00
Total overland point sources=              0.00
 
Mass balance error of inputs=          0.000094 percent
 
Overall mass balance error =          -0.001836 percent

14.3 Optional Flags

The optional flags are listed in Table 22.

Table 22 – Optional output cards

14.4 Time Series Data at Internal Locations

GSSHA has the capability to save time series data of a number of parameters at internal locations in the channel network and within cells in the 2-D grid.

14.4.1 Time Series Data at Internal Stream Network Locations

GSSHA can save time series of discharge, depth, concentration and sediment flux at any link-node pair in the channel network by specifying the cards listed in Table 23. If internal time series data are desired then the IN_HYD_LOCATION and OUT_HYD_LOCATION files must be specified in the project file.

Table 23 – Internal stream network output cards

The file specified by the IN_HYD_LOCATION card has a fixed format, which consists of an integer number equal to the number of points where hydrographs are to be saved (N), followed by N pairs of link and node numbers. For instance, if one wished to write out the hydrographs at 2 locations ( link 8, node 18) and (link 6 node 113), the contents of IN_HYD_LOCATION file would be:

	2
	8  18
	6  113

During the simulation, hydrograph ordinates would be written to the file specified with the OUT_HYD_LOCATION project file. The OUT_HYD_LOCATION file has (N+1) columns of data, where the first column contains the time in minutes since the beginning of the simulation for single events, the time in decimal years for continuous simulations, or the strict Julian date if the STRICT_JULIAN_DATE project card is used, and N columns of hydrograph ordinates. The hydrograph ordinates are written in the order they appear in the IN_HYD_LOCATION file. So, for example, an OUT_HYD_LOCATION file for the above example might appear as:

	0.000   0.000  0.000
	15.0    2.678  1.184
	30.0    5.988  3.714
	  •        •      •
	  •        •      •
 	  •        •      •

If depths are desired at the same locations specified in the IN_HYD_LOCATION file, then the OUT_DEP_LOCATION project card is used to specify the filename where depths (m default, ft if OUT_CFS is used) will be output.

If sediment flux at internal link-node locations is desired, the OUT_SED_LOC card is used to specify the filename where the sediment flux (m³/s) will be output. For sediment flux the link-node locations must be specified in a file identified with the IN_SED_LOC project card. To get time series data of in-stream sediment flux, the SOIL_EROSION project card must be specified along with the appropriate sediment erosion inputs.

Strictly, there are no limits on the number of link-node pairs at which time series ordinates can be saved. Practically, however, there may be limits due to the number of columns of data that may be imported into your data analysis/plotting software. Hydrograph ordinates are written every HYD_FREQ time steps.

To get output from reservoirs, put the LAKE_OUTPUT card in the project file along with the name of the file to write the lake output. The specified file will contain the elevation (m) and volume (m³) of each reservoir in the channel input .cif file in the order listed for each HYD_FREQ time period.

14.4.2 Time Series Output at Internal 2-D Grid Cell Locations

Time series data of soil moisture and groundwater level may be output at any cell in the 2-D grid network. This capability is provided to be able to compare to measured soil moisture and groundwater level data.

When saturated groundwater is being simulated observation, wells at any row (i) and column (j) in the 2-D grid can be specified in the OUT_WELL_LOCATION file. The OUT_WELL_LOCATION file contains the number of locations where groundwater levels are desired, followed by the ij location of each desired observation well. The file has the following format.

# observation wells (N)
i location of well 1 (i1)     j location of well 1 (j1)
i2        j2
i3        j3
etc.
iN-1      jN-1
iN        jN

Time series values of groundwater elevation (m) at every well location will be output every HYD_FREQ time steps to the file specified in the GW_WELL_LEVEL project card. This file will have one column for time and one column of groundwater surface elevation (m) for each well (N wells) listed in the OUT_WELL_LOCATION. The order of the output is the same as the order of the input.

Anytime infiltration is being calculated, soil moistures may be output at any cell in the soil column of any cell in the 2-D grid. To get time series data of soil moistures the IN_THETA_LOCATION card is used to provide the name of a file that contains the locations of cells where soil moisture output is desired. When any Green and Ampt approximation is used the location 2-D grid location, i row, j column, is specified in the IN_THETA_LOCATION file. For the various Green and Ampt approximations, soil moistures at the soil surface will be output. For Green and Ampt approximations the IN_THETA_LOCATION file has the following format.

The first line contains the number of 2-D grid locations where output is desired. Then for each 2-D grid cell where soil moisture output is desired the i location and j location are specified. This sequence is repeated for each 2-D grid location. This file has the following format:

# 2-D Grid Locations (N)
i1     j1    
i2     j2   
...
...
....
iN-1  jN-1   
iN     jN   

To get output from a given cell in the Richards’ equation solution, the location in the 2-D grid, i row, j column, and the location within that ij location, k^th cell, must be specified. The IN_THETA_LOCATION file has the following format. The first line contains the number of 2-D grid locations where output is desired and the maximum number of cells desired at any 2-D grid point. Then for each 2-D grid location desired, the i location, j location, and the number of vertical cells at that ij location are specified. This is followed by the vertical cell numbers (k) of each of the cells at the ij location. This sequence is repeated for each 2-D grid location. This file has the following format:

# 2-D Grid Locations (N)      Maximum number of cells at any location (M)
i1     j1     M1
vertical cell # 1 (k1)
k2
k3
etc.
kM1-1
kM1
i2     j2     M2
k1
etc.
kM2-1
kM2
etc.
iN     jN     MN
k1
etc.
kMN-1
kMN

For example, soil moistures are desired at 2 locations in the 2-D grid, at cell i = 40, j = 13 and at cell i = 24, j = 32. Soil moistures are desired at 5 depths at each of these ij locations, corresponding to vertical cell # (k) 25, 50, 71, 111, 170 at both sites. The required file would look like

2     5
40     13     5
25
50
71
111
170
24     32     5
25
50
71
111
170   

The soil moistures are then output to the file specified in the OUT_THETA_LOCATION file whose format is identical to that of the OUT_HYD_LOCATION file. For the Richards’ equation example above, the OUT_THETA_LOCATION file would contain 11 columns of data, one for the time and 10 for soil moistures at the specified locations, which will appear in the order requested in the IN_THETA_LOCATION file. For all Green and Ampt approximations each line will contain the time followed by one value of soil moisture, soil moisture at the surface, for each 2-D grid cell selected in the IN_THETA_LOCATION file, in the order requested in the IN_THETA_LOCATION file.

A list of all the current overland point output capability is listed below:

14.5 WMS Hydrograph File

GSSHA has the capability to write the outlet and the internal location hydrographs to a file format readable by WMS v7.0 and higher. This is specified by including the WMS_HYDRO project card and the name of the file to be written to. The WMS hydrograph file is generated post-process, at the end of a GSSHA run. The file has the following format:

GEISSHA_WMS_HYDROGRAPH_FILE
[Number of internal hydrographs {N}]
[start date (YYYYMMDD)]
[start time (2400)]
[time step interval, in seconds]
[number of hydrograph ordinates {M}]
[first node/link pair]
[second node/link pair]
…
[Nth node/link pair]
[outlet hydr. ord.–1]  [outlet hydr. ord.–2] …  [outlet hydr. ord.–10]
[outlet hydr. ord.–11] [outlet hydr. ord.–12] … [outlet hydr. ord.–20]
[outlet hydr. ord.–21] [outlet hydr. ord.–22] … [outlet hydr. ord.–30]
…
[outlet hydr. ord.–M-9] [outlet hydr. ord.–M-8] … [outlet hydr. ord.–M]
[internal hydr1 – 1]  [internal hydr1 – 2]  … [internal hydr1 – 10]
[internal hydr1 – 11] [internal hydr1 – 12] … [internal hydr1 – 20]
[internal hydr1 – 21] [internal hydr1 – 22] … [internal hydr1 – 30]
…
[internal hydr1 – M-9] [internal hydr1 – M-8] … [internal hydr1 – M]
[internal hydr2 – 1]  [internal hydr2 – 2]  … [internal hydr2 – 10]
[internal hydr2 – 11] [internal hydr2 – 12] … [internal hydr2 – 20]
[internal hydr2 – 21] [internal hydr2 – 22] … [internal hydr2 – 30]
…
[internal hydr2 – M-9] [internal hydr2 – M-8] … [internal hydr2 – M]
…
[internal hydrN – 1]  [internal hydrN – 2]  … [internal hydrN – 10]
[internal hydrN – 11] [internal hydrN – 12] … [internal hydrN – 20]
[internal hydrN – 21] [internal hydrN – 22] … [internal hydrN – 30]
…
[internal hydrN – M-9] [internal hydrN – M-8] … [internal hydrN – M]

The hydrograph ordinates are arranged 10 to a row, with each new hydrograph starting on a new line. If the number of hydrograph ordinates is not evenly divisible by 10 then the rest of the last line of ordinates for the hydrograph is left blank. The node-link pairs are arranged in the same order as the input and output hydrograph location files. The hydrograph data follow the same order, with the hydrograph data for the outlet being first and the internal location hydrographs following in order.

14.6 Time Series Maps

GSSHA can produce time-series maps of most spatially varied model output. In particular, GSSHA can write time series maps of spatially distributed rainfall, overland flow discharge, flow depths on the watershed, depths in the channel network, discharges in the channel network, cumulative infiltrated depth, infiltration rate, soil surface water content, groundwater head, contaminant concentration, volume of suspended sediment, maximum sediment flux, and net sediment flux. The project file cards required to write output time-series maps are listed in Section 3.11.3.

The MAP_TYPE project file card described in the above table determines the format of the output map. If the argument of MAP_TYPE is 0, then a series of GRASS ASCII maps are written, each with a different extension (e.g. depth.0, depth.1, depth.2 ...). These maps may be imported back into GRASS using the r.in.ascii command. Maps of types 1 and 2 are written in a generic WMS format. Maps of type 1 are written as ASCII files that may be read and processed by the user. All ASCII maps have the disadvantage of being up to twice the size of binary maps. Map type 3 is binary WMS format, which is the most compact, but cannot be directly read or edited. All maps are written every MAP_FREQ time steps.

Output time-series maps are very useful for obtaining an intuitive feel as to what is happening in the watershed at a given time. Using WMS to animate a series of maps provides the user with a moving time series of the output of concern. This allows the user to see how the variable’s spatial distribution progresses with time. Besides providing a means of visually analyzing the output, the output maps can be very helpful in spotting problems with the model. If fact, many years ago, the spatially varied maps of rainfall made obvious a problem in the inverse weighted distance rainfall distribution routine that may have otherwise gone by unnoticed.

In particular, the overland depth map is very useful for getting GSSHA to run properly. This map contains overland flow depths (m). The first map always corresponds to the initial condition and shows the water surface profile corresponding to the base flow discharge within the channel network. Similarly, the last depth map corresponds to the end-of-simulation time, or to the time at which the program finished abnormally. Abnormal program termination caused by oscillating depths may show negative depths in the overland plane, typically in a checkerboard fashion. This map output can be very informative to illustrate the location of flow problems such as pits, dams, or flat regions in the overland flow plane.

After calibration of GSSHA, depth and discharge maps are useful for flood plain determination, flow velocity estimation, and a host of other purposes. The spatially-varied output maps of soil surface water content and cumulative infiltrated depth are useful for analyzing the spatial variability of infiltration, and may be used as input for other surficial process models. The spatially varied rainfall map is illustrative for demonstrating storm and rainfall dynamics. These maps can be imported into GRASS and displayed as a film loop using the GRASS xganim program. WMS can be used to animate the time series of maps and build standard AVI files that can be played back by any type of animation software. Such animations can make a lasting image when inserted into otherwise vanilla PowerPoint presentations.