Template:GUM12

From Gsshawiki
Revision as of 18:54, 20 May 2008 by Eshaw (talk | contribs) (Template:GUM11 moved to Template:GUM12)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


The Mapping Table file has been designed for easy assignment of most of the parameters needed to model different processes in GSSHA. The Mapping Table consists of a short series of data tables, linked to a small number of integer-based index maps. The data tables are associated with different processes that can be simulated in GSSHA that require parameter values in every cell in the watershed, i.e. overland flow, infiltration, etc. From these inputs, GSSHA is able to internally create over two-dozen floating-point GRASS ASCII maps, which would otherwise have to be created by the user and specified with project cards. Consolidating the parameters into a series of tables and index maps reduces model construction time, organizes information, makes calibration easier, and allows easy parameter assignment for project alternatives and future scenarios. By using index maps as the patterns for assigning parameters, many different input parameters for a single cell can be assigned by changing the number in the index map.

Parameter values in the Mapping Table file are linked to the index maps through the identification numbers (IDs) used in the index maps. Data in the tables are arranged according to ID. The index maps contain the spatial distribution of the IDs over the watershed. To build the required input GRASS maps, GSSHA reads in the specified index maps, and replaces the index map ID values with the data corresponding to the ID from the appropriate table. This information is stored internally as an input floating-point map. Most watersheds can be simplified into a small set of parameters and a few index maps, but even large and complex watershed models can be quickly constructed using the Mapping Table file. The program WMS V6.1 and later releases, is designed to work with the Mapping Table file and parameters are assigned with the Mapping Table file when using WMS V6.1. When using WMS 6.1 and higher, WMS will place the MAPPING_TABLE card in the project file when one or more processes requiring distributed parameter values are chosen to be modeled. The MAPPING_TABLE project card, followed by the name of the Mapping Table file, informs GSSHA to obtain parameters needed for process simulations from the Mapping Table file, and that detailed ASCII maps or uniform values of parameters will not be used.

The following is a description of the overall structure of the Mapping Table file, followed by a detailed description of the structure of the index maps, the structure and organization of the various tables in the Mapping Table file, and a description of how to link the index maps to the tables in the Mapping Table file. Finally, a summary of the different sections of the Mapping Table file is given, as well an example of the Mapping Table file.

12.1 File Description

The Mapping Table file has three main sections: header, index map declaration lines, and data tables. These three sections of the file are arranged in the following order:

Header
Index Map Declaration Lines
Data Tables

The header is a line that specifies the type of file being read in, in this case a Mapping Table file. The index map declaration lines specify the index maps to use with the following data tables. The index map names are then referenced by the data tables that follow. The data tables link a set of input parameters to a named index map.

12.1.1 Header

The first section of the Mapping Table file is a header line, or a line that specifies the type of file being read by GSSHA. This must be the first line in the file. The line has the following identifier: GEISSHA_INDEX_MAP_TABLES, which appears alone on the first line of the Mapping Table, i.e.

GSSHA_INDEX_MAP_TABLES

This line indicates that the data that follows has been arranged into the Mapping Table format, as described in this document. This header is used to verify that the file being read in by GSSHA has been set up as a Mapping Table file. WMS v6.1 and higher automatically places this line in the Mapping Table file when WMS is used to describe the processes in the GSSHA model.

12.1.2 Index Map Declaration Lines

The second section of the Mapping Table file is a series of index map declaration lines. These lines are used to specify index maps that will be linked to the tables in the Mapping Table file. An index map consists of an index map name and an index map filename. The index map declaration lines associate the filename of a file in the format of an index map with an index map name. The index map is then referenced throughout the Mapping Table file by its name, not by the filename. Each index map name must be unique, though the index map filename do not necessarily have to be unique. That is, a single map could be assigned multiple names in the Mapping Table. WMS automatically adds the suffix idx to the filename of all index maps. The index map declaration lines follow the format:

INDEX_MAP      filename      "Index map name"

For example:

INDEX_MAP      soil1.idx      "Soils map of North Fork"

The amount of spacing between the three specifiers (i.e. INDEX_MAP, filename, “Index map name”) is not important; but at least one white-space character (i.e. tab, space) must appear between inputs. The index map name MUST be in quotes. There is no limit to the number of index maps that may be specified. Index maps named in the index map declaration lines need not be referenced by any tables in the Mapping Table file. An index map filename may be associated with multiple index map names, but each Index map name must be unique. All index map names referenced in the Mapping Table file must have an index map declaration line that has the exact same index map name.

12.1.3 Data Tables

Following the index map declaration lines come a series of tables. For each process to be simulated, data tables are used to assign the distributed parameters needed to model the process. The tables are identified by a unique name, TABLE_NAME, followed by the associated Index map name, in quotes. The next line must start with the identifier NUM_IDS followed by the number of IDs defined for the table. For the Richards Havercamp and Richards Brooks tables, the next line must start with the identifier MAX_NUMBER_CELLS followed by an integer number. For all tables, the next line is a header or descriptive line. This line is ignored by GSSHA. Following the descriptive line comes the listing of the IDs. The IDs must be an integer value greater than zero. The first six spaces of the line are allotted for the ID number. The IDs need not be in numerical order, or even numerically sequential. Each ID is followed by an 80-character description and the appropriate number of floating point values for the table. The following is a basic format for the data tables (the descriptions are truncated for display purposes):

