The manuscript “UniFHy v0.1.1: A community modelling framework for the terrestrial water cycle in Python” presents a code framework for the coupling of distributed large scale models of the hydrological cycle – at least, this is how I understand the manuscript. The scope and the topic of the manuscript is not well defined and the basic motivation to create the code is not well explained. The introduction mentions a couple of existing modular modelling approaches but they do not really categorize the existing approaches and, most important, the introduction misses a section explaining what problems are not solved with the status quo and which benefits are created by the presented software.
From the whole manuscript I understand that UniFHy is a coupling interface definition, like OpenMI, OASIS-MCT / Open-PALM etc. that does not include solvers and / or model equations like the cited modular Hydrology tool kits (FUSE, SuperFLEX, CMF, SUMMA and RAVEN) or LandLab. However, the interface is extremely limited in scope and it is not well explained, why such an interface is needed. My own experience is that any Python compatible API to model internals is sufficient for effective code coupling. Discussions about model boundaries (eg. is root distribution subsurface or vegetation model component) is the most important part of model coupling from my experience. This discussion is missing in the manuscript and hindered by the interface. For my coupling studies such an interface would have been a hindrance and not an asset – even if Landsystem models are involved (CLM, LPJ-GUESS) (Bendix et al., 2021).
The manuscript needs a complete rewrite to address the question, what unifhy really provides, what the status quo is missing. Large parts of the manuscript can be omitted (future development, case study in its current form), or need a complete rewrite focusing on the main questions (introduction, description of the framework, usage). I would therefore recommend to reject the manuscript in its current form.
The major problem is: the authors have not really decided which of two possible papers they want to write:
a) if the m/s is about the interface only, the need and the practical features of the interface and existing helper functions (eg. grid transformation, parallel memory allocation) should be presented. The status quo needs to be presented in a structured form
b) the presentation of the case study is to short and limited for a story of its own: The results are not discussed and the framework in its current form can be used for more variants then just the three presented.
The m/s is a mix of both papers, but none of the versions is presented in adequate form. There are also code quality problems, like the use of underscore as a prefix in the pubic (user / contributor facing) interface.
Some specifc issues:
L 40: CMF is not pure bucket style, but allows a wide range between physical and conceptua models – more physics than RAVEN (eg. Richards equation).
L 43: “However, refactoring existing land surface models using these frameworks is not trivial” – citation needed. Counter examples for CMF coupling with CLM and LPJ-GUESS (Bendix et al., 2021). Using the proposed interface would be harder.
L 44: OpenMI is something completely different from the modular hydrology toolboxes, it is more like the following paragraph
L 54: What is wrong with the status quo? Where are the gaps? Why don’t you use an existing coupler or none at all?
L 63: What is the “integrated coupling philosophy”? Which of the mentioned modular modelling approaches follow that also? What are the specific features of UnifHy?
2 Description of the framework
L 85ff: Citation needed - why do you thnk a one size fits all solution (“skilfuly yet pragmatically”) exists? The “intentionally limited” “degrees of freedom offered” makes the proposed interface in my eyes anything else than “unified”, but rather specialized for the purpose of this team and the models used in this study. What about energy or solute fluxes?
L98ff: Again, the term “integrated coupling approach” remains unexplained. The rational for this structure is not explained
L136: “These contributions can be implemented purely in Python, but can also rely on Fortran, C, or C++ programs called by interface middleware.” From my experience, creating any interface is far from trivial. Using any interface for couling is simple.
L154: “Contributors need not handle basic functionalities such as memory allocation nor input/output operations, as these are handled by the framework” Is this the main service of the provided software? How does the framework handle this? Why are the functions for memory allocation and input/output operations not explained? What are the limitations of the framework as is?
3 Usage of the framework
The whole section does not really follow a user story and is hard to follow. The code examples and descriptions seem to follow an example setup that is not yet described. The code examples lag explanations and comments.
4 Contribution to the framework
This section would benefit of less code and more story.
5 Case studies using the framework
The results are not discussed and the setup (and its rational) is not well explained. Instead of focusing on the “unified” interface the m/s could present the results from this multi-model exercise as a scientific paper and mention, that more is possible using the interface.
6 Future developments
This section is far too long for things not yet existing. A short outlook is appropriate but two manuscript pages concerning not yet existing features is clearly too much – the future is always the most difficult time to predict, as we modellers know.
Bendix, J., Aguire, N., Beck, E., Bräuning, A., Brandl, R., Breuer, L., Böhning-Gaese, K., de Paula, M. D., Hickler, T., Homeier, J., Inclan, D., Leuschner, C., Neuschulz, E. L., Schleuning, M., Suarez, J. P., Trachte, K., Wilcke, W., Windhorst, D., and Farwig, N.: A research framework for projecting ecosystem change in highly diverse tropical mountain ecosystems, Oecologia, 195, 589–600, https://doi.org/10.1007/s00442-021-04852-8, 2021.