WASP7-EFDC Linkage (3D Lake Example)


This technical document provided by Dynamic Solutions International, LLC (DSI)  (www.ds-intl.biz) describes the step-by-step procedures needed to create an EFDC hydrodynamic model results binary file (*.HYD) that is formatted for linkage as an input file to the WASP7 water quality model.  This technical memorandum provides the information needed and example problems to show the step-by-step procedures needed to successfully create and apply an EFDC project to export a hydrodynamic file (*.HYD) for linkage as an input file for a WASP7 water quality model project.  The description contained in this document assumes that the user has completed the setup of a working EFDC project for a hydrodynamic model and wishes to generate a binary HYD file as input to a WASP7 water quality model. 

The user is reminded that the EFDC model and the EFDC_Explorer interface can be obtained from DSI’s EFDC_Explorer web site (www.efdc-explorer.com)  includes a fully functioning coupled sediment transport and water quality model in a single EFDC model source code. The EFDC water quality model is comparable to the state variables included in the WASP7 water quality model. 

Two example problems are developed by DSI to show how an EFDC model can be setup and linked to a WASP7 water quality model.

Example Problem#2: A 3D time variable lake model for hydrodynamics, sediment and water quality is setup as an EFDC model. The hydrodynamic results file (HYD) is then used to setup the same 3D lake model in WASP7. All input files needed for the EFDC and the WASP7 models are provided for the 3D lake model problem.

This document presents the information and data needed for link age of the EFDC 3D Lake model to a WASP7 3D Lake model.

DSI recommends using the EFDC_DSI coupled hydrodynamic and water quality model instead of the EFDC/WASP linkage process as a faster approach to water quality modeling and it provides the user with more robust tools for pre- and post-processing the water quality model.  This allows the user to focus more on producing a better modeling study rather than wasting time with model/linkage mechanics.

Documentation for EFDC-WASP7 Linkage

The US Environmental Protection Agency (EPA) supports a number of public domain watershed, hydrodynamic and water quality models for use in water quality management studies including TMDL evaluations. The EPA Watershed & Water Quality Modeling Technical Support Center is the portal for downloading EPA supported models ( http://www.epa.gov/athens/wwqtsc/index.html).

Figure EPA Watershed & Water Quality Modeling Technical Support Center

The current version of the EPA supported WASP7 model (Version 7.52) can be downloaded from the URL link https://www.epa.gov/exposure-assessment-models/water-quality-analysis-simulation-program-wasp

Screenshots of the WASP7 pages from the EPA website are shown below.

Figure 2  Water Quality Analysis Simulation Program (WASP), page 1 of 2

Figure Water Quality Analysis Simulation Program (WASP)

The current versions of the Dynamic Solutions-International EFDC model and EFDC_Explorer can be downloaded from the URL links:



Example Problem #2: Three Dimensional (3D) Time Variable Lake Model

The setting for the 3D lake model includes watershed loading represented by tributary inflows and nonpoint distributed inflows (Figure 4). The lake model is setup with 195 horizontal segments (Figure 5 ) and the boundary locations identified in Figure 4. Model bathymetry is shown in Figure 6 and the bottom profile along the centerline of the lake with the 10 vertical layers is shown in Figure 7.  The EFDC model is activated for state variable modules checked off in Figure 8. The model is setup to simulate lake level, water temperature (Figure 9), cohesive sediments (Figure 10 to Figure 12) and water quality (Figure 13). The sediment diagenesis model is also activated to provide internal coupling of water column particulate organic matter deposition with sediment-water interface fluxes of nutrients and oxygen.  Kinetic coefficients for the water quality model are assigned in the screen shown in Figure 14.

 The EFDC model is configured to generate a hydrodynamic (HYD) file for linkage to the WASP7 water quality model.  The WASP7 water quality model is setup with the EFDC grid cell scheme and the hydrodynamic transport data from the HYD file. The default boundary condition settings of 1.0 mg/L for all state variables, all boundary segments and all boundary layers are setup by linkage of the lake model HYD file with WASP7. 

The boundary condition data sets for cohesive sediment and water quality for the EFDC lake model are not setup in the WASP7 model.  The settling velocity data used in the EFDC lake model for cohesive sediment, particulate organic matter and algae is also not setup for the WASP7 model. The effort required to setup boundary conditions and solids settling data for input to WASP7 is left to the user who wishes to learn how to setup a WASP7 model by developing a 3D WASP7 lake model that can be compared to the existing EFDC 3D lake model.

The timing of the EFDC model is shown in Figure 15. Linkage with EFDC_Explorer and WASP7 is shown in Figure 16 and Figure 17.

Figure Boundary Conditions for 3D Lake.

Figure Boundary Condition Locations for 3D Lake. Dashed line shows centerline of lake.

Figure 6- Bottom Elevation of 3D Lake.

Figure 7- Bottom Profile Along Centerline of lake.

Figure Active Modules for 3D Lake Problem.

Figure Water Temperature.

Heat/Temperature Option for “Equilibrium Temp (CE-QUAL-W2) Method)” is selected for the 3D lake model.