TABLE_NAME  "Index map name"
NUM_IDS ##
MAX_NUMBER_CELLS  ###  (only if table is of a Richards’ equation type)
ID DESCRIPTION VALUE DESCRIPTORS …
## ID description #####  #####  …  #####
## ID description #####  #####  …  #####
   
## ID description #####  #####  …  #####


For example, a data table for overland roughness might look like (the descriptions have been shortened for display purposes):

ROUGHNESS “roughness map”
NUM_IDS 4
ID DESCRIPTION ROUGHNESS
1 Corn Fields 0.3000
2 Soybean Fields 0.3300
3 Empty Fields 0.2500
7 Natural Vegetation 0.2700


The first line is the table is the table identifier, ROUGHNESS. GSSHA then expects that the table contains the values needed to create the internal map of overland roughness floating-point values. Following the table identifier is the name of the index map associated with the table. In this example, “roughness map” is the index map associated with the table. The next line contains the identifier NUM_IDS that declares how many IDs are in the table. In this example, four IDs are declared, numbered 1, 2, 3 and 7. ID 1 corresponds to a roughness of 0.3000, ID 2 corresponds to a roughness of 0.3300, etc. The descriptions following the IDs must be present, and must be 80 characters, but are purely for user identification. The descriptions are not used by GSSHA. The line following the NUM_IDS line, or the line following MAX_NUMBER_CELLS in the Richards’ equations tables, is discarded by GSSHA. It may contain any sort of text desired but it is usually used to describe the parameters set up in the data table.

The name of the index map associated with the table is “roughness map”. There must be a line for this map in the index map declaration lines, i.e.


INDEX_MAP roughness.idx “roughness map”


The file roughness.idx cannot contain integer values, IDs, other than 1, 2, 3 or 7, and 0, which is used for the inactive regions of the grid. See MASK_FILE. The index map file does not have to refer to all of these IDs. If the index map file roughness.idx only references IDs 1 and 7, then only roughness values of 0.3000 and 0.2700 will be in the final roughness map internal to GSSHA.

12.1.4 File Format

The Mapping Table file follows the following basic format:

GEISSHA_INDEX_MAP_TABLES
INDEX_MAP filename.idx "Index map name"
INDEX_MAP filename.idx "Index map name"
etc.
INDEX_MAP filename.idx "Index map name"
TABLE_NAME  "Index map name"
NUM_IDS ##
ID DESCRIPTION VALUE DESCRIPTORS …
## ID description ##### ##### … #####
## ID description ##### ##### … #####
etc.
## ID description ##### ##### … #####
TABLE_NAME  "Index map name"
NUM_IDS ##
ID DESCRIPTION VALUE DESCRIPTORS …
## ID description ##### ##### … #####
## ID description ##### ##### … #####
etc.
## ID description ##### ##### … #####
TABLE_NAME  "Index map name"
NUM_IDS ##
ID DESCRIPTION VALUE DESCRIPTORS …
## ID description ##### ##### … #####
## ID description ##### ##### … #####
etc.
## ID description ##### ##### … #####


An example file can be found in section 11.5. Note that there may not be blank lines between the tables, between the index map declaration lines, between the header and the index map declaration lines or even between the index map declaration lines and the data tables. Text and blank lines after the data table section are permitted.

12.2 Index Maps

An index map is a GRASS ASCII file that contains integer values in each grid cell. The data should follow the same shape or pattern as the WATERSHED_MASK file because each cell of the index map will be used to supply data for the corresponding watershed cell. The data cells outside of the watershed should contain the value 0. All data cells inside the watershed should be of integer value greater than or equal to 1. These values are ID numbers, and will correspond to IDs from a table in the Mapping Table file. It is from the index maps that the final structure and mapping of the data in the tables takes place. Developing good index maps is a key part in building a model that is easy to work with and modify.

An example of a watershed mask and an index map file:


Watershed Mask File

north: 150.00
south: 50.00
east: 150.00
west: 50.00
rows: 10
cols: 10
0 0 0 1 0 0 0 0 0 0
1 1 1 1 0 0 0 0 0 0
0 0 1 1 1 1 1 1 0 0
0 0 0 1 1 1 1 0 0 0
0 0 1 1 1 1 1 0 0 0
0 0 0 1 1 1 1 0 0 0
0 0 0 1 1 1 1 0 0 0
0 0 1 1 1 1 1 1 0 0
0 0 0 1 1 1 1 1 1 0
0 0 0 0 0 0 0 1 1 0
  Index Map File

north: 150.00
south: 50.00
east: 150.00
west: 50.00
rows: 10
cols: 10
0 0 0 1 0 0 0 0 0 0
1 1 1 1 0 0 0 0 0 0
0 0 1 1 1 1 1 1 0 0
0 0 0 2 2 2 1 0 0 0
0 0 1 2 2 1 1 0 0 0
0 0 0 1 2 1 1 0 0 0
0 0 0 1 1 1 1 0 0 0
0 0 1 1 3 3 3 1 0 0
0 0 0 1 1 3 3 3 1 0
0 0 0 0 0 0 0 1 1 0


This index map has three IDs, 1, 2 and 3. Any table in the Mapping Table file that uses this index map should at least have the IDs 1, 2 and 3. The table may have other IDs, but the associated values will not be in the final floating-point map generated internally by GSSHA. A table may refer to more IDs than an index map references, but an index map cannot contain the IDs that are not listed in the associated table. Allowing IDs in the tables not associated with the index maps is useful in running different scenarios; for example, pre and post project conditions. To change the model scenario, only the name of a different index map need be assigned to the table in the Mapping Table file.

