File Formats:Project File Format

The project file is the heart of a GSSHA simulation. It controls what processes run, when they run, and what output is returned. The project file references many other files. These files often differ in name by not much more than the extension. The extensions shown here are the defaults used in WMS, but they are not fixed. Filenames or paths, if they contain spaces, should be enclosed in double quotes.

Note: This section has not been kept up to date with developments. Please refer to Chapter 3 of the Manual, which describes the project file, and projects cards in detail.

Comments in the project file begin the line with a #.

Header

A GSSHA project file always begins with the same header

Card	Input	Req'd	Comments
GSSHAPROJECT	none	Y	Identifies the file as a GSSHA project file.

WMS info

Next comes info that WMS needs when reading the project

Card	Input	Req'd	Comments
WMS	version	Y	This simply conveys the version of WMS used to create the project.
FLINE	filename.map	Y	The WMS map file associated with this project. WMS reads this file in to create the GIS data.

General Simulation Data

The general simulation data provides the framework for how the simulation is to be set up and run. The mask file controls what cells are on and off, and all other grid files must have the exact same dimensions as the mask file.

Card	Input	Req'd	Comments
WATERSHED_MASK	filename.msk	Y	The watershed mask controls the simulation domain.
PROJECT_PATH	path	N	Path to all project files. This path is prepended to all files that GSSHA tries to open.
METRIC	none	N	output hydrographs are in cms (default)
ENGLISH	none	N	output hydrographs are in cfs,either specify METRIC or ENGLISH, not both
GRIDSIZE	value	Y	value in meters of the grid dimensions
ROWS	value	Y	number of rows in the simulation, should match the value in the watershed mask
COLS	value	Y	number of colums in the simulation, should match the value in the watershed mask
TOT_TIME	value	Y	simulation length (non-long-term) in minutes
TIMESTEP	value	Y	overland and stream time step in seconds
OUTROW	value	Y	outlet row number, for overland flow only
OUTCOL	value	Y	output column number, for overland flow only
OUTSLOPE	value	Y	outlet slope, for overland only
TIME_SERIES_FILE	filename.ts	N	read file containing time series; this is optional and it may be repeated to include several files
EVENT_MIN_Q	value	Y	the minimum flow to signal the end of event
END_TIME	year month day hour min	N	if this time is reached in the simulation then the simulation automatically ends.
NUM_THREADS	##	N	If using GSSHA compiled with OpenMP, then this will change the default thread level (which is to use all logical processors).

The simulation will end at the end of hmet data when the flow has fallen below event_min_q (for long-term runs) or when the tot_time has been reached (uniform or gaged precip, non-long-term runs) or if the current simulation time is after the end time.

Replacement cards

GSSHA has the ability to replace any part of any line of any input file with a value from another file. These files must be set up for batch mode processing.

Card	Input	Req'd for Replacement	Comments
REPLACE_PARAMS	filename.ext	Y	Replacement parameter file.
REPLACE_VALS	filename.ext	Y	Replacement value file.
REPLACE_FOLDER	path	N	Puts all output files in the specified folder.
REPLACE_LINE	##	N	Use a certain line from the values file.

Output cards

These cards control the output of GSSHA. There are several output formats-- gridded data, link/node data, time series data, and summary files.

Card	Input	Req'd	Comments
SUMMARY	filename.sum	Y	Summary output file. Most important output file of them all.
OUTLET_HYDRO	filename.otl	Y	outlet hydrograph time series
MAP_FREQ	value	Y	gridded output frequency, in minutes
HYD_FREQ	value	Y	hydrograph, link/node dataset output frequency, in minutes
MAP_TYPE	value	Y	gridded output format, 0=ascii grid sequence, 1=WMS gridded dataset
DEPTH	filename.dep or path	N	overland flow depth maps, if map_type==0 then put a path else put a filename.
SURF_MOIST	filename.smo or path	N	soil moisture output, see DEPTH
GW_OUTPUT	filename.gwh or path	N	groundwater heads, see DEPTH
DIS_RAIN	filename.drn or path	N	rainfall rate as it is being applied, see DEPTH
INF_DEPTH	filename.idp or path	N	infiltration depth, see DEPTH
DISCHARGE	filename.dsc or path	N	overland discharge, see DEPTH
CHAN_DEPTH	filename.cdp	N	channel flow depth, link/node format
CHAN_DISCHARGE	filename.cdq	N	channel discharge, link/node format
CHAN_STAGE	filename.cst	N	channel stage, link/node format
CHAN_VELOCITY	filename.cvl	N	channel velocity, link/node format
STRICT_JULIAN_DATE	none	N	force hydrograph output to be in strict julian date
QUIET	none	N	do not output to screen as model is running
SUPER_QUIET	none	N	do not output to screen
IN_HYD_LOCATION	filename.ihl	N	describes hydrograph output locations
OUT_HYD_LOCATION	filename.ohl	Y if .ihl	output hydrographs from .ihl file
IN_THETA_LOCATION	filename.ith	N	describes soil moisture output locations
OUT_THETA_LOCATION	filename.oth	Y if .ith	output soils moisture time series from .ith
FLOOD_GRID	filename.fgd	N	outputs the maximum water depth on the overland grid
FLOOD_STREAM	filename.fst	N	outputs the maximum water depth on the stream network
OPTIMIZE	filename.opt	N	outputs the values of event peak flow and event volume for use by external optimization methods

