Basic Model Interface

Introduction

The Community Surface Dynamics Modeling System (CSMDS) has developed the Basic Model Interface (BMI). BMI consists of a set of standard control and query functions that can be added by a developer to the model code and makes a model both easier to learn and easier to couple with other software elements.

CSDMS provides specifications for the languages C, C++, Fortran and Python. Wflow, written in the Julia programming language, makes use of the following Julia specification, based on BMI 2.0 version.

For the BMI implementation of Wflow all grids are defined as unstructured grids. While the input (forcing and model parameters) is structured (uniform rectilinear), internally wflow works with one dimensional arrays based on the active grid cells of the 2D model domain.

Configuration

The variables that Wflow can exchange through BMI are based on the different model components and these components should be listed under the API section of the TOML configuration file of the model type. Below an example of this API section, that lists the vertical component and different lateral components:

[API]
components = [
"vertical",
"lateral.subsurface",
"lateral.land",
"lateral.river",
"lateral.river.reservoir"
]

BasicModelInterface.initializeFunction
BMI.initialize(::Type{<:Wflow.Model}, config_file)

Initialize the model. Reads the input settings and data as defined in the Config object generated from the configuration file config_file. Will return a Model that is ready to run.

source
BasicModelInterface.get_input_var_namesFunction
BMI.get_input_var_names(model::Model)

Returns model input variables, based on the API section in the model configuration file. This API sections contains a list of Model components for which variables can be exchanged.

source

Couple to a groundwater model

For the coupling of wflow_sbm (SBM + kinematic wave) with a groundwater model (e.g. MODFLOW) it is possible to run:

• wflow_sbm in parts from the BMI, and
• to switch off the lateral subsurface flow component of wflow_sbm.

The lateral subsurface component of wflow_sbm is not initialized by Wflow when the [input.lateral.subsurface] part of the TOML file is not included. Then from the BMI it is possible to run first the recharge part of SBM:

model = BMI.update(model, run="sbm_until_recharge")

and to exchange recharge and for example river waterlevels to the groundwater model. After the groundwater model update, and the exchange of groundwater head and for example drain and river flux to wflow_sbm, the SBM part that mainly determines exfiltration of water from the unsaturated store, and the kinematic wave for river - and overland flow can be run as follows:

model = BMI.update(model, run="sbm_after_subsurfaceflow")

BasicModelInterface.updateFunction
BMI.update(model::Model; run = nothing)
• run = nothing: to update a model partially.