Figure 10-Cohesive Sediment.

One class of cohesive sediment is setup for example problem. One bed layer is required for sediment transport model.

Figure 11  Cohesive Erosion and Deposition Parameters.

Figure 12  Bed Morphology and Consolidation.

Figure 13  Water Quality-Module 1 (Standard) is selected.

Figure 14  Kinetic coefficients and parameters of the EFDC water quality model.

Figure 15  Timing and Linkage for 3D Lake Problem. 

1/1/1985 is assigned as the reference base date. The simulation begins on 1 Jan 1992 (day=2556) and ends 365 days later. A time step of 20 seconds is used to maintain a stable solution. 

Figure 16  EFDC Explorer Linkage-EFDC results are written to output files at 60 minute intervals

Figure 17  WASP Linkage.

WASP7HYDRO is selected from the drop down list for WASP linkage.  The # Time periods to average is assigned 180 to match the 60 minute output interval assigned for EFDC Explorer linkage. With a time step of 20 sec and an EFDC output interval of 60 minutes (=3600 seconds), the EFDC model results are averaged over 180 iterations (180 =3600 sec/20 sec DT).

EFDC-WASP7 Linkage Control File EFDC.WSP

Successful generation of an EFDC hydrodynamic linkage (HYD) file requires (a) setup of an EFDC hydrodynamic model; and (b) user created input control file named EFDC.WSP.  A description of the data provided in the EFDC.WSP file is presented in the EFDC Hydro user’s manual.  The User manual can be downloaded from EPA website:


Figure 18- Input File EFDC.WSP from EFDC-HYDRO User Manual (EPA, 2002)

EFDC.WSP is an ASCII text file that can be created in any text editor. As shown in the code shown below, the filename EFDC.WSP is hardwired in the EFDC model source code that uses the control file to support generation of the EFDC HYD file for linkage to WASP7.  The EFDC.WSP control file must be located in the same folder used for all the EFDC project input files.

c      for jswasp=1 only first entry


The current version of the EFDC source code that can be obtained from Dynamic Solutions International uses a version of the EFDC.WSP control file for creation of the EFDC HYD file that is similar, but not identical, to the record structure shown in the above screenshot from the EFDC-HYDRO user manual (Figure 18). The available WASP7 user manuals and documentation reports available from EPA do not provide any documentation of the modified format required for the EFDC.WSP control file.

Screenshots of the EFDC.WSP file used for the 3D Lake problem are shown below. The EFDC.WSP text file is included in the files provided for this sample problem.

Figure 19- EFDC.WSP Control File used for 3D Lake problem, partial listing.

As can be seen in the data entered in the EFDC.WSP control file (Figure 19), most of the ”legacy”  parameters shown in the EFDC-HYDRO manual are assigned dummy integer or floating point values of 999 or 999.0.

Card image C2 includes new data for ADCOEFF and ABMAX as shown in the C2 records below


C2    xxxxx xxxxx  xxxxx   xxxx    ADCOEFF     ABMAX   

      999   999.0  999.0   999      0.9          0.001    

These two parameters are described in the EFDC.WSP control file as:

  • ·         ADCOEFF - coefficient that limit the max dispersion flux to a fraction of the volume divided by the time step
  • ·         ABMAX - global maximum dispersion in m2/s - this set an upper limit on the vertical dispersion

Card Image C3 is the record where the user assigns the filename for the EFDC HYD file.

C3    Hyd file name and IDAYS PARAMETERS

C3    xxxx xxxxxx xxxxxx   xxxxx   Hyd File Name  xxxxxx  xxxx    IDAYS

        4   999    999.0   999.0      efdc_dsi_wasp.hyd    999      999     0

Card Image C5 is where the user assigns the reference beginning date for the EFDC hydrodynamic model project.  See screenshot from EFDC_Explorer for data input for the 3D Lake hydrodynamic project (Figure 20).

C5    Not Used

C5    iyear   imon     iday   

      1985     1         1

Figure 20  EFDC_Explorer Model Run Timing. 

Beginning date/time for reference date for EFDC Julian day values is 1/1/1985 for the 3D Lake. EFDC Start simulation Day 2556 is 1-Jan-1992 00:00. Reference date is entered on Card image C5 to assign the beginning year, month, day for the WASP7 project.

