Introduction

The main objective of this training course is to provide users with a basic knowledge of how-to setup a shellfish model and run a solution for Environmental Fluid Dynamics Code Plus (EFDC+). It will cover preparation of the necessary input files for the EFDC+ model and visualization of the output by using the EFDC_Explorer Modeling System (EEMS). Kobayashi et al. (1997) is used as a case study to illustrate the general process of developing a model from basic to complex. All files for this tutorial are contained in the EEMS website. After this training, users will be able to:

• 1. Set up a basic water quality and shellfish model from input data using EFDC_Explorer (EE) version 10.2
• 2. Visualize, extract and manage model output by EE

Model Description 

The model is set up to replicate the Kobayashi et al. (1997) data for shellfish growth in interaction with water quality described in the paper "A population dynamics model for the Japanese oyster, Crassostrea gigas". The goal of the project is to better understand the impact of vegetation to the flow in open channel.
The experiment was carried out in a 300x100 m channel as described in Shellfish Farm#Figure 1 below.

Figure 1. The shellfish farm model grid.

Data Summary

All data used in the model including inputs and comparison data are collected from the paper Kobayashi et al. (1997). These data are stored in "Data" folder from the testcase model (TC-12) available on EEMS website.

Environmental Conditions

Time series of mean water temperature, salinity and chlorophyll are shown in Shellfish Farm#Table 1 and Shellfish Farm#Figure 2 below. Water temperature ranged between 8 to 30^oC, while salinity during this period was relatively constant, ranging only between 28.4 to 31.9 ppt.

Table 1. Data use for shellfish model

Figure 2. Environments data for the study.

Biological Characteristics of Oyster Populations

Step-by-Step Guide for Building Hydrodynamics Model

This chapter will show users how to:

• Generate a new hydrodynamic model
• Assign initial conditions
• Assign BCs.

Generate a New Model

In this exercise, we will generate a new water quality model. This exercise familiarizes users with the basic interface of EE and demonstrates how to build a model from scratch. Double click on the EE10.2 icon on your Desktop or start it from the list of programs to load the model interface. Click on the New Model button to begin generating a new model, as shown in Shellfish Farm#Figure 3.

Figure 3. Cartesian Grid Generator form.

For this demo, we will generate a Cartesian grid using the following steps. From the Cartesian Grid Generator form,

• (1) Select Grid Options as Generate Uniform Grid;
• (2) Set the dimension of the uniform grid as Figure 3
• (3) In the example, leave the UTM Zone as 0 or any zone;
• (4) After filling in the parameters, click the Generate button to generate the model grid, then click on the Remove Dry button to remove cells outside the polygon. The preview of the generated grid will show in the right panel.

Note: If the grid is not suitable for your purpose, you can modify the grid parameters and click Generate again to re-generate the grid;

• (5) After the grid is generated, click the OK button to close the form and go to model settings.

After the grid is generated, the Model Control form will be displayed as Figure 4. General information about the model will be displayed that includes the model title, area, number of cells, model width, height, and model location coordinates.

Figure 4. EE Model control form.

In the model interface, click on Save to save the model.

After clicking on the Save button, a Select Directory pop-up will appear to select saving options. Before project files are saved, the grey box is empty. This is where EE project files are listed. The empty gray box shows that no files have been written yet for the study.
There are three save options:

• Full Write can be selected to save all the input files,
• Write All except Time Series Files can be selected to save all input files without the time series.
• Save Profile File Only (EFDC.EE) can be selected for saving if users have only changed formatting options in EE.

In this project, it is recommended to use Full Write option. After choosing this option, click OK to close the form and save the model.

Figure 5. Saving the model.

Assign Model Bathymetry

