Difference between revisions of "File Formats:Project File Format"
From Gsshawiki
(→Infiltration) |
|||
| Line 213: | Line 213: | ||
|- | |- | ||
! OVERTYPE | ! OVERTYPE | ||
| − | | EXPLICIT, ADE, or ADE-PC || Y || overland flow solver | + | | 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 | ! OVERBANK_FLOW | ||
Latest revision as of 14:55, 13 October 2023
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 #.
Contents
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