Each index map used in the Mapping Table file is identified by its index map name, which is different than the index map filename. The index map filename is the name of the file on disk, referenced by the operating system. The index map name is an internal descriptive name used in the Mapping Table file to identify which index map is assigned to which tables. The index map filenames and the associated index map names are associated with each other at the beginning of the file in the index map declaration lines. These index map declaration lines follow the first line of the file, which identifies the file as a Mapping Table file.

12.3 Mapping Tables

The Mapping Tables consist of an index map name, and a set of IDs, each ID having an associated set of parameter values. GSSHA reads in the integer-based index map, and then builds the floating-point-based map by looking up the ID for each cell and inserting the associated floating-point value from the table. GSSHA expects each ID to have the correct number of values, in the correct order. The number of values and the order of them are given in the following table. The Mapping Table file does not need to contain all of the tables listed in the following table.

Table Name # Values Parameter Units
ROUGHNESS 1 Roughness (n) none
ROUGH_EXP 1 Depth varying roughness exponent none
INTERCEPTION 2 Storage Capacity (a) mm
Interception coefficient (b) none
RETENTION 1 Retention depth (dret) mm
GREEN_AMPT_INFILTRATION 7 Saturated hydraulic conductivity (Ks) cm/hr
Wetting front suction head (ψƒ) cm
Porosity (θs) m3/m3
Pore distribution index (λ) m3/m3
Residual water content (θr) m3/m3
Field Capacity (θfc) m3/m3
Wilting point (θwp) m3/m3
GREEN_AMPT_INITIAL_SOIL_MOISTURE 1 Initial soil moisture (θi) m3/m3
RICHARDS_EQN_INFILTRATION_BROOKS

3 sets of values for each ID
1 set per line

10 x 3 Ks cm/hr
θs m3/m3
θr m3/m3
θi m3/m3
θwp m3/m3
θfc m3/m3
Layer thickness (tL) cm
λ none
Bubbling pressure (ψb) cm
Cell size (Δz) cm
RICHARDS_EQN_INFILTRATION_HAVERCAMP

3 sets of values for each ID
1 set per line

