dycove.sim.engines.DFM_hydro.DFMEngine

class dycove.sim.engines.DFM_hydro.DFMEngine(dfm_path, config_path, mdu_path, vegetation=None)

Engine interface for DFM hydro-morphodynamic model.

This engine:

• Loads and initializes DFM executables (DIMR + D-Flow FM BMI).

• Manages exchange of hydrodynamic and vegetation state variables though DFM-specific BMI-python wrapper.

• Ensures that required input files are present and are consistent with simulation settings.

Parameters:

• dfm_path (Path or str) – Path to the root Delft3D-FM installation directory. Might look like this: ‘C:/Program Files (x86)/Deltares/Delft3D Flexible Mesh Suite HM (2021.03)/plugins/DeltaShell.Dimr/kernels/x64’

• config_path (Path or str) – Path to DIMR configuration file dimr_config.xml

• mdu_path (Path or str) – Path to DFM MDU file.

• vegetation (VegetationSpecies or MultipleVegetationSpecies, optional) – Vegetation object passed down from the base simulation.

Notes

• Vegetation files (.xyz) required by DFM vegetation module are auto-created if missing.

• Parallel mode is not currently implemented.

__init__(dfm_path, config_path, mdu_path, vegetation=None)

Methods

__init__(dfm_path, config_path, mdu_path[, ...])
add_dll_directories(dfm_path)	Add DLL paths to env before calling BMI.
add_extforcefile_to_mdu()	Add ExtForceFile to .mdu line if it's not there (and if vegetation is active).
add_veg_module_to_mdu()	Add [veg] section to .mdu if it's not there (and if vegetation is active).
check_simulation_inputs(simstate)	Compare DYCOVE simulation time to MDU simulation time.
cleanup()	Clean up resources.
create_extforcefile()	Create .ext file in the model directory if it doesn't exist
create_veg_xyz_files()	Create required files for [veg] module to run, even if they are blank
get_cell_count()	Return number of active grid cells in the model.
get_elevation()	Return array of bed elevations at cell-centers.
get_model_inputs()	Read lines from MDU file into a dictionary
get_morphodynamic_inputs()	Read lines from morphology file into a dictionary, if mprph files exist
get_rank()	Get current parallel processor/rank.
get_refdate()	Get model reference date as a datetime object.
get_vegetation()	Return stem dens., diam., and height arrays from numerical model.
get_velocity_and_depth()	Return velocity magnitude and depth arrays at cell-centers.
initialize()	Prepare engine to run (allocate memory, read/check inputs, print start, etc.)
is_parallel()	Return True if model is running in parallel based on number of active processors.
merge_parallel_veg(OutputManager)	Merge vegetation output files across MPI subdomains into single files.
open_bmi_wrappers()	Create BMI wrapper objects for DFM and DIMR
set_vegetation(stemdensity, stemdiameter, ...)	Push vegetation arrays back into the numerical model.
step(seconds)	Advance the hydrodynamic model forward by a given number of seconds.
vegetation_file_check()	MODIFIES .mdu file if certain vegetation-related lines are not present:
write_modified_mdu()	Write modified .mdu lines back to file

add_dll_directories(dfm_path)

Add DLL paths to env before calling BMI.

Return list to retain handle and avoid accidental garbage collecting.

Note that for versions of python 3.7 and earlier, you would need to set the env variables differently:

os.environ['PATH'] = os.path.join(dfm_path, 'share', 'bin') + ";" +
                     os.path.join(dfm_path, 'dflowfm', 'bin') + ";" + ... )

add_extforcefile_to_mdu()

Add ExtForceFile to .mdu line if it’s not there (and if vegetation is active).

[external forcing] ExtForceFile = FlowFM.ext # Old format for external forcings file …

add_veg_module_to_mdu()

Add [veg] section to .mdu if it’s not there (and if vegetation is active).

Format: [veg] Vegetationmodelnr = 2 # 1: Baptist, 2: Baptist with morphology correction factor (lambda) Clveg = 0.8 # Stem distance factor, default=0.8 Cdveg = 1.1 # Drag coefficient, pulled from input veg.json file Cbveg = 0.7 # Stem stiffness coefficient, default=0.7

check_simulation_inputs(simstate)

Compare DYCOVE simulation time to MDU simulation time.

All MDU files (DFM models) will have a simulation time specifed, but DYCOVE will run DFM for a period of time based on how many veg years we want to simulate. Basically, the time specified in the MDU needs to be arbitrarily large enough so that we never run into the issue of the model stopping prematurely.

cleanup()

Clean up resources.

create_extforcefile()

Create .ext file in the model directory if it doesn’t exist

create_veg_xyz_files()

Create required files for [veg] module to run, even if they are blank

get_cell_count()

Return number of active grid cells in the model.

get_elevation()

Return array of bed elevations at cell-centers.

get_model_inputs()

Read lines from MDU file into a dictionary

get_morphodynamic_inputs()

Read lines from morphology file into a dictionary, if mprph files exist

get_rank()

Get current parallel processor/rank.

get_refdate()

Get model reference date as a datetime object. Required for now, only really used by DFM.

get_vegetation()

Return stem dens., diam., and height arrays from numerical model.

get_velocity_and_depth()

Return velocity magnitude and depth arrays at cell-centers.

initialize()

Prepare engine to run (allocate memory, read/check inputs, print start, etc.)

is_parallel()

Return True if model is running in parallel based on number of active processors.

merge_parallel_veg(OutputManager)

Merge vegetation output files across MPI subdomains into single files.

open_bmi_wrappers()

Create BMI wrapper objects for DFM and DIMR

set_vegetation(stemdensity, stemdiameter, stemheight)

Push vegetation arrays back into the numerical model.

step(seconds)

Advance the hydrodynamic model forward by a given number of seconds.

ANUGA implements this by looping with domain.evolve(), while DFM calls dimr.update().

vegetation_file_check()

MODIFIES .mdu file if certain vegetation-related lines are not present:

• Adds a filename next to ‘ExtForceFile’ if blank, creates the file too

• Adds drag coefficient from VegetationAttributes if [veg] block is present

• Adds appropriate Baptist model number (1 if no morph, 2 if morph)

• Adds [veg] block if it is not present, including drag coefficient from VegetationAttributes and appropriate Baptist model number

Creates empty text files for stem density, stem diameter, and stem height, if they don’t already exist.

The filenames are those specified in the vegetation .ext file in the model directory (e.g., “FlowFM_veg.ext”).

These files can be created beforehand if prior vegetation establishment is desired.

Otherwise, blank files are required so that DFM knows to store these variables through time.

write_modified_mdu()

Write modified .mdu lines back to file