Template:GUM12
12 - Mapping Table File
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:
|
|
|
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 |
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 |
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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 | θr-θs |
| 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 | θr-θs | ||
| θ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 |
| 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 | θr-θs | ||
| θ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 |
| 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 |
| 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 |
| 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) |
| 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 |
| 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 |
| 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 |
| 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 |
| 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.
| Number of Characters | |||||
| <- 6 -> | <------ 80 -------> | <-Parameter-> | <-Parameter-> | … | <-Parameter-> |
| ID #1 | Description | ####.###### | ####.###### | … | ####.###### |
| ID #2 | Description | ####.###### | ####.###### | … | ####.###### |
| … | |||||
| ID #N | Description | ####.###### | ####.###### | … | ####.###### |
| 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
