Mapping Table: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.