Example - Simple beach and tide channel (Delft3D FM)

This example corresponds to the Python file run_tide_channel.py located in the examples/DFM/tide_channel/ directory, along with supporting input files. This example uses the same bathymetry and vegetation inputs as the corresponding ANUGA example. That example includes some more discussion on DYCOVE’s vegetation logic and inputs than this example does, and users are always encouraged to read the background documentation for full exposure to DYCOVE concepts.

This example consists of a simple, symmetrical beach slope with a channel that bisects the dune and connects to a lagoon. A simple structured mesh is developed using Delft3D’s RGFGRID, one that mimics the mesh developed for the ANUGA version of this example. A tidal boundary condition is imposed on the left (ocean) side, that propagates through the channel and fills the lagoon behind the dune. A vegetation species, loosely based on Salicorniaspp. (pioneer species, first life stage) and Spartina anglica (second life stage), is added to the model via a set of attributes defined in the file veg1.json. After the simulation is finished, we can inspect a variety of 2-D model results using ModelPlotter.

This example does not consider morphology. Please see this example for a model that has morphology turned on.

Run the Model

The following import statement forms the basis of all DYCOVE-DFM coupling simulations:

from dycove import VegetationSpecies, DFM_hydro

To run Delft3D FM, you will need to create and export your model outside of the coding environment. After creating a Delft3D model using Delta Shell, export the model as DIMR:

  • Alt-click on the model name in the Project tree

  • “Export…” → “DIMR configuration”

This will create an .xml file at the same level as a directory called dflowfm/, which contains the .mdu file inside. Next, identify the path to your Delft3D FM code library, which probably looks something like the path shown below:

from pathlib import Path
config_file = 'dimr_config.xml'
mdu_file = Path('dflowfm/FlowFM.mdu')
DFM_DLLs = Path('C:/Program Files (x86)/Deltares/Delft3D Flexible Mesh Suite HM (2021.03)/plugins/DeltaShell.Dimr/kernels/x64')

To turn on the internal vegetation module in Delft3D FM, we must create an additional forcing .ext file and add a new block in the .mdu file with the [veg] heading. DYCOVE handles this automatically, as long as you supply a vegetation species to your DYCOVE model.

After setting up the model and identifying the model file paths, DYCOVE-DFM models are run in much the same way as DYCOVE-ANUGA models. The only difference is the call to the hydrodynamic engine, which in this case is DFM:

veg_1 = VegetationSpecies("veg1.json")
HydroModel = DFM_hydro.DFM(DFM_DLLs, config_file, mdu_file, vegetation=veg_1)
HydroModel.run_simulation(3, sim_time_unit="eco-morphodynamic years")

Plot the Results

DFM map output is saved in the dflowfm/output/FlowFM_map.nc file (or whatever the model name is, if not FlowFM). DYCOVE output is saved in .npz files, with one file per vegetation cohort per ecological time step. For a list of outputs stored with each cohort, see VegCohort.

Plot 2-D maps of various model quantities over time using ModelPlotter. For example, we can plot vegetation stem heights over the entire 21-day (hydrodynamic time) simulation period.

from dycove import plotting
plotter = plotting.ModelPlotter(
   simdir = Path("."),
   #quantity = "Velocity",
   quantity = "Stem Height",
   plot_times = {
      "plotHR_0": 0*24.,
      "plotHR_f": 28*24.,
      "mapHR_int": 1,
      "plotHR_int": 1,
   },
   cmap_lims = {
      "Bathymetry": (-0.5, 0.5),
      "Velocity": (0, 0.3),
   },
   )
plotter.run()

This plotting code is located in the same example directory at examples/DFM/tide_channel/plot_tide_channel.py, where there are additional comments on how to use the code, as well as more ideas for quantities to plot.