12 x 3 Ks cm/hr
θs m3/m3
θr m3/m3
θi m3/m3
θwp m3/m3
θfc m3/m3
Layer depth cm
Havercamp factor α none
Havercamp factor Β none
Havercamp factor A none
Havercamp factor B none
Δz cm
EVAPOTRANSPIRATION 5 Albedo none
Wilting point (moisture content)
Vegetation height m
Transmission coefficient none
Canopy Resistance s/m
WELL_TABLE 2 IsDynamic 0 or 1
pumping rate (if static) or time series index (if dynamic) cms
OVERLAND_BOUNDARY 2 Boundary Type
0 - Regular Cell
1 - Constant Slope
2 - Constant Specified Head
3 - Time Variable Specified Head
4 - Specified hydrograph (cfs)
5 - Specified hydrograph (cms)
Type 0 - 0.0
Type 1 - slope
Type 2 - head (m)
Type 3, 4, or 5 - time series index
Parameter depends on the type specified by the first parameter See below
TIME_SERIES_INDEX 1 "Time Series Name" none
GROUNDWATER 2 Hydraulic Conductivity cm/hour
Porosity m3/m3
GROUNDWATER_BOUNDARY 1 Boundary Value none
AREA_REDUCTION 1 Impervious area fraction [0.0 - 1.0]
WETLAND_PROPERTIES 7 Initial water depth cm
Retention depth (Darcy flow depth) cm
Retention hydraulic conductivity m/day
Vegetation height cm
Vegetation hydraulic conductivity m/day
Vegetation Manning's N none
Burn-in depth cm
OVR_FLOW_BLOCK 5 Area reduction Fraction (0-1)
Upper (North) face blockage Fraction (0-1)
Right (East) face blockage Fraction (0-1)
Down (South) face blockage Fraction (0-1)
Left (West) face blockage Fraction (0-1)
BMPS 10+ BMP Type <number>
Inflow Type Fraction (0-1)
Outflow Type Fraction (0-1)
Area m2
Retention depth mm
Soil Saturated Hydraulic Conductivity cm/hr
Inflow variable (based on BMP type) <number>
Outflow variable (based on BMP type) <number>
Soil Depth meters
TSS Treatment Efficiency Fraction (0-1)
Contaminant Treatment Efficiency (repeat for each contaminant Fraction (0-1)


The following sections outline the table names, number of parameters, order and type of the parameters, and the table format. Also included is an example table. In the example tables the descriptions have been shortened for display purposes. In all fields of the table, except the ID and descriptions fields, the amount of spacing between the identifiers does not matter. The format of the ID lines is given after the Soil Erosion Factors table is described.

12.3.1 Roughness

The roughness table specifies Manning/Strickler n values for the overland flow domain. This table is always present since overland flow is always running. Roughness values are usually based on land use values.
See also Parameter Line Format

Table Name # Values Parameter Units Typical Range
ROUGHNESS 1 Surface Roughness (n) none 0.02 – 0.5


Table Format
ROUGHNESS "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.###
ID #2 Description 1 Description 2 ###.###
etc.
ID #N Description 1 Description 2 ###.###



Example Table

ROUGHNESS "roughness map"
NUM_IDS 2
ID    DESCRIPTION1                            DESCRIPTION2                              SURF_ROUGH
1     cornfield                               Soil type independent                      0.24000
2     urban area                              Soil type independent                      0.19000
3     Forest                                  Soil type independant                      0.27000


12.3.2 Roughness Exponent

The roughness exponent table specifies exponent values for depth-varying Manning/Strickler n values for the overland flow domain. This table is for the "b" values in the equation n=n0^(-bh). Values vary from 0.0 (non-depth-varying) to 1.0.
See also Parameter Line Format

Table Name # Values Parameter Units Typical Range
ROUGH_EXP 1 Surface Roughness Exponent (b) none 0.00 – 1.0


Table Format
ROUGH_EXP "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.###
ID #2 Description 1 Description 2 ###.###
etc.
ID #N Description 1 Description 2 ###.###



Example Table

ROUGH_EXP "roughness map"
NUM_IDS 2
ID    DESCRIPTION1                            DESCRIPTION2                               ROUGH_EXP
1     cornfield                               Soil type independent                      0.5000
2     urban area                              Soil type independent                      0.43000
3     Forest                                  Soil type independant                      0.62000

12.3.3 Interception

The interception table specifies parameters for water being abstracted from the rainfall by the vegetation. This table is usually based on a vegetation or land cover map.
See also Parameter Line Format


Table Name # Values Parameter Units Typical Range
INTERCEPTION 2 Storage capacity mm 0.0 - ?
Interception Coefficient none 0.0 – 1.0


Table Format
INTERCEPTION "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.### ###.###
ID #2 Description 1 Description 2 ###.### ###.###
ID #N Description 1 Description 2 ###.### ###.###



Example Table

INTERCEPTION "interception map"
NUM_IDS 3
ID    DESCRIPTION1                            DESCRIPTION2                               STOR_CAPY  INTER_COEF
1     Deciduous Trees                         Independent of soils                        1.143    0.245000
2     Coniferous Trees                        Independent of soils                        0.984    0.102000
3     Corn                                    Independent of soils                        1.052    0.045000

12.3.4 Retention

This table describes the retention depth used in the overland flow model. It is usually based on land use.
See also Parameter Line Format


Table Name # Values Parameter Units Typical Range
RETENTION 1 Retention depth (dret) mm 1.0 – 5.0


Table Format
RETENTION "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.###
ID #2 Description 1 Description 2 ###.###
ID #N Description 1 Description 2 ###.###



Example Table

RETENTION "retention map"
NUM_IDS 3
ID    DESCRIPTION1                            DESCRIPTION2                            RETENTION_DEPTH
1     Forest                                  Soil type independent                       1.800000
2     Residential                             Soil type independent                       0.800000
3     Corn                                    Soil type independent                       2.300000

12.3.5 Green & Ampt Infiltration

This table is used to describe the soil properties for use with the Green and Ampt or Green and Ampt with Redistribution infiltration methods. Both of those methods also require that the GREEN_AMPT_INITIAL_SOIL_MOISTURE table also be defined. This table is usually defined from a combination of soil type and land use maps.
See also Parameter Line Format


Table Name # Values Parameter Units Typical Range
GREEN_AMPT_INFILTRATION 7 Ks (Saturated Hydraulic Conductivity) cm/hr 0.01 – 2.0
ψf (Capillary Suction Head) ) cm 10.0 – 100.0
θs (Porosity) m3/m3 0.25 – 0.60
λ (Pore Index Value) none 1.0 – 4.0
θr (Residual Saturation) m3/m3 0.01 – 0.1
θf (Field Capacity) m3/m3 0.01 – 0.3
θwp (Wilting Point) none 0.03 – 0.25



Table Format
GREEN_AMPT_INFILTRATION "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.### ###.### ###.### ###.### ###.### ###.### ###.###
ID #2 Description 1 Description 2 ###.### ###.### ###.### ###.### ###.### ###.### ###.###
ID #N Description 1 Description 2 ###.### ###.### ###.### ###.### ###.### ###.### ###.###



Example Table

GREEN_AMPT_INFILTRATION “green and ampt infil map”
NUM_IDS 2
ID    DESCRIPTION1                            DESCRIPTION2                               HYDR_COND  CAPIL_HEAD    POROSITY  PORE_INDEX   RESID_SAT FIELD_CAPACITY
1     Row Crop                                SL                                          0.048342    8.34         0.501000    0.234000    0.015000    0.3300
2     Row Crop                                CL                                          0.026000    12.4         0.485000    0.257000    0.012000    0.2700

12.3.6 Initial Soil Moisture

The initial soil moisture table is required for either of the Green and Ampt infiltration methods. This table is usually based on a combination of soil type and vegetation or land cover types.
See also Parameter Line Format


Table Name # Values Parameter Units Range
GREEN_AMPT_INITIAL_SOIL_MOISTURE θi 1 m3/m3 θrs


Table Format
GREEN_AMPT_INITIAL_SOIL_MOISTURE "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.###
ID #2 Description 1 Description 2 ###.###
ID #N Description 1 Description 2 ###.###



Example Table

GREEN_AMPT_INITIAL_SOIL_MOISTURE "green and ampt moisture map"
NUM_IDS 2
ID    DESCRIPTION1                            DESCRIPTION2                            SOIL_MOISTURE
1     Row Crops                               SL                                          0.250000
2     Row Crops                               CL                                          0.200000

12.3.7 Richards’ Equation, Brooks Option