After the control file input for the beginning date of the EFDC/WASP7 project the user must enter a set of data records to assign the spatial dependence of ABMAX for each horizontal grid cell (I, J) of the EFDC model domain.

C5 list of cell specific ABmax; overrides global ABMAX for cells listed; ABMAX for all cells written out to ABmax.txt file. The first few records of this part of the EFDC.WSP file are shown below.

C5     I       J    ABmax   I J Wasp Segment Data for 3D LAKE Problem

       3       3       0

       3       4       0

       3       5       0

The EFDC source code that reads the ABMAX data provided in the EFDC.WSP file reads in the loop from LT=2, LALT as shown below. 

        DO LT=2,LALT                              




          write(*,*)'<EFDC.WSP7> ',i,j,abwmax              


12      continue

The sequence of the data records in the loop LT=2, LALT reads each horizontal grid cell in the EFDC project in a sequence identical to the loop used to read EFDC input data from the DXDY.INP file as shown in the screen shot of the file for the 3D Lake problem (Figure 21). 

Figure 21-DXDY.INp file for 3D Lake problem. 

First two data columns above provide the sequence of all horizontal (I, J) grid cells that are required for correct setup of the EFDC.WSP control file.  The user can prepare a correctly formatted EFDC.WSP file by importing the DXDY.INP file into Excel to get the correct sequence of I and J grid cells. Insert a third column after the imported I, J records from the DXDY.INP and insert the assignment of ABMAX value (as m**2/sec) desired for each grid cell.

Figure 22  Input files for 3D Lake problem. EFDC.WSP file must be located in folder for EFDC project.

Linkage of EFDC Generated HYD file and Setup of WASP7 Project

Successful generation of an EFDC hydrodynamic linkage (HYD) file requires (a) setup of a working EFDC hydrodynamic model; and (b) user created input control file EFDC.WSP as described above.  The EFDC model writes the hydrodynamic (HYD) file for linkage to the WASP7 project to the EFDC project folder …………….. \#output\wasp\ (see Figure 23). The EFDC HYD hydrodynamic linkage file is used to setup a new WASP7 project as described in Ambrose and Wool (2009).


Ambrose, R.A. and T. Wool (2009) WASP7 Stream Transport- Model Theory and User’s Guide, EPA/600/R-09/100, September.

Section 4.1.4 and 4.1.5 text presented below is taken from Ambrose and Wool (2009)

4.1.4 Hydrodynamics

There are currently three surface flow options available for WASP. The first two options pertain to how WASP will calculate the exchange of mass between adjoining segments with flow in both directions across a segment interface. The three flow options available for surface water flow are:

1. Gross Flows -- WASP will calculate net transport across a segment interface that has opposing flow. WASP will net the flows and move the mass from the segment that has the higher flow leaving. If the opposed flows are equal no mass is moved.

2. Net Flows -- Pertains to mass and water being moved without regard to net flow.

3. Kinematic Wave -- For one-dimensional, branching streams or rivers, kinematic wave flow routing is a simple but realistic option to drive advective transport. The kinematic wave equation calculates flow wave propagation and resulting variations in flows, volumes, depths, and velocities throughout a stream network.

