Caveat: this version may not be consistent with previous version
EF5 is designed to facilitate creation of ensemble forecasts for flash flood prediction. As such it will incorporate multi-model support while maintaining a single set of input data. Currently the only supported model is the Coupled Routing and Excess Storage (CREST) hydrologic model. Additionally, EF5 was designed with utilization of parallel computing in mind. Presently portions of CREST are optimized to take advantage of multi-core computing through the use of OpenMP.
The Coupled Routing and Excess STorage (CREST) distributed hydrological model is a hybrid modeling strategy that was recently developed by the University of Oklahoma (http://hydro.ou.edu) and NASA SERVIR Project Team (www.servir.net). CREST simulates the spatiotemporal variation of water and energy fluxes and storages on a regular grid with the grid cell resolution being user-defined, thereby enabling global- and regional-scale applications. The scalability of CREST simulations is accomplished through sub-grid scale representation of soil moisture storage capacity (using a variable infiltration curve) and runoff generation processes (using linear reservoirs). The CREST model was initially developed to provide online global flood predictions with relatively coarse resolution, but it is also applicable at small scales, such as single basins. The CREST Model can be forced by gridded potential evapotranspiration and precipitation datasets such as, satellite-based precipitation estimates, gridded rain gauge observations, remote sensing platforms such as weather radar, and quantitative precipitation forecasts from numerical weather prediction models. The representation of the primary water fluxes such as infiltration and routing are closely related to the spatially variable land surface characteristics (i.e., vegetation, soil type, and topography). The runoff generation component and routing scheme are coupled, thus providing realistic interactions between atmospheric, land surface, and subsurface water.
More detailed information about CREST can be found in the following publication:
Wang, J., Y. Hong, L. Li, J. J. Gourley, S. I. Khan, K. K. Yilmaz, R. F. Adler, F. S. Policelli, S. Habib, D. Irwin, A. S. Limaye, T. Korme, and L. Okello, 2011: The coupled routing and excess storage (CREST) distributed hydrological model. Hydrol. Sci. Journal, 56, 84-98, doi: 10.1080/02626667.2010.543087.
CRESTPHYS builds upon the CREST model. Differently, it separates interflow with baseflow by using a fill-spill bucket to represent conceptual groundwater reservior. This approach is applied also in the National Water Model. We hope this enhanced module can bring benefits in representing baseflow and flow recession limb.
More detailed information about CRESTPHYS will follow...
Contact Allen Zhi Li (firstname.lastname@example.org) if you have questions regarding this module
The Sacramento Soil Moisture Accounting (SAC-SMA) Model was developed by the U.S. National Weather Service with the goal of parameterizing soil moisture characteristics in a fashion that would 1) logically distribute applied moisture in various depths and energy states in the soil 2) have rational percolation characteristics 3) allow an effective simulation of streamflow.
More detailed information about SAC-SMA can be found online at U.S. NWS SAC-SMA algorithm description
The Hydrophobic (HP) water balance model features an entirely impervious surface where all rainfall is transformed into surface runoff.
The linear reservoir routing is adapted from the CREST implementation. There are two reservoirs, one for overland/surface runoff and one for subsurface runoff.
Kinematic wave routing is a simplified approximation of the Barré de Saint-Venant equations developed in 1871. Kinematic wave routing assumes the gravity force and friction force are equal and cancel while neglecting the acceleration terms.
Snow-17 is a temperature index based snow melt module widely used by the U.S. NWS.
EF5 makes use of the TIFF and GEOTIFF libraries for use as a raster format. You can obtain binaries or source code and compilation documentation from:
Compiling EF5 can be accomplished in 3 steps:
1. This step is only needed if you are a developer and are adding files to the Makefile.am
autoreconf --force --install
make CXXFLAGS="-O3 -fopenmp"
The configuration file specifies all of the user changeable settings for EF5. Information in this file controls the input forcings, output options, run methods, etc.
In general the configuration file is case insensitive. The only exception is file paths when working on case sensitive file systems such as those typically found in Linux/Unix.
The configuration file supports three different styles of comments. The three styles are bash (#), C (/**/) and C++ (//).
#All variables/names/etc with the exception of #file paths are case insensitive //Multiple comment types are supported /* Including multi-line C-style comments */
Example of the different comment styles.
The basic section of the configuration file specifies the digital elevation model (DEM), drainage direction map (DDM), and flow accumulation map (FAM) files.
[Basic] DEM=/EF5Demo/FF/basic/DEM.asc DDM=/EF5Demo/FF/basic/DDM.asc FAM=/EF5Demo/FF/basic/FAM.asc PROJ=laea ESRIDDM=true SELFFAM=true
Example Basic BlockDEM: Specifies the location and file name of the DEM grid in ESRI ascii or float32 geotiff format.
Geographic: Standard geographic projection LAEA: Lambert Azimuthal Equal Area projection with the standard parallel at 45.0 and the central meridian at -100.0.ESRIDDM: Specifies if the DDM is in ESRI format or TauDEM format. Possible values are:
true: The directions in the DDM are specified as
true: The lowest flow accumulation value for any grid cell will be 1. false: The lowest flow accumulation value for any grid cell will be 0.
The precipitation forcing section specifies the information necessary to adequately describe the precipitation product that the model will ingest.
[PrecipForcing Q2Precip] TYPE=BIF UNIT=mm/h FREQ=5u LOC=/EF5Demo/FF/precip NAME=Q2_YYYYMMDDHHUU.bif
Example PrecipForcing BlockPrecipForcing Block Name: This specifies in the name of the precipitation forcing block as it will be referred to later in the configuration file. In the above example the block name is "Q2Precip".
ASC: An ESRI ASCII grid. BIF: A binary file version of an ESRI ASCII grid. TIF: A float32 geotiff grid. TRMMRT: TRMM Multisatellite Precipitation Analysis realtime binary grid. Can be gzip compressed. TRMMV7: TRMM Multisatellite Precipitation Analysis 3B42V7 HDF5 grid. MRMS: Multi-Radar Multi-Sensor binary grid.UNIT: Specifies the units of the precipitation in the file. Supported length units are meters (m), centimeters (cm) and millimeters (mm). Supported time units are year (y), month (m), day (d), hour (h), minute (u) and second (s). Modifiers in front of the time portion are also supported. For example if your precipitation forcing file has units of millimeters per three hours then your "UNIT" line would appear as "UNIT=mm/3h".
The potential evapotranspiration forcing section specifies the information necessary to adequately describe the PET product that the model will ingest.
[PETForcing PET] TYPE=BIF UNIT=mm/h FREQ=m LOC=/EF5Demo/FF/pet NAME=PET_MM.bif
Example PETForcing BlockPETForcing Block Name: This specifies in the name of the PET forcing block as it will be referred to later in the configuration file. In the above example the block name is "PET".
ASC: An ESRI ASCII grid. BIF: A binary version of an ESRI ASCII grid. TIF: A float32 geotiff grid.UNIT: Specifies the units of the PET in the file. Supported length units are meters (m), centimeters (cm) and millimeters (mm). Support ed time units are year (y), month (m), day (d), hour (h), minute (u) and second (s). Modifiers in front of the time portion are also supported. For example if your PET forcing file has units of millimeters per three hours then your "UNIT" line would appear as "UNIT=mm/3h".
These blocks specify the location of the gauges to the model. This is useful if you want time series output at a point and also to specify parameters. Basins are treated as collections of gauges with the outlet gauge being the independent gauge and all other gauges inside a basin being dependent gauges.
[Gauge OKC] LON=-97.01 LAT=35.68 OBS=/EF5Demo/obs/okc.csv BASINAREA=341.88 OUTPUTTS=TRUE [Gauge AR] LON=-93.62 LAT=34.37
Example Gauge Location BlocksGauge Location Block Name: This specifies in the name of the gauge location block as it will be referred to later in the configuration file. In the above example the block names are "OKC" and "AR".
These blocks do not represent actual physical basins but rather a collection of specified gauge locations that may or may not form a single independent basin.
[Basin FF] GAUGE=OKC GAUGE=AR
Example Basin BlockBasin Block Name: This specifies in the name of the basin block as it will be referred to later in the configuration file. In the above example the block name is "FF".
These blocks control the distributed model parameter settings. Parameters are specified per gauge and propogated upstream. Therefore each independent gauge must have a parameter set specified. Gridded parameters can be specified using the parameter name combined with "_grid" with a value specifying the grid file. When gridded parameters and uniform parameters are specified the uniform parameters act as scalar multipliers on the gridded parameter values.
[CrestParamSet ABRFC] wm_grid=/hydros/zflamig/EF5_Jess/params/crest_params/wm_usa.tif im_grid=/hydros/zflamig/EF5_Jess/params/crest_params/im_usa.tif fc_grid=/hydros/zflamig/EF5_Jess/params/crest_params/ksat_usa.tif b_grid=/hydros/zflamig/EF5_Jess/params/crest_params/b_usa.tif gauge=03455500 wm=1.00 b=1.0 im=0.01 ke=1.0 fc=1.00 iwu=50.0
Example CrestParamSet BlockGAUGE: This is the name of the gauge location block for which the parameters that follow it will be applied.
[CrestphysParamSet ABRFC] gauge=03455500 wm_grid=/hydros/wm_usa.tif im_grid=/hydros/im_usa.tif fc_grid=/hydros/ksat_usa.tif b_grid=/hydros/b_usa.tif hmaxaq_grid=/hydros//params/hmaxaq.tif gwe_grid=/hydros/params/gwe.tif gwc_grid=/hydros/gwc.tif wm=1.00 b=1.0 im=0.01 ke=1.0 ksoil=0.1 fc=1.00 iwu=50.0 igw=25.0 hmaxaq=1.0 gwc=1.0 gwe=1.0
Example CrestPhysParamSet BlockGAUGE: This is the name of the gauge location block for which the parameters that follow it will be applied.
[SacParamSet ABRFC] UZTWM_grid=/data/FLASH/v2/sac_params/uztwm_usa.tif UZFWM_grid=/data/FLASH/v2/sac_params/uzfwm_usa.tif UZK_grid=/data/FLASH/v2/sac_params/uzk_usa.tif ZPERC_grid=/data/FLASH/v2/sac_params/zperc_usa.tif REXP_grid=/data/FLASH/v2/sac_params/rexp_usa.tif LZTWM_grid=/data/FLASH/v2/sac_params/lztwm_usa.tif LZFSM_grid=/data/FLASH/v2/sac_params/lzfsm_usa.tif LZFPM_grid=/data/FLASH/v2/sac_params/lzfpm_usa.tif LZSK_grid=/data/FLASH/v2/sac_params/lzsk_usa.tif LZPK_grid=/data/FLASH/v2/sac_params/lzpk_usa.tif PFREE_grid=/data/FLASH/v2/sac_params/pfree_usa.tif gauge=01055000 UZTWM=1.0 UZFWM=1.0 UZK=1.0 PCTIM=0.101 ADIMP=0.10 RIVA=1.001 ZPERC=1.0 REXP=1.0 LZTWM=1.0 LZFSM=1.0 LZFPM=1.0 LZSK=1.0 LZPK=1.0 PFREE=1.0 SIDE=0.0 RSERV=0.3 ADIMC=1.0 UZTWC=0.55 UZFWC=0.14 LZTWC=0.56 LZFSC=0.11 LZFPC=0.46
Example SacParamSet BlockGAUGE: This is the name of the gauge location block for which the parameters that follow it will be applied.
[lrparamset rundu] gauge=rundu coem=1611.115479 river=307.980042 under=2531.556641 leako=0.918236 leaki=0.017568 th=8.140809 iso=0.000040 isu=0.000073To be completed in a future revision
[KWParamSet rundu] GAUGE=rundu UNDER=1.673110 LEAKI=0.043105 TH=6.658569 ISU=0.000000 ALPHA=2.991570 BETA=0.932080 ALPHA0=4.603945
Example KWParamSet BlockGAUGE: This is the name of the gauge location block for which the parameters that follow it will be applied.
[snow17paramset tarbela] GAUGE=tarbela UADJ=0.184653 MBASE=0.047224 MFMAX=1.068658 MFMIN=0.516059 TIPM=0.911706 NMF=0.077336 PLWHC=0.093812 SCF=2.219492
Example Snow17ParamSet BlockGAUGE: This is the name of the gauge location block for which the parameters that follow it will be applied.
[simpleinundationparamset rundu] gauge=rundu alpha=2.991570 beta=0.932080
Example SimpleInundationParamSet BlockGAUGE: This is the name of the gauge location block for which the parameters that follow it will be applied.
Tasks define the necessary information about which model to run, over what time period to run, with what time step to run, etc.
[Task RunFF] STYLE=SIMU MODEL=CREST BASIN=FF PRECIP=Q2_PRECIP PET=PET OUTPUT=/EF5Demo/FF/output/ PARAM_SET=FF TIMESTEP=5u TIME_BEGIN=201006010000 TIME_END=201006010030
Example Task BlockSTYLE: The style of task that this is. Possible values are:
SIMU: A simulation run. SIMU_RP: A simulation run that will produce standard deviation, average and skew coefficient grids for estimating return period. CALI_DREAM: A calibration run using DREAM. CLIP_BASIN: Clips the basic files to the specified BASIN. CLIP_GAUGE: Clips the basic files to the first specified gauge.MODEL: The water balance model that this task should use. Possible values are:
CREST: The Coupled Routing and Excess STorage distributed hydrological model. CRESTPHYS: CREST model + baseflow bucket SAC: The SAC-SMA model. HyMOD: HyMod.ROUTING: The routing method that this task should use. Possible values are:
KW: Kinematic Wave Routing. LR: Linear Reservoir Routing.SNOW: (Optional) The snow melt model that this task should use. Possible values are:
SNOW17: The Snow-17 snow melt model.INUNDATION: (Optional) The inundation model that this task should use. Possible values are:
SIMPLEINUNDATIOn: The Simple Inundation model.BASIN: The basin block name which defines the area over which the model should be run.
NONE: No gridded output. streamflow: Streamflow (cms) unitstreamflow: unit discharge (q/fac) soilmoisture: Soil moisture (%) returnperiod: Streamflow return period (years) precip: Precipitaiton (mm) pet: Potential evapotranspiration (mm) snowwater: Snow water equivalent from the snow melt model (mm) temperature: Temperature (C) inundation: Water depth (m) maxstreamflow: Maximum streamflow during run (cms) maxsoilmoisture: Maximum soil moisture during run (%) maxreturnperiod: Maximum return period during run (years) maxsnowwater: Maximum snow water equivalent (mm) runoff: Surface rain (mm/hr) groundwater: Conceptual groundwater table (mm) subrunoff: Subsurface runoff (mm/hr)DA_FILE: (Optional) The input observations to be added for use with streamflow data assimilation,
The execute block defines which tasks to run when the ef5 program is executed
Example Execute BlockTASK: The task block name which should be executed.
Running ef5 is straight forwarded, you can called the executable with no arguments and it will assume a default configuration file name of "control.txt" in the current working directory or you can pass in a configuration file name as an argument.
This section will be filled in once calibration methods are implemented.
/* * This is an example configuration file for EF5 */ [Basic] DEM=/EF5Demo/FF/basic/DEM.asc DDM=/EF5Demo/FF/basic/DDM.asc FAM=/EF5Demo/FF/basic/FAM.asc PROJ=laea ESRIDDM=true [PrecipForcing Q2Precip] TYPE=BIF UNIT=mm/h FREQ=5u LOC=/EF5Demo/FF/precip NAME=Q2_YYYYMMDDHHUU.bif [PETForcing PET] TYPE=BIF UNIT=mm/h FREQ=m LOC=/EF5Demo/FF/pet NAME=PET_MM.bif [Gauge OKC] LON=-97.01 LAT=35.68 OBS=/EF5Demo/obs/okc.csv [Gauge AR] LON=-93.62 LAT=34.37 [Basin FF] GAUGE=OKC GAUGE=AR [CrestParamSet FF] GAUGE=AR COEM=24.230076 EXPM=0.502391 RIVER=1.73056 UNDER=0.291339 LEAKO=0.56668 LEAKI=0.251648 TH=63.20205 GM=1.364364 PWM=71.96465 PB=0.964355 PIM=6.508687 PKE=0.19952 PFC=2.578529 IWU=53.52593 ISO=5.899539 ISU=17.31128 GAUGE=OKC COEM=24.230076 EXPM=0.502391 RIVER=1.73056 UNDER=0.291339 LEAKO=0.56668 LEAKI=0.251648 TH=63.20205 GM=1.364364 PWM=71.96465 PB=0.964355 PIM=6.508687 PKE=0.19952 PFC=2.578529 IWU=53.52593 ISO=5.899539 ISU=17.31128 [Task RunFF] STYLE=SIMU MODEL=CREST BASIN=FF PRECIP=Q2_PRECIP PET=PET OUTPUT=/EF5Demo/FF/output/ PARAM_SET=FF TIMESTEP=5u TIME_BEGIN=201006010000 TIME_END=201006010030 [Execute] TASK=RunFF
Example of a full EF5 configuration file.