iMOD User Manual version 5.2 (html)

A.4Coupling MODFLOW 6 and MetaSWAP


The last year Deltares worked in collaboration with the USGS on the code of MODFLOW 6. Within this collaboration a coupling method is implemented in the code of MODFLOW 6 based on Basic Model Interface (BMI) (Hutton et al., 2020). This change is part of the official MODFLOW release (v6.2.0) of the USGS. The coupling is tested with the unsaturated zone model MetaSWAP of Wageningen Environmental Research (WEnR). The BMI coupling within MODLFOW 6 can also be used to couple other models to MODFLOW 6. The coupling is in an experimental phase.

A.4.2Coupling components

For the coupling between MODFLOW 6 and MetaSWAP several different software components are developed.


Figure A.5: The different components used for the coupling MODFLOW 6 and MetaSWAP.

A.4.3BMI, XMI en xmipy

For the coupling between MODFLOW 6 and MetaSWAP the Basic Model Interface (BMI) (Hutton et al., 2020) concept is used. BMI is a set of functions that, when added to the calculation code, allow data to be exchanged between models via the working memory on a standardized way. This makes it easier to link models. BMI is a standard used by many models, developed and maintained by the Community Surface Dynamics Modeling System group (CSDMS) in Boulder, Colorado. The great advantage of this standardization is that it makes it easier to reuse parts of software. Moreover, BMI language is "agnostic"; this means that model codes can be linked in a programming language of your own preference.

MODFLOW and MetaSWAP must be linked within the outer iteration loop of MODFLOW. The current BMI does not provide the fine-grained control to make this possible. The concept of the XMI, the eXtended Model Interface, was developed for this purpose, which was subsequently implemented in the MODFLOW 6 and MetaSWAP code. At the same time a python package has been created that extends the bmipy developed by CSDMS with this XMI concept: xmipy. The code and documentation is available on gitub (


For the coupling between MODFLOW 6 and MetaSWAP a new program is developed: imod_coupler. This program is the glue between the models and allows the user to couple MODFLOW 6 to MetaSWAP.

The imod_coupler works as follows. At the beginning of each iteration, MODFLOW 6 provides the phreatic heads to MetaSWAP. MetaSWAP then calculates a new storage coefficient, a groundwater extraction for irrigation, and a groundwater replenishment. These are redirected to MODFLOW 6, which then recalculates its rising heads, after which the next iteration can begin. This numerical problem is solved iteratively until the heads and fluxes in MODFLOW 6 no longer change.

For development purpose this program is developed in python and can be used as a python packages and as a executable (imodc.exe). The choice of python does not influence the total computational time because MODFLOW 6 and MetaSWAP determines the calculation time. The imod_coupler can be adjusted for coupling to other models than MetaSWAP. More information and documentation is available on github (

Table A.4: Number of seconds spent in the different components of the coupling for a test model. The test model consists of 3 layers, 1000x1000 cells and 5 time steps. The used processor is a Intel Core i5-7200U CPU 2.50GHz.


Time (s)

Percentage (%)













The imod_coupler is the main program which a user should start during a coupled modelrun (see next paragraph).


With the implementation of MODFLOW 6 in iMOD the standard iMOD RUN file is no longer supported. Instead of the runfile a project file (*.prj) can be used. Using the project file, model input files are prepared for a user-defined area, for the defined resolution and model period. The translation of the data files and the upscaling and downscaling is done by iMOD. When the MetaSWAP package is also activated in the project file, the MetaSWAP input and the correct coupling files for MODFLOW and MetaSWAP are also created using the iMOD batch RUNFILE function.

For the coupling between MODFLOW 6 en MetaSWAP additional files are necessary. The coupling files are created automatically when using the iMOD batch function RUNFILE (see section 8.7.5).

More information about these files can be found on:

To run a MODFLOW 6 model coupled with MetaSWAP the coupling software imod_coupler should be used. The imod_coupler is the main program which a user should start during a coupled modelrun. This programme uses a configuration file (*.toml file) which contains the locations of the *.dll files of the computational codes and the model input. An example of a TOML file is given below. The executables and *.dll files are part of the iMOD installation.


Figure A.6: Example of an imod_coupler configuration file (*.toml file).

An example of a batch script to run a coupled model is given below. First create the MODFLOW 6 and MetaSWAP input files, including the additional coupling files. with the iMOD batch function RUNFILE. Than run the imod_coupler together with the TOML configuration file.


Figure A.7: Example of a batch file to run a MODFLOW 6 and MetaSWAP model.

The output of the MODFLOW 6 model is defined in standard MODFLOW format. Conversion to idf files for the iMOD GUI is possible with the help of an iMOD batch tool or python routines that are available in the python libary imod-python ( developed by Deltares.