The Richards' Equation infiltration methods are the most rigorous that GSSHA has to offer. These methods have three defined layers and thus have three lines of parameters for each index value; the top layer is the first line, the bottom layer is the third line. The parameter sets all begin at character #87 on the line (see also Parameter Line Format) but for the 2nd and 3rd lines the ID and description spaces are blank (GSSHA ignores whatever is there.) The maximum number of cells parameter should be bigger than the sum of the depth of each layer divided by the delta Z of that layer.

Table Name # Values Parameter Units Typical Range
RICHARDS_EQN_INFILTRATION_BROOKS

3 sets of values for each ID,
one set of values per line for each soil layer
10 x 3 Ks cm/hr 0.05 – 23.5
θs (Saturated hydraulic conductivity) m3/m3 0.4 – 0.55
θr (Residual saturation) m3/m3 0.01 – 0.1
θi (Initial soil moisture) m3/m3 θrs
θwp (Wilting point) m3/m3 0.03 – 0.25
θfc (Field capacity) m3/m3 0.25 - 0.35
d (total layer depth) cm NA
λ none 1.0 – 4.0
ψb (Bubbling pressure) cm 5.0 – 100.0
Δz (Numerical solver layer depth) cm 0.1 – 10.0


Table Format
RICHARDS_EQN_INFILTRATION_BROOKS "Index Map Name"
NUM_IDS ####
MAX_NUMBER_CELLS ####
Text Line
ID #1 Description 1 Description 2 ###   ###   ###   ###   ###   ###   ###   ###   ###  
  ###   ###   ###   ###   ###   ###   ###   ###   ###  
###   ###   ###   ###   ###   ###   ###   ###   ###  
ID #2 Description 1 Description 2 ###   ###   ###   ###   ###   ###   ###   ###   ###  
  ###   ###   ###   ###   ###   ###   ###   ###   ###  
###   ###   ###   ###   ###   ###   ###   ###   ###  
ID #N Description 1 Description 2 ###   ###   ###   ###   ###   ###   ###   ###   ###  
  ###   ###   ###   ###   ###   ###   ###   ###   ###  
###   ###   ###   ###   ###   ###   ###   ###   ###  

Example Table

RICHARDS_EQN_INFILTRATION_BROOKS  "map name"
NUM_IDS 2
MAX_NUMBER_CELLS 165
ID    DESCRIPTION1                            DESCRIPTION2                                HYD_COND    POROSITY   RESID_SAT  SOIL_MOIST  WILTING_PT FIELD_CAP  DEPTH      LAMBDA   BUB_PRESS DELTA_Z
1     Clay                                                                                 0.1        0.5        0.1        0.25        0.15       0.35       10.0       3.0      -50.0     1.0
                                                                                           0.1        0.5        0.1        0.25        0.15       0.35       20.0       3.0      -50.0     2.0
                                                                                           0.1        0.5        0.1        0.25        0.15       0.35       50.0       3.0      -50.0     5.0
2     Silty Clay                                                                           0.2        0.48       0.09       0.25        0.15       0.35       10.0       2.7      -35.0     1.0
                                                                                           0.2        0.48       0.09       0.25        0.15       0.35       20.0       2.7      -35.0     2.0
                                                                                           0.2        0.48       0.09       0.25        0.15       0.35       50.0       2.7      -35.0     5.0

12.3.8 Richards’ Equation, Havercamp Option

Like the Brooks option the Havercamp option has three soil layers. The first line of each parameter set is for the top layer and the third line the bottom layer. The maximum number of cells parameter should be bigger than the sum of the depth of each layer divided by the delta Z of that layer. See also Parameter Line Format and the Brooks Option.

Table Name # Values Parameter Units Range
RICHARDS_EQN_INFILTRATION_HAVERCAMP

3 sets of values for each ID
One set of values per line for each soil layer
12 x 3 Ks cm/hr 0.05 – 23.5
θs m3/m3 0.4 – 0.55
θr m3/m3 0.01 – 0.1
θi m3/m3 θrs
θwp m3/m3 0.03 – 0.25
θfc m3/m3 0.25 – 0.35
dL cm NA
α none fit to curve
β none fit to curve
A none fit to curve
B none fit to curve
Δz cm 0.1 – 10.0


Table Format
RICHARDS_EQN_INFILTRATION_HAVERCAMP "Index Map Name"
NUM_IDS ####
MAX_NUMBER_CELLS ####
Text Line
ID #1 Description 1 Description 2 ###   ###   ###   ###   ###   ###   ###   ###   ###   ###   ###  
  ###   ###   ###   ###   ###   ###   ###   ###   ###   ###   ###  
###   ###   ###   ###   ###   ###   ###   ###   ###   ###   ###  
ID #2 Description 1 Description 2 ###   ###   ###   ###   ###   ###   ###   ###   ###   ###   ###  
  ###   ###   ###   ###   ###   ###   ###   ###   ###   ###   ###  
###   ###   ###   ###   ###   ###   ###   ###   ###   ###   ###  
ID #N Description 1 Description 2 ###   ###   ###   ###   ###   ###   ###   ###   ###   ###   ###  
  ###   ###   ###   ###   ###   ###   ###   ###   ###   ###   ###  
###   ###   ###   ###   ###   ###   ###   ###   ###   ###   ###  

Example Table