4. Hydrodynamic Linkage -- Realistic simulations of unsteady transport in rivers, reservoirs, and estuaries can be accomplished by linking WASP7 to a compatible hydrodynamic simulation. This linkage is accomplished through an external “hyd” file chosen by the user at simulation time. The hydrodynamic file contains segment volumes at the beginning of each time step, and average segment interfacial flows during each time step. WASP7 uses the interfacial flows to calculate mass transport, and the volumes to calculate constituent concentrations. Segment depths and velocities may also be contained in the hydrodynamic file for use in calculating reaeration and volatilization rates. Before using hydrodynamic linkage files with WASP, a compatible hydrodynamic model must be set up for the water body and run successfully, creating a hydrodynamic linkage file with the extension of *.hyd. This is an important step in the development of the WASP input file because the hydrodynamic linkage file contains all necessary network and flow information. When Hydrodynamic Linkage is selected in the Data Set Parameters screen, the user cannot provide any additional surface flow information. When you are ready to begin the development of a WASP input deck, simply open the hydrodynamic linkage file from within the data preprocessor. The hydrodynamic linkage dialog box allows the user to browse and select a hydrodynamic linkage file. The data preprocessor will open the hydrodynamic interface file and extract the number of segments, the starting and ending time. The data processor will also determine the set of boundary segments (segments that receive flow from outside the model network) and set the boundary concentrations to 1.0 mg/L. Once a hydrodynamic linkage file is selected in the data preprocessor, WASP has enough information to execute a simple test run with no loads or kinetics enabled. This step is recommended to test the network and transport integrity. If the simulation is run for a sufficient duration, concentrations should approach 1.0 mg/L throughout the network. If you are getting a number other than 1 mg/L, you may have to use a different time step in the hydrodynamic model. This is especially true if the concentrations are oscillating between large and small numbers, a clear indication of numerical instability. WASP has the ability to get hydrodynamic information from a host of hydrodynamic models. If a hydrodynamic model does not support the WASP linkage it is relative straightforward to create a hydrodynamic linkage file (see Appendix X for file format). The hydrodynamic models that currently support the WASP7.x file format are: EFDC (three dimensions), DYNHYD (one dimension branching), RIVMOD (one dimension no branching, CE-QUAL-RIV1 (one dimension branching), SWMM/Transport (one dimension branching, SWMM/Extran (one dimension branching)

4.1.5 Solution Technique

The user now has the ability to select the model solution technique to be used by the water quality module during the simulation. Currently there are 3 solution techniques that can be selected: 1) Euler – which is the traditional solution technique that has been in WASP since its inception, 2) COSMIC Flux Limiting – this solution technique is typically used when WASP is linked to multi-dimensional hydrodynamic models like EFDC, 3) Runge-Kutta 4 step solution technique used for diurnal simulations.

Figure 23  EFDC generated HYD file efdc_dsi_wasp.hyd for 3D Lake problem.

A step-by-step sequence of screen shots is shown in Figure 24 through Figure 33 to illustrate how to link the EFDC generated HYD file to setup and save a new WASP7 project.

Figure 24  Startup screen when WASP7 is open.

Pre-processor button is grey so data cannot be entered yet.  Click on File and select the first item in drop down list to define a ‘New’ file

Figure 25  After clicking “New “ the pre-processor button is now ready to be activated to import the EFDC HYD file

Figure 26  Hydrodynamic Linkage File.

When you click on Pre-Processor, this screen is opened.  This is the screen where you load the EFDC HYD file. Click the button for ‘Hydrodynamic Linkage File’ and use the browser to locate the EFDC HYD file generated for the project.  EFDC writes the HYD file to the EFDC project folder …\DM-08_3DLake_WASP_Linkage_(EE8.3)\EFDC\#output\wasp

Figure 27  EFDC generated HYD file for 3D Lake problem.

Select and open the HYD file in the WASP7 screen. Path is shown in Figure 23 for the EFDC HYD file for the project.

Figure 28  Message from WASP7 when HYD file is selected.

Select ‘Yes’ to setup the new WASP7 project for the 3D Lake problem.

Figure 29- EFDC HYD file selected. Click OK to read the HYD file.

Figure 30  Data read from EFDC HYD file for the 3D Lake problem, page 1 of 2

Figure 31  Data read from EFDC HYD file for the 3D Lake problem, page 2 of 2

Figure 32  Parameters Screen for Data Set.

Pre-processor page now shows beginning and ending date and time 1/1/1992 00:00 and 12/30/1992 23:00 for the model run.  Note that the solution technique has correctly been changed from EULER to COSMIC because the HYD linkage has been correctly read by WASP7.  User can enter project name and description of the run/problem etc in space at top of the screen. Next step is to save the new WASP7 project file as *.WIF.

Go back to “File” button on main screen and click ‘Save As’ project file, then you use browser to save the WASP7 project file to the folder for WASP7 projects (not EFDC projects).

Figure 33  WASP7 project file saved in WASP7 project folder (not the EFDC project folder).

The next set of steps in setting up the WASP7 project is the input of boundary condition data for each state variable and each boundary segment. Screenshots shown in Figure 34 through Figure 43 show the assignment of default boundary condition data and testing the boundary condition settings for the 3D Lake problem.

Figure 34  Pre-Processor Selection for (+)  Boundaries brings up this screen.

Figure 35  Click on Ammonia (+) and list of boundary segments is displayed.  

K=10 is WASP7 surface layer.  Boundary data is entered for all 10 vertical layers for each of the boundary locations.

Figure 36  Click on segment I=10 J=41 K=10 and the default setting of 1.0 for boundary condition data is displayed in the Time Function screen. 

Ammonia boundary value of 1.0 is set for begin date/time 1/1/1992 00:00 and end date/time 12/30/1992 23:00.  WASP7 assigns a default setting of 1.0 for all boundary conditions for all state variables. WASP7 boundary segments are setup with linkage data for the EFDC grid cell model domain.  When setting up a new WASP7 project, EPA recommends that a model run be executed at this point to test that the data provided by EFDC hydrodynamic linkage will result in a stable WASP7 model solution. Next step is to go to main screen and execute the WASP7 model to test the boundary settings of 1.0.