Overland Flow

There are several cards to set up overland flow. The elevation file must be specified, an overland solver selected, and roughness values set up.

Card	Input	Req'd	Comments
ELEVATION	filename.ele	Y	surface elevation grid file
OVERTYPE	EXPLICIT, ADE, or ADE-PC	Y	overland flow solver (EXPLICIT is being deprecated in v8.0 and will not be an option in future versions)
OVERBANK_FLOW	none	N	allow streams to flow back to overland
MAX_COURANT_NUMBER	value	N	used to change the maximum courant number allowed from the default (0.06)
INITIAL_DEPTH	filename.idp	N	read in a hot start file
READ_OV_HOTSTART	filename.idp	N	read in a hot start file, same as INITIAL_DEPTH
WRITE_OV_HOTSTART	filename.odp	N	write the overland depths at the end of the simulation
ROUGHNESS	filename.ovn	N	GSSHA reads a gridded file of n values; if not present and MANNING_N not present, then GSSHA assumes to use the mapping table. If the mapping table is not properly set up you will see an error.
MANNING_N	value	N	use uniform manning's n value for overland flow, see ROUGHNESS
OV_BOUNDARY	none	N	do overland boundaries according to the OVERLAND_BOUNDARY table in the mapping table file.
EMBANKMENT	filename.dik	N	set up no-flow embankments between overland grid cells.
LOWSPOT_FILE	filename.lsp	N	set up low spots for overtopping on the embankments

Stream Flow

There are several input files that set up the stream network. The most important of these are the channel input file (.cif) and the grid/stream file (.gst.) The stream network is not required to run a GSSHA simulation, so the required column lists those cards that are required to run the stream network.

Card	Input	Req'd for Streams	Comments
NON_ORTHO_CHANNELS	none	Y	Run the channel model
DIFFUSIVE_FLOW	none	Y	Use the diffusive flow numerical model, currently the only supported numerical model for streams.
STREAM_CELL	filename.gst	Y	The grid-stream file tells GSSHA how the streams link to the grids.
CHANNEL_INPUT	filename.cif	Y	The channel input file describes the entire stream network, e.g. cross-sections, thalweg profile, roughness values, etc.
HEAD_BOUND	none	N	Use a head boundary at the channel outlet
BOUND_DEPTH	value	if HEAD_BOUND then either BOUND_DEPTH or BOUND_TS	Use a constant value (m) for the outlet channel depth (not stage.)
BOUND_TS	time series name	if HEAD_BOUND then either BOUND_DEPTH or BOUND_TS	Use a time series to specify the outlet boundary depth (m) (not stage.)
WRITE_CHAN_HOTSTART	filename.ext	N	Create two channel hot-start files at the end of the simulation. Depth file has extension .dht, flow has extention .qht.
READ_CHAN_HOTSTART	filename.ext.ext	N	Read in a hot-start file, created by WRITE_CHAN_HOTSTART.
HOTSTART_IS_DEPTH	none	N	Treat hot-start file as depth of flow when reading it in.
STREAM_LOSS	none	N	Do stream losses even if groundwater is not turned on
M_RIVER	value	N	Uniform value (m) for stream sediment thickness for stream losses. Only use if not specified in the channel input file.
K_RIVER	value	N	Uniform hydraulic conductivity (cm/hr) of streambed for stream losses. Only use if not specfied in the channel input file.
EXPLIC_BACKWATER		N
FIRST_ORDER_CHAN_Q		N

Infiltration

These are the four different infiltration options. One of these are required to run infiltration.

Card	Input	Req'd for Groundwater	Comments
GREEN_AMPT	none	Run single or two layer Green & Ampt. (Single event model)
INF_REDIST	none	Use G&A w/ soil moisture redistribution (Long-term model, may have 1 or 2 layers)
INF_LAYERED_SOIL	none	Use G&A layered model. (Single event model)
INF_RICHARDS	none	Use Richard's Equation model. (Long-term model)

These parameters are required for the Richard's Equation infiltration model.

