File Formats:Project File Format

From Gsshawiki
Revision as of 14:55, 13 October 2023 by Aabyrd (talk | contribs)

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

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