The next step in the model setup is to assign the bathymetry for the model domain. Assigning bathymetry refers to assigning the elevation value to each cell in the model. In this exercise, bottom elevation is a constant value at elevation of -3m (see Shellfish Farm#Figure 6).

Figure 6. Set constant bottom elevation.

Assign Water Surface Elevation

Water surface elevation can be assigned following the import of bathymetry. In this exercise, water depth of the channel is 3m, so assign WSEL equal to 0m.

Assign Boundary Condition Time series Data

From 2DH View, assign Inflow and Outflow BCs as shown in Shellfish Farm#Figure 7 below and set constant value of inflow and outflow BCs are 10 m3/s and (-10 m3/s).

Figure 7. Assign Boundary Conditions in 2DH View.

Hydrodynamics Model

From Model Control form,

1. Go to the Modules tab
2. Expand Hydrodynamics sub-tab
3. RMC on Roughness to assign Bottom roughness (Z0) as shown in Figure 8. In this demo, bottom roughness of the model is 0.01

Figure 8. Hydrodynamics – Assign bottom roughness.

From the Model Control form,

1. Go to the Modules tab
2. Expand Hydrodynamics sub-tab
3. RMC on Shallow Water to enter the Dry Depth and the Wet Depth.

This feature is required with fluctuating water levels that will leave some of the domain dry. For an area with tidal flats, the user should probably enable the wet and dry option. Although it incurs a certain computational overhead, it is necessary to obtain accurate results as it sets the minimum water depth allowed in a point before it is taken out of calculation (Dry Depth), and also the water depth at which the point will be reentered into the calculation (Wet Depth). In this exercise shallow water parameters are set as shown in Figure 9.

Figure 9. Hydrodynamics – Shallow Water setting.

Note: The Wet Depth should always greater than the Dry Depth.

Step-by-step Guide for Building Shellfish Farm Model

From Model Control form, RMC on Modules tab under Model Control form, check on the Salinity, Temperature, Water Quality and Shellfish Farm check-boxes then click the OK button to activate the salinity, temperature, water quality and shellfish farm modules as shown in Figure 10 below.

Figure 10. Active EFDC Modules.

Salinity Module

Assign Salinity Initial Condition

From Model Control form,

1. RMC on Salinity sub-tab under Modules tab to open Salinity Parameters form
2. Click on Assign button to set salinity IC
3. Under Value to Set frame, set constant value of salinity equal to 30.1 ppt
4. Click on Apply button to assign salinity IC as shown in Figure 11 below.

Figure 11. Assign Salinity IC.

Import Salinity Data Series

After assigning salinity IC, from Salinity Parameters form, click on Edit button under Time Series Data frame to import salinity data series as shown in Figure 12 below.

Figure 12. Edit Salinity Time Series Data.

After clicking on the Edit button, Boundary Data Series form will appear for participants to add/modify data series. In Boundary Data Series form, click on the Add New button to add new data series, then select Import Data button to import Salinity series data as below as shown in Shellfish Farm#Figure 13.

In the ASCII Data Import form,

1. browse to the "Data_Salinity.dat" file and select the data format as EE Dat or WQ Data;
2. Modify Import Settings parameters; then
3. click OK to import data series; Import Data form appears to allow the user to select import options from this form
4. click OK to close the form and finish importing data .

Figure 13. Import data into data series for salinity.

Note: After importing the data series; from Boundary Data Series form, participants can set the data series name by typing in Series Name blank on the top left corner.

Temperature Module

From the Model Control form, RMC on each module sub-tab under the Modules tab; a list of options will appear for the user to select, as shown in Figure 14 below. From this pop-up menu:

• (1) Go to the Settings;
• (2) Assign the Initial Conditions settings

Figure 14. General Module: Temperature setting options.

As shown in Shellfish Farm#Figure 14, RMC on the Temperature module sub-tab under the Modules tab and select the Settings option to open the Temperature Parameters form. From this form, go to the Initial Conditions tab, which allows the user to assign water temperature and bed temperature initial conditions, as shown in Figure 15 below. For water temperature initial conditions, click on the Assign button to open the assign form and set the water temperature initial conditions as a constant value of 20.0^oC

Figure 15. Temperature – Initial Conditions settings.

After assigning temperature initial conditions, go to the Boundary Conditions tab. This tab allows the user to add or modify water temperature data time series by clicking on the corresponding Edit button, as shown in Shellfish Farm#Figure 16.

Figure 16. Temperature – Boundary Conditions settings.

After clicking on the Edit button, the Boundary Data Series form will appear. To add/modify data series, import temperature (Data_Temperature.dat) data series into the model by carrying out the steps described in Shellfish Farm#Figure 13 of this document.

Water Quality Model

Kinetics Computation Settings

From Model Control form, RMC on Water Quality module sub-tab under Modules tab, select Settings option to open Water Quality form. From Kinetics tab under Water Quality module, click on Params button to select which constituents are being simulated, then click OK to save settings as shown in Shellfish Farm#Figure 17 below. (Note: From Kinetics Computation Option form, value = 1 means parameter activated, 0 means parameter is not used in the simulation).

Figure 17. Kinetics Computation Options.

After selecting the parameters used to compute, from the Kinetics tab,

• (1) Select Reaeration Options under the Water Column Kinetics frame.
• (2) Click on the Modify button to edit Kinetics Parameters; then
• (3) type in kinetic parameters
• (4) click OK to save the settings, as shown in Shellfish Farm#Figure 18 below.

Figure 18. Water column kinetics - Kinetic Parameters.

• (5) Click on the Modify button in the Use Zones for Algal Dynamics in the Water Column Kinetics frame to edit Algal Growth Parameters for the current zone; then click OK to save the settings, as shown in Shellfish Farm#Figure 19 below.

Figure 19. Algal growth parameters by zone.

Algal Setting

Go to the Algae tab, which is shown in Shellfish Farm#Figure 20 and includes two frames: the Solar Radiation for Algae frame and the Algae Options frame.
In the Solar Radiation for Algae frame in Shellfish Farm#Figure 20, click on the Source drop-down menu and select Constant.

Figure 20. Water quality – Algae tab.

Initial Conditions Settings

Go to the Initial Conditions tab as shown in Shellfish Farm#Figure 21. In the Initial Conditions frame,

• (1) Click on the drop-down menu and select Spatially Varying IC's (WQWCRST.INP),
• (2) then type in IC's values as shown in Shellfish Farm#Figure 21. After the parameters have been edited, click OK to save the settings and move to other steps.

Figure 21. Water Quality – Initial Conditions tab.

Boundary Conditions Settings

Go to the Boundary Conditions tab as shown in Shellfish Farm#Figure 22. In the Time Series Data frame,

• Click on the Edit button, the Boundary Data Series form pops up. Click Add New button to create a new time series for WQ, put name of time series as "WQ".
• There are 21 classes in the time series, the values for the Diatom Algae is from the "Data" folder and set constant value (e.g 8 mg/L) for Dissolved Oxygen, set 0 for other left classes.
• After the classes have been set, click OK to save the settings and move to other steps.

Figure 22. Water Quality – Boundary Conditions tab.

Assign Concentration Time Series Data to Boundaries

After finish import data series, go to Boundary Conditions tab, RMC on Inflow BC group under Flow sub-tab and select Edit Boundary Group to open the Flow Boundary Conditions form to link the concentration data to the boundary group. In this form, in the Time Varying Concentration tab under Boundary Group Condition frame, click on the drop-down menu of all concentration constituent and select the corresponding concentration data series to link them to the BC group as shown in Shellfish Farm#Figure 23 below.

Figure 23. Link concentration data series to BC group.

Shellfish Farm Model Setting

From the Model Control form, RMC on Shellfish Farm module sub-tab under the Modules tab, then click on Settings option to open Shellfish Farm setting form as shown in Figure 24 below.

Figure 24. Shellfish Farm Settings (1).

From Shellfish Farm form,

• (1) type 1 in Number of Shellfish Species blank to add new shellfish farm species,
• (2) then click on Edit Species button to open Shellfish form to set species characteristics
• (3) Type in species name
• (4) Under Shellfish form, go to General tab, set parameters as shown in Shellfish Farm#Figure 25 below.

Figure 25. Shellfish form – General tab.

Go to Infiltration tab, then set parameters as shown in Shellfish Farm#Figure 26 below.

Figure 26. Shellfish form – Infiltration tab.

Go to Respiration tab, then set parameters as shown in Figure 26 below.

Figure 27. Shellfish form – Respiration tab.

Go to Growth tab, then set parameters as shown in Shellfish Farm#Figure 28 below.

Figure 28. Shellfish form – Growth tab.

Go to Mortality tab, then set parameters as shown in Shellfish Farm#Figure 29 below.

Figure 29. Shellfish form – Mortality tab.

Go to Excretion tab and set parameters as shown in Shellfish Farm#Figure 30 below.

Figure 30. Shellfish form – Excretion tab.

Go to Spawning tab and set parameters as shown in Shellfish Farm#Figure 31 below.

Figure 31. Shellfish form – Spawning tab

After finish setting shellfish characteristics, click OK button to save settings and close form.
From Shellfish Farm form, go to Farm Settings tab as shown in Shellfish Farm#Figure 32 below. From this tab,

• (1) Type in 3 into Number of Farm Zone box to set 3 shellfish farm zones
• (2) Set Death Rate for each farm zone (group) in the Shellfish Farming Zones frame

Figure 32. Shellfish Farm – Farm Settings tab.

From Shellfish Farm form, go to Initial Conditions tab to assign the shell farm position and initial number of individual as shown in Shellfish Farm#Figure 33 below. From this tab, under Initial Individuals frame,

• L, J, J columns: cell index of the shellfish farm
• Zone: Farm zone index
• IC# Oyster: Initial number of individuals

Figure 33. Shellfish Farm – Initial Conditions tab.

After finish settings, click OK button to save settings and close form to move to the next steps.

Set Model Timing

From the Model Control form, go to the Timing/Linkage tab | RMC on Timing sub-tab (Shellfish Farm#Figure 34). Set the Reference Date/Time to the base year of the study. Typically, this date is the 1st of some calendar year but this is not required, and any date/time is acceptable. Users can use the J<->G button to convert from the Julian calendar to the Gregorian calendar or vice-versa. In this exercise, the base date is 1990-01-01.

Time of Start is the number of Julian days after the base date at which to start the simulation. In this exercise, set the Time of Start to 120. The Number of Reference Periods is the total simulation time as a multiple of reference periods. In this exercise, set the Number of Reference Periods to 273, where the duration of one Reference Period is 24 hours as set up in the next box.

Time step is the simulation time step. In this exercise, set the Time step as 0.1 second. The Dynamic Timestep Options subframe allows users to engage auto stepping by setting the Safety Factor, usually to a positive number less than 1. Generally, the safety factor should be less than 0.8 but some runs work with the safety factor >1 and some require a value <0.3. If set to 0 it will result in fixed time steps.

It should be noted that EFDC will use multiples of the Time Step when dynamic time stepping is on, so this value should be set to one second or less. The number of Ramp-Up Loops should also be set by users; this is the number of initial iterations for which to hold the time step to a constant value during ramp-up. The Maximum dH/dT option is ignored if set to zero, but if >0 then CALSTEP will use these additional criteria to set the dynamic timestep.

Growth Step is the minimum number of iterations for each time step before increasing DTDYN. Maximum Time Step is the maximum allowed time step in seconds. If this value is too high the model will crash. Users can refer to the EE Knowledge Base on Timing for more details.
Click on the OK button to save the settings and close form before moving forward to the next steps

Figure 34. Simulation Timing settings.

Returning to the Model Control form, expand the Timing/Linkage form, go to Linkage tab | RMC on EFDC_Linkages sub-tab (Shellfish Farm#Figure 35) to set the output frequency. In the EFDC Model Linkages form that pops up, select Link EFDC Results to EFDC_Explorer in the EFDC_Explorer Linkage tab and frame, and set the Linkage Output Frequency
In this exercise, set Linkage Output Frequency to 1440 minutes. This means EFDC will record the output every day for displaying.
Note: Smaller the output frequency, larger the output file size.

Figure 35. EFDC_Explorer Linkage setting form.

Save the model and click on Run EFDC button to run the model. The EFDC+ Run Options form will appear. In EFDC+ Run Options form, set the # OMP Cores Used is 1 in case the demo license is using. Note that the number of cores use for EFDC+ run must be smaller than the Available CPU Cores. (see Shellfish Farm#Figure 36).
Set the KMP Offset to set the threads that will be passed over when running model. For example, if KMP Offset is set to 2, that means the thread used for EFDC+ run will start from the 3^rd thread. This can be used if you are running multiple models on one machine, so the models run on different threads.
Note: If the model has existing results, please check on the Overwrite check box to run and save new results.

Figure 36. EFDC+ Run Options form.

Click on Run EFDC+ button to start running model (see Shellfish Farm#Figure 37

Figure 37. EFDC+ run window.

Step-by-Step Guide for Model Output Visualization

This chapter will show users how to:

• Visualize model outputs from the EFDC+model in EE
• Extract and manage EFDC+ model outputs

Model Output Visualization

After each simulation run finishes click on Refresh Output button in the toolbar to refresh the model output. From the 2DH View window, in the Layer Control form,

• (1) Click on the Add New Model Layer button to open 2DH View Option form which is used to select layer to add to 2DH View.
• (2) Select the parameter that users want to add to the 2DH View in Primary Groups (Shell Farm) and Parameters drop-down menus (e.g. Shell Length).
• (3) Click on the Add button to a add layer to the 2DH View (Shellfish Farm#Figure 38).

Figure 38. Visualize model output in 2DH View (1).

• After the layer Shell Length to the Layer Control, to see the change of this layer value the user follows steps below (see Shellfish Farm#Figure 39):
  • (1) Turn off the layer Bottom Elevation
  • (2) Move the Timing Slide bar
  • (3) See the value change on the legend or
  • (4) Enable the selection arrow of the Shell Length layer
  • (5) LMC on the cell then the output information of the selected cell at a specific time will be displayed on the yellow box (see Shellfish Farm#Figure 40).

Figure 39. Visualize model output in 2DH View (2).

Figure 40. Visualize model output in 2DH View (3).

Model Verification

In this exercise, shellfish species characteristics are dry weight and shell length data series collected from the paper will be used to compare with the model output for verification. From EE interface, click on Time Series Plot icon in toolbars to open Extract Time Series Data form as shown in Shellfish Farm#Figure 41 below.

Figure 41. Time Series Data Extraction.

• (1) Type in the number of cells that user want to plot to # blank (e.g. 1)
• (2) Then entering the L, I, and J index of each cell under Selected Cells frame. The user only needs to enter the L index, the IJ will be automatically updated.
• (3) The Time Series Start/Stop frame allows the user to set the time period of extracted data. As default this time period displayed as model simulation time period.
• (4) The Define Parameter to Plot frame allows the user to select parameters to plot in the same way as the Add Layer feature described for 2DH View. (e.g. Shell Length for Parameter)
• (5) Click the Left Arrow button to add a parameter; if the user wants to remove an already existing parameter, select that parameter in the Parameter to Plot frame and click the Right Arrow button to remove. The Up and Down buttons are used to change the order of layers in the Parameter to Plot frame. Note: If the user wants to modify an existing parameter or exchange it with another parameter, select that layer from the Parameter to Plot frame then click the Update button.
• (6) After finishing these settings, click the OK button to extract data. The time series data plot will be displayed as shown in Shellfish Farm#Figure 42.

Figure 42. Time series data plot: Shell Length.

From toolbar, click on Import Data Series icon, browse to data file name "Data_Shell Length.dat" in the Data folder, then click OK button to import data series as shown in Shellfish Farm#Figure 43 below. The Enter the series index to import form pops up as shown in Shellfish Farm#Figure 44, EE defines the model extracted time series is the first time series with index is 1 so the index of data time series imported will be consider as 2. In case if the users enters 1 so the model time series will be replaced with the data time series.

Figure 43. Import external data series to existing plot.

Figure 44. Enter the series index to import.

Figure 45. Modeled vs Data: Shell Length (1).

When the measured data is added, RMC on the legend to change the settings of data series (the blue line) for more clearly visualization by RMC on the legend and change data series displayed as points as shown in Shellfish Farm#Figure 46 below.

Figure 46. Edit the data plot.

Figure 47. Modeled vs Data: Shell Length (2).

The user can also do the same steps as above to compare dry weight data. The plot for dry weight is shown in Shellfish Farm#Figure 48 below.

Figure 48. Modeled vs Data: Dry Weight.