RICHARDS_EQN_INFILTRATION_HAVERCAMP "map name"
NUM_IDS 2
MAX_NUMBER_CELLS 165
ID    DESCRIPTION1                            DESCRIPTION2                                HYD_COND POROSITY RESID_SAT SOIL_MOIST WILTING_PT FIELD_CAP  DEPTH Alpha Beta   A    B   DELTA_Z
1    Clay                                                                                  0.1     0.5      0.09      0.25       0.25       0.35       20    80    1.3    125  1.8 1.0
                                                                                           0.1     0.5      0.09      0.35       0.25       0.25       30    80    1.3    125  1.8 2.0
                                                                                           0.1     0.5      0.09      0.45       0.25       0.35       50    80    1.3    125  1.8 5.0
2    Sand                                                                                  1.0     0.4      0.01      0.25       0.03       0.25       10    35    4.0    1175 4.7 1.0
                                                                                           1.0     0.4      0.01      0.35       0.03       0.25       40    35    4.0    1175 4.7 2.0
                                                                                           1.0     0.4      0.01      0.35       0.03       0.25       50    35    4.0    1175 4.7 5.0

12.3.9 Evapo-transpiration

This table holds the parameters for the evapo-transpiration routine. See also Parameter Line Format and the Computation of evaporation and evapo-transpiration

Table Name # Values Parameter Units Typical Range
EVAPO-TRANSPIRATION 4 Albedo none 0.0 – 1.0
Vegetation Height m 0.1 – 10.0
Vertical Radiation Coefficient none 0.0 – 1.0
Canopy Resistance s/m 0.0 – 500.0


Table Format
EVAPOTRANSPIRATION "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.### ###.### ###.### ###.### ###.###
ID #2 Description 1 Description 2 ###.### ###.### ###.### ###.### ###.###
ID #N Description 1 Description 2 ###.### ###.### ###.### ###.### ###.###

Example table

EVAPOTRANSPIRATION "et map"
NUM_IDS 2
ID    DESCRIPTION1                            DESCRIPTION2                                  ALBEDO  WILTING_PT  VEG_HIEGHT  V_RAD_COEF CANOPY_RESIST
1     Row Crops                                                                           0.100000    0.120000    0.500000    0.100000   45.000000
2     Forest                                                                              0.200000    0.080000    7.500000    0.200000   200.00000

12.3.10 Wells

The well table uses the standard line format (see Parameter Line Format) but also uses the time series index table.

The Is Dynamic? parameter is a flag to indicate if the flow rate is static (0) or dynamic (1). If the flow rate is static then the value is the pumping/injection rate. If it is dynamic then the value should be the ID of a time series as specified in the time series index table. The well IDs are used in the map, just like other tables, but map IDs of 0 are ignored.

Table Name # Values Parameter Units Typical Range
WELL_TABLE 2 Is Dynamic? none 1=yes, 0=no
Value cms or none -10000..10000 or Time Series ID


Table Format
WELL_TABLE "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 # ###.###
ID #2 Description 1 Description 2 # ###.###
ID #N Description 1 Description 2 # ###.###


Example table


TIME_SERIES_INDEX ""
NUM_IDS 1
1     "Municipal well #4"

WELL_TABLE "well map"
NUM_IDS 2
ID    DESCRIPTION1                            DESCRIPTION2                                Is_Dynamic? Value
1     Static well                                                                         0           2.53 
2     Dynamic well                                                                        1           1   

In the example above, since well #1 is static, the value is the pumping rate. Since well #2 is dynamic, the value (1) refers to the ID in the time series index (1="Municipal well #4").

12.3.11 Overland Boundaries

The overland boundaries table works in conjunction with the time series index table. See also Parameter Line Format and Overland Boundaries.


Table Name # Values Parameter Units Typical Range
OVERLAND_BOUNDARY 2 Boundary Type none 0=none
1=Specified slope
2=Constant specified head
3=Time variable specified head
4=Hydrograph source (cfs)
5=Hydrgraph source (cms)
Boundary Value none for type 0, 1, and 3
m above sea level for type 2
cfs for type 3
cms for type 4
Type 0: 0.00
Type 1: 0.0000001 - 0.01
Type 2: 0.0 .. 5.0 above cell elevations
Type 3: IDs in time series index, heads between -1.0..20.0 above cell elevation.
Type 4: IDs in the time series index, input flow rates in cubic feet per second (cfs)
Type 5: IDs in the time series index, input flow rates in cubic meters per second (cms)


Table Format
OVERLAND_BOUNDARY "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 # ###.###
ID #2 Description 1 Description 2 # ###.###
ID #N Description 1 Description 2 # ###.###


Example table


TIME_SERIES_INDEX ""
NUM_IDS 2
1     "Municipal well #4"
2     "Storm surge"

OVERLAND_BOUNDARY "bdy"
NUM_IDS 3
ID    DESCRIPTION1                            DESCRIPTION2                              BDY_TYPE   BDY_VAL
1     specified slope                                                                     1        0.001000
2     specified head                                                                      3        2
3     none                                                                                0        0.0

In the example above, ID 1 is a constant specified slope (for allowing the water to drain off the grid in a location other than the outlet cell), ID 2 is a time-variable specified head and the boundary value of 2 is the ID in the time series index (2="Storm surge"). ID 3 is used in the grid where non-boundary-condition cells are located.

12.3.12 Time Series Index

The time series index table is a special table in that it is used by other tables as a means of associating an ID with a time series name, rather than specifying parameters for a process. This table does not refer to an index map, nor does it have description fields as the other tables do.


Example Table

TIME_SERIES_INDEX ""
NUM_IDS 2
ID   Time series name...
1    "Municipal well #4"
2    "Storm surge"

12.3.13 Groundwater

