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 DFM execution is supported through MPI domain partitioning.

• Parallel vegetation output is reconstructed using DFM global cell IDs and the native merged DFM map ordering.

__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.
configure_library_paths()	Configure DFM and DIMR library paths for the current OS.
configure_mpi()	Configure MPI state once for serial or parallel DFM execution.
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
gather_partition_mappings()	Gather rank-local global-cell and ownership mappings on rank 0.
get_bmi_global_cell_ids(n_cells, rank)	Return DFM global cell IDs in BMI-local array order.
get_cell_count()	Return number of active grid cells in the model.
get_elevation()	Return array of bed elevations at cell-centers.
get_merged_map_cell_order(owned_global_ids)	Return global cell IDs in the native merged DFM map ordering.
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_owned_global_cell_ids(partition_maps)	Return unique global IDs for physical cells owned across all ranks.
get_partition_net_file(rank)	Return the rank-local mesh path from the partition MDU NetFile.
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.
load_partition_mapping()	Build local DFM cell ownership/global numbering in BMI order.
map_partition_ownership(net_globalnr, ...)	Map partition ownership metadata into DFM BMI-local order.
merge_parallel_cohort_file(OutputManager, ...)	Merge one cohort output across all DFM MPI partitions.
merge_parallel_dfm_map()	Merge rank-local DFM map files into one global map file using Deltares' native dfmoutput mapmerge utility.
merge_parallel_veg(OutputManager)	Merge rank-local DYCOVE vegetation files into global files.
open_bmi_wrappers()	Create BMI wrapper objects for DFM and DIMR
parallel_barrier()	Synchronize DFM MPI ranks.
prepare_output_reconciliation()	Prepare parallel DFM output for global vegetation reconstruction.
raise_parallel_root_error(error)	Broadcast a rank-0 error to all MPI ranks and raise it consistently.
read_partition_cell_metadata(net_file)	Read global cell IDs and ownership from a partition mesh.
set_vegetation(stemdensity, stemdiameter, ...)	Push vegetation arrays back into the numerical model.
setup_parallel()	Configure DIMR for MPI parallel execution.
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.

configure_library_paths()

Configure DFM and DIMR library paths for the current OS.

configure_mpi()

Configure MPI state once for serial or parallel DFM execution.

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

gather_partition_mappings()

Gather rank-local global-cell and ownership mappings on rank 0.

get_bmi_global_cell_ids(n_cells, rank)

Return DFM global cell IDs in BMI-local array order.

get_cell_count()

Return number of active grid cells in the model.

get_elevation()

Return array of bed elevations at cell-centers.

get_merged_map_cell_order(owned_global_ids)

Return global cell IDs in the native merged DFM map ordering.

The merged map order is authoritative for reconstructed DYCOVE vegetation output.

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

static get_owned_global_cell_ids(partition_maps)

Return unique global IDs for physical cells owned across all ranks.

get_partition_net_file(rank)

Return the rank-local mesh path from the partition MDU NetFile.

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.

load_partition_mapping()

Build local DFM cell ownership/global numbering in BMI order.

Global cell IDs are obtained directly from the D-Flow FM BMI variable iglobal_s. Ownership information is read from this rank’s partitioned NetCDF mesh and reordered into BMI-local order.

map_partition_ownership(net_globalnr, net_domain, n_cells, rank, net_file)

Map partition ownership metadata into DFM BMI-local order.

merge_parallel_cohort_file(OutputManager, fname, partition_maps, global_to_output, n_global)

Merge one cohort output across all DFM MPI partitions.

merge_parallel_dfm_map()

Merge rank-local DFM map files into one global map file using Deltares’ native dfmoutput mapmerge utility.

This runs only on rank 0. The merged map provides the authoritative global DFM face ordering for reconstruction of DYCOVE vegetation output.

merge_parallel_veg(OutputManager)

Merge rank-local DYCOVE vegetation files into global files.

Uses the DFM BMI-order global-cell mappings collected during initialization. Only cells owned by each MPI rank are inserted into the reconstructed global arrays; ghost-cell copies are ignored.

open_bmi_wrappers()

Create BMI wrapper objects for DFM and DIMR

parallel_barrier()

Synchronize DFM MPI ranks.

prepare_output_reconciliation()

Prepare parallel DFM output for global vegetation reconstruction.

All ranks finish writing partition-local output before rank 0 reconstructs the global DFM map. The merged map defines the authoritative global-cell ordering used by merge_parallel_veg().

raise_parallel_root_error(error)

Broadcast a rank-0 error to all MPI ranks and raise it consistently.

This prevents non-root ranks from waiting indefinitely at a later synchronization point if a rank-0 output-reconstruction step fails.

read_partition_cell_metadata(net_file)

Read global cell IDs and ownership from a partition mesh.

set_vegetation(stemdensity, stemdiameter, stemheight)

Push vegetation arrays back into the numerical model.

setup_parallel()

Configure DIMR for MPI parallel execution.

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