MF6 version compatibility

[deltamarnix]

Problem Description

Flopy should aim for maximum compatibility with MF6, regardless of the MF6 version.

This relevant for e.g. debugging a model received from an external partner who has not adopted the most recent version.

Definition (dfn) files are used to generate source code in both MODFLOW 6 and flopy. Currently we do this at release time. This means that flopy versions are hard-linked to MODFLOW 6, unless the developer utilities for code generation are used. Incompatibility issues will arise when trying to load a MODFLOW6 model with the wrong version of flopy.

The user either needs to downgrade their flopy version or use the developer utilities when they want to use an older version of MODFLOW 6.

Proposal

The release cycle of flopy and MODFLOW should be split, so that it is possible to release new MODFLOW6 versions without releasing a new flopy, and fixing flopy issues without having to patch them on all earlier released flopy versions.

We can achieve this concept by changing the installation process for users and making some minor changes in already existing functions. Instead of generating the source code packages from the dfn files during development time and storing the dfn files in both MODFLOW and flopy, the MODFLOW repository should be the leading truth of the dfn files.

The proposal is to distribute the dfn files along with MODFLOW6, so that the get_modflow() function also downloads the dfn files. When the dfn files are downloaded, the code generation can kick off to install those extra python classes in the local environment of the user.

sequenceDiagram
actor User
User ->> pip: pip install flopy
User ->> flopy: flopy.get_modflow("6.1.3")
flopy ->> modflow_server: download modflow 6.1.3
flopy ->> flopy: flopy.code_generation()

Loading

I believe that this proposed solution can already be performed within the current FloPy code base, as the get_modflow() functionality already exists. The only thing that would change for the user, is that they need to call this functionality, or otherwise the mf6 package will not yet be available in their python environment.

Advantages

The proposed solution makes it possible to separate releases of MODFLOW from flopy, giving the opportunity to perform flopy patches and add features without having to release a new version of MODFLOW. And to update MODFLOW without having to release a new version of flopy.

It also gives the opportunity for users to switch between MODFLOW versions without having to install a different version of flopy, they would only have to call get_modflow() again in order to set up their flopy environment correctly.

There would only be a single source of truth for the dfn files, so no dfn duplication in multiple repositories.

Disadvantages

I believe that MODFLOW input files do not contain a version number in their configuration or metadata. That makes it hard for the flopy code to validate if it is possible to load the input files or not. Adding such information would be a great addition, as we could then return error messages when the flopy generated code does not match the model to load from disk.

[deltamarnix]

A similar proposal was done by @wpbonelli here: modflowpy/flopy#1970 (comment), but the effort was stalled I believe.

[wpbonelli]

@deltamarnix I lightly edited your problem description. Flopy provides a utility to regenerate the mf6 layer. It's not generally necessary to downgrade to work with a different version of MF6, provided the version is "recent". The further back you go, the more likely it is that something deep-down has changed, in which case downgrading may be needed.

I think the core elements of the proposal are

• keeping DFNs in MF6 only
• distributing DFNs with MF6

With this flopy can auto-sync to whatever version of MF6 it installs, provided the user installs MF6 with flopy. But I don't think we can guarantee that. Maybe consider keeping MF6 and flopy on the same release schedule? It's a bit tiresome, but it will "just work" for those people who for whatever reason get an mf6 binary some other way and expect the latest flopy to support the latest mf6.

We might also consider not only distributing MF6 with DFN files, but giving MF6 the ability to emit them? Then flopy could just ask MF6 for its version and spec. This would be handy not only for code generation, removing the need for simultaneous releases, but also to verify that a given executable is compatible both with a given flopy and a given set of input files.

Re: adding an MF6 version number to input files, if we were to do that, what would mf6 / flopy do if it detected a version number different from the expected? Presumably warn but still try to load?