The groundwater table is used to specify spatially variable values of hydraulic conductivity and porosity without creating a continuous map.

See also Parameter Line Format


Table Name # Values Parameter Units Typical Range
GROUNDWATER 2 Hydraulic Conductivity cm/hr <math>10^{-9}</math> .. <math>10^4</math>
Porosity none 0.001 – 0.5


Table Format
GROUNDWATER "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.### ###.###
ID #2 Description 1 Description 2 ###.### ###.###
ID #N Description 1 Description 2 ###.### ###.###



Example Table

GROUNDWATER "gw properties map"
NUM_IDS 2
ID    DESCRIPTION1                            DESCRIPTION2                               HYD_COND  POROSITY
1     Karst region                                                                        120.0    0.10000
2     Glacial till                                                                        0.0036   0.20000

12.3.14 Groundwater Boundary

The groundwater boundary table maps ID values to groundwater boundary codes. See also Parameter Line Format and groundwater boundary conditions.

Table Name # Values Parameter Units Typical Range
GROUNDWATER_BOUNDARY 1 Boundary value none 0-7


Table Format
GROUNDWATER_BOUNDARY "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.###
ID #2 Description 1 Description 2 ###.###
ID #N Description 1 Description 2 ###.###



Example Table

GROUNDWATER_BOUNDARY "gw boundary map"
NUM_IDS 3
ID    DESCRIPTION1                            DESCRIPTION2                                BOUNDARY_VALUE
1     regular cell                                                                          1
2     static head                                                                           2
3     dynamic well                                                                          3
4     flux river                                                                            4
5     head river                                                                            5
6     static well                                                                           6
7     lake                                                                                  7

Of course, the index map in this example is simple enough to also be the boundary map as well. Wells are better set up using the well table rather than here.

12.3.15 Area Reduction Factor

The area reduction factor reduces the potential infiltration by the specified fraction. See also Parameter Line Format

Table Name # Values Parameter Units Typical Range
AREA_REDUCTION 1 Impervious area fraction none 0.0 – 1.0


Table Format
AREA_REDUCTION "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.###
ID #2 Description 1 Description 2 ###.###
ID #N Description 1 Description 2 ###.###



Example Table

AREA_REDUCTION "impervious area map"
NUM_IDS 3
ID    DESCRIPTION1                            DESCRIPTION2                                IMPERVIOUS_AREA
1     High-density urban                                                                  0.800000
2     low-density urban                                                                   0.300000
3     natural area                                                                        0.000000

12.3.16 Wetlands

The wetlands table has the parameters for the overland flow wetland process. Currently limited to <300 unique wetlands. The wetland map is similar in nature to the well map; the areas that don't have wetlands should be marked as having ID 0. See also Parameter Line Format


Table Name # Values Parameter Units Typical Range
WETLAND_PROPERTIES 7 Initial Depth cm 0.1 - 600.0
Retention Depth cm 1.0 - 500.0
Retention Hydraulic Conductivity m/day 0.1 - 1000.0
Vegetation Height cm 5.0 - 200.0
Vegetation Hydraulic Conductivity m/day 0.1 - 1000.0
Vegetation Manning N none 0.02 – 0.5
Burn In Depth cm 0.0 – 500.0


Table Format
WETLAND_PROPERTIES "Index Map Name"
NUM_IDS ####
Text Line
ID #1 Description 1 Description 2 ###.### ###.### ###.### ###.### ###.### ###.### ###.###
ID #2 Description 1 Description 2 ###.### ###.### ###.### ###.### ###.### ###.### ###.###
ID #N Description 1 Description 2 ###.### ###.### ###.### ###.### ###.### ###.### ###.###

Example table

WETLAND_PROPERTIES "wetland map"
NUM_IDS 2
ID    DESCRIPTION1                            DESCRIPTION2                                INIT_DEPTH  RET_DEPTH  RET_HYD_COND  VEG_HEIGHT VEG_HYD_COND VEG_N  BURN_IN_DEPTH
1     Lower Wetland                                                                       65.0        50.0       20.0          1.0        120.0        0.35   50.0
2     Upper Wetland                                                                       75.0        100.0      110.0         1.5        200.0        0.35   75.0

12.3.17 Flow Blockage

The overland flow blockage table specifies how much of each cell face does not communicate with the neighboring cell.


Table Name # Values Parameter Units Typical Range
OVR_FLOW_BLOCK 5 Area Reduction none (fraction of area) 0.0 - 1.0
Upper (north) face flow blockage none (fraction of cell edge length) 0.0 - 1.0
Right (east) face flow blockage none (fraction of cell edge length) 0.0 - 1.0
Lower (south) face flow blockage none (fraction of cell edge length) 0.0 - 1.0
Left (west) face flow blockage none (fraction of cell edge length) 0.0 - 1.0

12.3.18 Parameter Line Format

For each of the mapping tables, except for the time series index table and the sediment properties table, the parameter lines follow a mixed fixed/free format. The ID number portion of the line must be 6 characters, and each of the two descriptions must be 40 characters. After this (starting at character 87) the parameter values can be spaced as desired. The description fields are generally used to describe the land use and soil type that each of the IDs refers to so that the file is human-readable. These fields can contain any desired information, however, as GSSHA simply ignores them. The same applies for the text line above the parameter lines; this is for your use to help in identifying what goes where or whatever else you want to write there.

[ID  ][Description 1                         ][Description 2                         ]Parameter values...



12.4 ID Line Format