Card	Input	Comments
RICHARDS_WEIGHT	##	Usually 0.8 to 1.2
RICHARDS_K_OPTION	geometric or arithmetic
RICHARDS_C_OPTION	havercamp or brooks
RICHARDS_UPPER_OPTION	green_ampt or average
RICHARDS_ITER_MAX
RICHARDS_DTHETA_MAX
AQUIFER_DELTA_Z	##.##

These are used for the G&A and the G&A w/ Redistribution to create the soil moisture layers. If top_layer_depth is not included, then only one layer will be used.

Card	Input	Comments
SOIL_MOIST_DEPTH	##.##	Full depth for soil moisture computations.
TOP_LAYER_DEPTH	##.##	Upper layer depth (included in soil_moist_depth) for just an upper layer soil moisture layer.

There are two cards for hot-starting.

Card	Input	Comments
WRITE_SM_HOTSTART	<filename>	Write out the soil moisture at the end of the simulation as a hot start file.
READ_SM_HOTSTART	<filename>	Read initial soil moistures.

Groundwater

Card	Input	Req'd for Groundwater	Comments
GW_SIMULATION	none	Y	Run groundwater simulation.
WATER_TABLE	filename.wte	Y	Specifies the initial water table elevation.
AUIFER_BOTTOM	filename.aqe	Y	Specifies the lower extent of the aquifer.
GW_ASSIGN_THETA
GW_LSOR_DIR
GW_UNIF_POROSITY
GW_UNIF_HYCOND
GW_TIMESTEP
GW_LSOR_CON
SINGLE_UNSAT_SAT
GW_LEAKAGE_RATE
GW_RELAX_COEFF
GW_FLUX_BOUNDTABLE
GW_BOUNDFILE
GW_OUTPUT
GW_WELL_LEVEL
OUT_WELL_LOCATION

Precipitation

Card	Input	Req'd	Comments
PRECIP_FILE	filename.gag	either PRECIP_FILE or PRECIP_UNIF	input gaged or radar precip data
PRECIP_UNIF	none	either PRECIP_FILE or PRECIP_UNIF	use uniform precipitation
RAIN_THIESSEN	none	either RAIN_THIESSEN or RAIN_INV_DISTANCE	use theissen polygons to distribute rainfall
RAIN_INV_DISTANCE	none	either RAIN_THIESSEN or RAIN_INV_DISTANCE	use inverse distance weighting to distribute rainfall
RAIN_INTENSITY	value	Y if PRECIP_UNIF	Set the precipitation intensity for uniform precip. mm/hr.
RAIN_DURATION	value	Y if PRECIP_UNIF	Set the precipitation duration for uniform precip. Minutes.
START_DATE	year month day	Y if PRECIP_UNIF	starting simulation time for uniform precip
START_TIME	hour minute	Y if PRECIP_UNIF	starting time for uniform precip

Constituent Transport

This section controls all constituents, simple and NSM. To include NSM controls, see the Nutrients section.

Card	Input	Req'd for Transport	Comments
OV_CON_TRANS	none	N	Turns on routing in the overland. Can route in overland w/out streams, soils.
CHAN_CON_TRANS	none	N	Turns on routing in the streams. Can route in streams w/out routing in overland.
SOIL_CON_TRANS	none	N	Turns on routing in the soils. Must have overland routing turned on.
SEDIMENT_CONTAM	none	N	Turns on sorption/desorption of constituents to sediments.
SOIL_STATIC_CONC	none	N	Keeps the soil concentrations constant.
OUT_MASS_LOCATION	filename.ext	N	Filename for output mass fluxes, uses .ihl locations
OUT_CON_LOCATION	filename.ext	N	Filename for output concentrations, uses .ihl locations

Nutrients

Setting up nutrients requires several cards. The transport options need to be specified for whichever flow options are turned on. The aquatic environment file, with its stream index map and overland index map, needs to be set up with the kinetic rates.

General Setup

Card	Input	Req'd for Nutrients	Comments
NUTRIENTS	none	Y	Tells GSSHA to do NSM nutrients kinetics and transport
MIXING_LAYER_DEPTH	value	Y if SOIL_CONTAM	The depth of the surface soil layer containing the constituents
OV_CON_TRANS	none	Y	Tells GSSHA to do overland constituent transport
CHAN_CON_TRANS	none	Y if streams	Tells GSSHA to do channel constituent transport
SOIL_CONTAM	none	Y if infiltration	Tells GSSHA to do vadose zone nutrient transport
AQ_ENV	filename.aqe	Y	contains the controlling kinetic rates
CHAN_PH	value	Y if computing Kjeldahl N	The pH of the water (constant)
WATER_TEMP	value	Y	The temperature of the water (constant)
SOURCEFILE	filename.src	N	describes point and non-point loadings
OV_DISPERSION	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values.