Figure Click on Model and execute WASP7.  

Figure 37 shows screen display when WASP7 is executing. Estimate of time remaining for model run is shown at lower right of screen.

Figure 38  WASP7 run has completed successfully. 

The linkage of EFDC water temperature with WASP7 water temperature is checked with the WASP7 post-processor.  Water temperature is extracted for Wasp7 segment 7 (surface layer) and segment 1762 (bottom layer) (see Figure 39).  A lookup table WASP7SEG_EFDCIJK.DAT is written by EFDC to provide a mapping from EFDC (I,J,K) grid cell coordinates to WASP7 segment numbers and vertical layers (see Figure 40). The upper and lower panel shows the mapping of EFDC grid cell L=8 I=4 J=5 for the surface layer (EFDC K=10, WASP7 Layer=1) and the bottom layer (EFDC K=1 WASP7 Layer=10) to WASP7 Segment 7 (surface) and Segment 1792 (bottom).

Figure 39  EFDC and WASP7 grid cell selected to extract water temperature results.

Figure 40  WASP7SEG_EFDCIJK.DAT Lookup Table from EFDC (I,J,K) to WASP7 (Segment, Layer)

Message pops up; click OK and select the *.BMD file as the output results file for the WASP7 model

Figure 41  Select BMD file for post-processing time series results

Figure 42  Select Water Temperature for viewing in S#7 I=4 J=5 K=10.

This is a surface layer segment near the dam in the forebay shown in the grid cell map (Figure 40).

Figure 43  Water temperature for Wasp7 segment 7 at forebay, Surface layer.

Figure 44  Water temperature for Wasp7 segment 1762 at forebay, Bottom layer.

WASP7 Boundary Condition Input for 3D Lake Problem

After it has been confirmed that the EFDC-WASP7 model linkage works correctly with the default boundary values of 1.0, the user must setup the time series data for the actual boundary conditions and kinetic constants for each state variable and each boundary segment and each vertical layer for the WASP7 project.  

Model Parameters and Kinetic Coefficients Input for 3D Lake Problem

EFDC model parameters and kinetic coefficients used for the 3D Lake problem are given in the EFDC WQ3dWC.INP input files and screens for the water quality model.  The user can use the parameters and kinetic coefficients developed for the EFDC lake water quality model to assign input to the WASP7 model ‘Constants’.

 WASP7 Model Output and Post Processing Results

Output Control allows the user to write CSV files for selected model output variables. Data is written to CSV files as a flat data block file for all time intervals for all segments. CSV files are selected for a number of model output variables as shown in screenshot below.

Figure 45  Output Control selection of CSV files for 3D Lake problem

Figure 46  Output CSV files written for 3D Lake problem.

Comparison of Model Results for EFDC and WASP7 Models

Results are extracted from EFDC and WASP7 for surface and bottom layer water temperature for a grid cell in the forebay of the lake (see Figure 39). The time series comparison of model results is shown in Figure 47.  As can be seen in the plot, the results match exactly since water temperature is provided to WASP7 in the HYD file linkage.

Figure 47  EFDC and WASP7 results for water temperature at grid cell I=4, J=5, K=1 & K=10.

Comparison of Run Times for EFDC and WASP7 Models

The specifications for the computer used for the EFDC and WASP7 model runs for the 3D Lake problem are shown in Figure 48.  The run time for a 365 day simulation for the EFDC 3D lake model is given in Table 1.  Total elapsed time for the computer using a single thread was 2.0 hrs. The run time for the lake model with the same computer using 4 threads was 1.1 hrs.  The EFDC model simulated hydrodynamics, sediment transport, water quality and sediment diagenesis. The run time for the WASP7 3D lake model, shown in Table 1, was 5 hrs.  The WASP7 model used the linked HYD model for hydrodynamics and simulated sediment and water quality.

Figure 48  Specifications for Windows 7 Computer used for EFDC and WASP7 model runs

Table 1  EFDC_DSI and WASP runtimes.

Water Quality Model Run Times


Number of Layers10

Simulation Period1 year

Number of ProcessorsCPU Time Used (Hrs)Speed1
EFDC with Hydrodynamics and Water Quality12.123.0


1  Ratio of WASP run time to EFDC_DSI.
   e.g. EFDC_DSI with 4 processors is 6 times faster than WASP

End EFDC-WASP7 Linkage Documentation