The ID lines consist of three parts, the ID number, the description, and the parameter values. The main difference between the ID lines for the non-Richards’ equation tables and the ID lines for the Richards’ equation tables is that the Richards equations tables assign parameters for three different soil layers, each layer having its’ own parameter set. In the ID lines for the Richards’ equations, the two lines that do not begin with the ID and the description can have up to 86 characters. For each ID line, the ID must fill the first six spaces. There may be, and usually is, white space after the ID number, to fill the remaining six spaces. Likewise, the description must be 80 characters long. There may be as much white space in the 80 characters as needed. The 80 characters following the ID are only for the description of the ID and are not read by GSSHA. The 80-character length is mainly for the program WMS, which outputs two 40-character descriptions. The ID and description are followed by a number of parameter values dependent on the table type. All values for a table must be present, even if they are not used in a particular model. When unused values must be assigned, any valid floating point number, including 0.0, may be input. The amount of spacing between the values is not important, but it is usually visually helpful to align the parameters.


Format of ID lines (Non-Richards Equation Tables)
Number of Characters
<- 6 -> <------ 80 -------> <-Parameter-> <-Parameter-> <-Parameter->
ID #1 Description ####.###### ####.###### ####.######
ID #2 Description ####.###### ####.###### ####.######
         
ID #N Description ####.###### ####.###### ####.######


Format of ID lines (Richards Equation Tables)
Number of Characters
<- 6 -> <------ 80 ------> <-Parameter-> <-Parameter-> <-Parameter->
ID #1 Description ####.###### ####.###### ####.######
  ####.###### ####.###### ####.######
####.###### ####.###### ####.######
ID #2 Description ####.###### ####.###### ####.######
  ####.###### ####.###### ####.######
####.###### ####.###### ####.######
     
ID #N Description ####.###### ####.###### ####.######
  ####.###### ####.###### ####.######
####.###### ####.###### ####.######


12.5 Example Mapping Table File

The following example Mapping Table file is for the North Fork watershed. Index maps of land use and soil texture are used to assign all the parameter values. The land use index map can contain three values, 1, 2, and 3. The soil texture index map can contain only the values 1 and 2. Tables for processes not used and multiple methods of solving different processes, such as Green and Ampt infiltration and Richards’ equation can be created. Which method is used will be determined by the card in the project file, i.e. GREEN_AMPT, INF_REDIST, INF_RICHARDS.

GSSHA_INDEX_MAP_TABLES
INDEX_MAP      soil1.idx         "Soils map of North Fork"
INDEX_MAP      landuse.idx	    “Land use map of North Fork”
INDEX_MAP      landuse.idx    “This map not used”
ROUGHNESS  “Land use map of North Fork”
NUM_IDS 3
ID    Description				Roughness
1     Urban					0.05
2     Fields					0.2000
3     Fields					0.1000
INTERCEPTION  “Land use map of North Fork”
NUM_IDS 3
ID    Description			StorCap     	IntrCoeff
1     Urban                   		0.1000		0.1000
2     Fields				0.1000	 	0.1000
3     Forest		      		0.2000		0.2000
RETENTION  “Land use map of North Fork”
NUM_IDS 3
ID    Description			Retention
1     Urban             		0.5
1     Fields				1.0
2     Forest				2.0
GREEN_AMPT_INFILTRATION  “Soils map of North Fork”
NUM_IDS 2
ID    Description  HY_COND  CAP_HEAD  POR  POR_IDX  RES_SAT  
1     Clay	   0.10     50.0      0.45 3.0      0.10     
2     Sand	   1.0       7.0      0.55 1.0      0.05     
GREEN_AMPT_INITIAL_SOIL_MOISTURE  “Soils map of North Fork”
NUM_IDS 2
ID    Description			Moisture
1     Clay				0.40
2     Sand				0.10  
RICHARDS_EQN_INFILTRATION_BROOKS  “Soils map of North Fork”
NUM_IDS 2
MAX_NUMBER_CELLS 65
ID	Descript	Ks	θs	θr	θi	θwp	d	λ	ψb	Δz
1	Clay		0.1	0.5	0.1	0.25	0.15	10.0	3.0	-50.0	1.0
			0.1	0.5	0.1	0.35	0.15	50.0	3.0	-50.0	2.0
			0.1	0.5	0.1	0.45	0.15	100.0	3.0	-50.0	5.0
2	Sand		1.0	0.45	0.1	0.25	0.05	10.0	1.5	-10.0	2.0
			1.0	0.45	0.1	0.35	0.05	10.0	1.5	-10.0	5.0
			1.0	0.45	0.1	0.35	0.05	10.0	1.5	-10.0	10.0
EVAPO-TRANSPIRATION  “Land use of North Fork”
NUM_IDS 2
ID    Description	Alb        Wilt       VegH    VRadC  CanRes
1     Urban		0.100      0.100       0.100  0.100  0.100
2     Fields		0.200      0.200      10.0    0.200  0.200
3     Forest		0.300      0.300       0.15   0.300  0.300
SOIL_EROSION_PROPS  “Soils map of North Fork”
NUM_IDS 2
ID    Description			Erode    Sand      Silt
1     Clay				0.100     0.100     0.900
2     Sand				0.200     0.900     0.100
SOIL_EROSION_FACTORS  “Land use map of North Fork”
NUM_IDS 3
ID    Description			C Mng     Cons P
1     Urban				0.100     0.100
1     Fields				0.100     0.100
2     Forest				0.500     0.500