Soils Initialization

Card	Input	Req'd for Nutrients	Comments
SOILS_NSM_P	none	N	Initialize cell loadings from mapping table values
SOILS_NSM_N	none	N	Initialize cell loadings from mapping table values
SOILS_NSM_C	none	N	Initialize cell loadings from mapping table values

Overland Initialization

Values of constituents in water produced by hotstart or init_cell_elev cards.

Card	Input	Req'd for Nutrients	Comments
OV_INIT_NO2	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.
OV_INIT_NO3	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.
OV_INIT_NH4	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.
OV_INIT_ON	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.
OV_INIT_OP	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.
OV_INIT_DP	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.
OV_INIT_ALG	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.
OV_INIT_CBOD	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.
OV_INIT_DO	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.
OV_DOC_INIT	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.
OV_DOC_FOC	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in mg/l.

Stream Initialization

Card	Input	Req'd for Nutrients	Comments
ST_MAPPING_TABLE	filename.smt	N	Mapping table for streams.
ST_INIT_NO2	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in kg per cell.
ST_INIT_NO3	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in kg per cell.
ST_INIT_NH4	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in kg per cell.
ST_INIT_ON	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in kg per cell.
ST_INIT_OP	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in kg per cell.
ST_INIT_DP	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in kg per cell.
ST_INIT_PO4	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in kg per cell.
ST_INIT_ALG	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in kg per cell.
ST_INIT_CBOD	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in kg per cell.
ST_INIT_DO	none, uniform value, or filename.ext	N	If blank, use mapping table. If filename, apply grid of values. Value is in kg per cell.

Overland Nutrient Output

Card	Input	Req'd for Nutrients	Comments
total_ov_n	filename.ton or path	N	gridded output of total N mass and concentration (will add .mass and .conc)
total_ov_p	filename.top or path	N	gridded output of total P mass and concentration (will add .mass and .conc)
out_ov_no2	filename.on2 or path	N	gridded output of overland NO2 mass and concentration (will add .mass and .conc)
out_ov_no3	filename.on3 or path	N	gridded output of overland NO3 mass and concentration (will add .mass and .conc)
out_ov_nh4	filename.on4 or path	N	gridded output of overland NH4 mass and concentration (will add .mass and .conc)
out_ov_on	filename.oon or path	N	gridded output of overland ON mass and concentration (will add .mass and .conc)
out_ov_op	filename.oop or path	N	gridded output of overland OP mass and concentration (will add .mass and .conc)
out_ov_dp	filename.odp or path	N	gridded output of overland DP mass and concentration (will add .mass and .conc)
out_ov_po4	filename.op4 or path	N	gridded output of overland PO4 mass and concentration (will add .mass and .conc)
out_ov_alg	filename.oal or path	N	gridded output of overland Algae mass and concentration (will add .mass and .conc)
out_ov_cbod	filename.ocb or path	N	gridded output of overland CBOD mass and concentration (will add .mass and .conc)
out_ov_do	filename.odo or path	N	gridded output of overland DO mass and concentration (will add .mass and .conc)

Stream Nutrient Output

Card	Input	Req'd for Nutrients	Comments
total_chan_n
total_chan_kn
total_chan_p
out_st_no2
out_st_no3
out_st_nh4
out_st_on
out_st_op
out_st_dp
out_st_po4
out_st_alg
out_st_cbod
out_st_do

Nutrient Loadographs

Card	Input	Req'd for Nutrients	Comments
out_hyd_no2
out_hyd_no3
out_hyd_nh4
out_hyd_on
out_hyd_op
out_hyd_dp
out_hyd_po4
out_hyd_alg
out_hyd_alg
out_hyd_cbod
out_hyd_do

Sediment Transport

Card	Input	Req'd for Sediments	Comments
SOIL_EROSION		Y
SOIL_ERODABILITY		N	Uniform erodability factor
CHAN_SED_FLUX		N
IN_SED_LOC		N
VOL_SED_SUSP		N
MAX_SED_FLUX		N
NET_SED_VOLUME		N
OUTLET_SED_FLUX
OUT_SED_LOC
SED_POROSITY		Y
OUT_SED_LOC

Analyzers

Analyzers look into the GSSHA code as it is running and print out specified data values.

Card	Input	Req'd for Analyzers	Comments
ANALYZERS	filename.ext	Y	Turn on output analyzers.

GSSHA User's Manual

17 GSSHA File Formats

17.1     Project File

17.2     Mapping Tables

17.3     Stream Network Files

17.4     GRASS grid files

17.5     Nutrient Files

17.6     Time and Elevation Series Files