FINAM &ndash; is not a model (v1.0): a new Python-based model coupling framework

Müller, Sebastian; Lange, Martin; Fischer, Thomas; König, Sara; Kelbling, Matthias; Leal Rojas, Jeisson Javier; Thober, Stephan

doi:https://doi.org/10.5194/gmd-2024-144

Preprints

https://doi.org/10.5194/gmd-2024-144

Preprints

Submitted as: development and technical paper

20 Aug 2024

Submitted as: development and technical paper |

| 20 Aug 2024

Status: this preprint is currently under review for the journal GMD.

FINAM – is not a model (v1.0): a new Python-based model coupling framework

Sebastian Müller, Martin Lange, Thomas Fischer, Sara König, Matthias Kelbling, Jeisson Javier Leal Rojas, and Stephan Thober

Abstract. In this study, we present a new coupling framework named FINAM (short for "FINAM Is Not A Model"). FINAM is designed to facilitate the coupling of independently developed source codes and enable seamless model extensions by wrapping existing models into components with well-specified interfaces. Positioned between a coupling library and a full-fledged framework, FINAM allows users to couple preexisting wrapped models or to build models from scratch using its components. The primary goal of FINAM is to leverage the power of Python, facilitating rapid prototyping and ease of use for complex workflows while offloading computationally intensive parts to native models. FINAM supports bidirectional coupling of spatial models, enabling fast in-memory data exchange, and provides a consistent interface for flexible coupling. The main assumption for a successful coupling is that every model operates with a time loop at its core. This design of FINAM allows for straightforward model extensions written in Python without altering the original model source code. Python's robust interoperability features further enhance FINAM's capabilities, allowing interfaces with various programming languages including Fortran, C, C++, Rust, and others. This paper describes the main principles and modules of FINAM and presents example workflows to demonstrate its features. These examples range from simple toy models to well-established models like OpenGeoSys and Bodium covering features like bidirectional dependencies, complex model coupling, and spatio-temporal regridding.

Received: 23 Jul 2024 – Discussion started: 20 Aug 2024

Publisher's note: Copernicus Publications remains neutral with regard to jurisdictional claims made in the text, published maps, institutional affiliations, or any other geographical representation in this preprint. The responsibility to include appropriate place names lies with the authors.

Download & links

Sebastian Müller, Martin Lange, Thomas Fischer, Sara König, Matthias Kelbling, Jeisson Javier Leal Rojas, and Stephan Thober

Status: final response (author comments only)

CC1:
'Comment on gmd-2024-144', Knut Klingbeil, 22 Aug 2024

The motivation of this new (yet another another...?!) coupler should be more concise. The raised disadvantages of the existing libraries/frameworks are partially far-fetched. In the context of ESMF, the authors incorrectly state "The disadvantage of this approach is that it is not applicable for independently developed models with existing code bases because the framework is used to build model systems from scratch. Here, we aim to overcome the mentioned disadvantages of the existing couplers by developing a new coupling framework framework named FINAM (short for "FINAM Is Not A Model"). FINAM allows us to couple independently developed codes and enable seamless model extensions by wrapping existing models in components with a well-specified interface." The latter is exactly the aim of ESMF! Moreover, the authors should not ignore the latest generations of NUOPC and ESMX functionality. Finally, the authors contradict themselves be concluding "Additionally, making a model ready for FINAM can require a significant investment of time and resources. Although Python facilitates rapid prototyping and

development, preparing a model to comply with FINAM’s requirements can be a demanding process, particularly for legacy systems or highly complex models, depending on their internal structure. If the code base is well written and its functionality is encapsulated in logical units, such as executing the time loop as a separate subroutine, the Python interface is reasonably easy

to implement."
In my opinion, the authors can use their coupler for some minimalistic applications, but due to the missing focus on parallelisation, their coupler will never be used for serious real world coupled model systems (in contrast to ESMF and OASIS). So I have to ask: Is there any new approach or functionality that is of relevance for the community and deserves publication?

Citation: https://doi.org/10.5194/gmd-2024-144-CC1
- CC3: 'Reply on CC1', Stephan Thober, 17 Sep 2024
  
  Dear Knut Klingbeil,
  We would like thank you for your time and effort reading our manuscript. Based on your comment, we double checked the ESMF description and agree with you that ESMF is indeed able to couple independently developed codes. Still, notable differences between ESMF and FINAM exist. ESMF is domain specific and Fortran is used for the interface. These decisions limit the range of potential users. FINAM is not targeted at a specific domain and is more accessible as Python is used to couple different components.
  Regarding NUOPC, the NUOPC website states: "NUOPC partners are working toward a common model architecture - a standard way of building models - in order to make it easier to collaboratively build modeling systems", which is what we mean by "not applicable for independently developed models with existing code bases because the framework is used to build model systems from scratch". We will refine our manuscript based on these findings.
  Finally, the authors contradict themselves be concluding "Additionally, making a model ready for FINAM can require a significant investment of time and resources. Although Python facilitates rapid prototyping and development, preparing a model to comply with FINAM’s requirements can be a demanding process, particularly for legacy systems or highly complex models, depending on their internal structure. If the code base is well written and its functionality is encapsulated in logical units, such as executing the time loop as a separate subroutine, the Python interface is reasonably easy to implement."
  Regarding your comment above, we will rephrase this section to make it more clear under which conditions and for which steps increased efforts may be necessary. We think that, in comparison to other couplers, creating a component from an existing model is easy and fast. Contrary to ESMF, which requires the implementation of "Coupler Components" to set up a coupling, no further effort is required once components are implemented and coupling scripts are short and easy to write. Adapters can be used flexibly to integrate data in time or remap it in space.
  In my opinion, the authors can use their coupler for some minimalistic applications, but due to the missing focus on parallelisation, their coupler will never be used for serious real world coupled model systems (in contrast to ESMF and OASIS). So I have to ask: Is there any new approach or functionality that is of relevance for the community and deserves publication?
  As stated in the outlook section, parallelisation using MPI is the next bigger feature planned for FINAM. Even without MPI, we definitely see "serious real world" applications of FINAM. The usefulness of models is by no means governed by their spatial scale, runtime complexity or memory demand. While in climate or earth systems modelling, models may be developed and refined over long time spans, this is not the case in all fields. With FINAM, we also want to allow for rapid development, coupling and experimentation across disciplines without much developer effort.
  Yours sincerely,
  Stephan Thober on behalf of all authors
  
  Citation: https://doi.org/10.5194/gmd-2024-144-CC3
CC2:
'Comment on gmd-2024-144', Reed Maxwell, 04 Sep 2024

I stumbled across this manuscript by accident, was intrigued by the title and abstract and ended up reading the entire preprint with interest. I have a long history of developing models, coupling models, and engineering coupling strategies. This is just a comment, by no means a review, as I am not a referee assigned to this manuscript, but I found this work to be interesting and novel. The modeling landscape is littered with coupling approaches but there are very few well thought out frameworks. Given the ubiquitous nature of Python and how rapidly it can facilitate development, the authors present an interesting approach. I appreciated the range of examples and how well maintained the code is. I navigated to the GitLab repo and was impressed by the level of activity and organization. While aspects like parallelism and development of model interfaces remain challenges, no framework is ever finished and there is always work to do. In my opinion this work was novel and appeared publishable on its own merits regardless of the next steps. I applaud the authors for their effort to develop, document and share this model coupling framework.

Reed Maxwell
Princeton University

Citation: https://doi.org/10.5194/gmd-2024-144-CC2
- CC4: 'Reply on CC2', Stephan Thober, 17 Sep 2024
  
  Dear Reed Maxwell,
  we want to thank you for taking the time to read our manuscript and look at our codebase. Our aim is to provide a documentation and step-by-step guide for users of FINAM. We think that this is a very important aspect of FINAM as users might have very different levels of expertise and are not necessarily familiar with coupling frameworks. This is a notable difference to developers of Earth System Models for which a range of coupling frameworks exist (like ESMF and OASIS).
  Your sincerely,
  
  Stephan Thober on behalf of all authors
  
  Citation: https://doi.org/10.5194/gmd-2024-144-CC4
RC1:
'Comment on gmd-2024-144', Moritz Hanke, 25 Sep 2024
Disclaimer:
I am the main developer of YAC (a coupling library mentioned in this paper) and

involved in the coupling infrastructure in the ICON model. In addition,

this review was written after receiving addition information from the main

authors of this paper.
Summary:
In their paper the authors introduce a newly developed coupling framework

(FINAM). Its design concepts are explained comprehensibly and in detail. They

are also compared to existing coupling solutions like ESMF or OASIS. In

addition, examples on how this new framework can be used in practice are

presented.
I think FINAM provides an easy entry to coupling for users that are

inexperienced in this field. It is also particularly suited for certain

use-cases. Therefore it is a contribution to the community. However, the paper

does not make it clear enough what these use-cases are. After a major revision,

I would consider it for publishing.
General remarks:
In the introduction, as the motivation for the development of FINAM, common

coupling strategies and examples for their implementations are presented.

Additionally, their disadvantages are listed. However, what the authors fail to

do is to start by giving an overview on the main use-case for which FINAM is

currently built for and the potential target users, which is different

from compute intensive and highly-parallel weather and climate model, which

OASIS and YAC are used for. If this had been established first in the

introduction, the characteristics of the various coupling solution could listed.

Based in this, the need for the newly developed FINAM could be explained.
For example library based coupling solutions like OASIS and YAC are used for

highly-parallel model with long histories and large code basis. A restructuring

of these models for coupling framework would be very difficult and is often not

supported by the associated communities. They usually have fixed time step

length, and therefore the support for variable time step length is not a

requirement.
Because this is an important information for many readers, it should be stated

somewhere at the beginning of the paper, that currently FINAM runs in a single

process and does not support MPI.
For many coupling setups the performance penalty of the coupling is an

important factor, which is why publications related to coupling solutions often

include respective measurements. However, in your use-case this does not seem

to apply. This could be a useful information to the reader.
Other coupling solutions you could take into account for your state-of-the-art

analysis are:
bmi (https://bmi-spec.readthedocs.io/en/latest/)

OpenPALM (https://www.cerfacs.fr/globc/PALM_WEB/index.html)

preCICE (https://precice.org/)

Unrelated to the paper:
You use the “datetime” class from Python, which uses the Gregorian calendar.

Can you exclude the possibility that FINAM users may require a different

calendars at some point?
Specific comments:
Abstract:

You should probably include a hint on the main use case for FINAM, because it

might be different for other coupling solutions like ESMF or OASIS. Because

this is an important information for potential readers of this paper.
L3: "independently developed source codes"

The development of two models can depend of each other (one does not work

without the input from the other) and can even have a partially shared code

base (e.g. ICON atmosphere and ICON ocean) but still require coupling. Maybe

try to find a better wording.
L13: add reference for OpenGeoSys and Bodium
Introduction:

Add description of targeted use case and the characteristics of applications

FINAM is supposed to be used for. This is only slightly hinted at by

"environmental models". A comparison of the characteristics of these models

compared the ones used in weather and climate models (for which ESMF, OASIS,

and YAC are used) would greatly improve the understanding of the evaluation

done in the introduction.

In case you are interested, there are publications by Sophie Valcke in which

she compares the coupling library and framework approaches.
L21: "independently developed models"

(see above)
L21: "three main approaches to exchange data"

You could also add the option to include one model into another by mergind

the source code or through a plugin-mechanism. In this case the data is

exchanged directly through routine arguments between the models.
L25: "infeasible"

maybe "impractical"
L28: "infeasible"

duplication
L35: "Shrestha et al., 2014"

The work in this paper used OASIS3 and not OASIS3-MCT, which makes a

significant difference especially in respect to performance.
L38: "A disadvantage of these libraries [...]. This is an error-prone approach."

That depends the perspective of the evaluation and the experience of the

users. So in your case, this may be an inadequate approach for coupling.
L41-24: "The maintenance of the data exchange..."

That depends on the software design of a model. From my experience users of

the uncoupled ICON atmosphere never have to deal with any coupling-related

source code or configuration parameters.
L49-51: "The disadvantage..."

Even if my experience with ESMF is very limited, I do not agree with this

statement. There is an example where ESMF was used for the coupling of ICON

(see https://gmd.copernicus.org/articles/14/4843/2021/).

Characteristics of ESMF that might make it unsuitable for your application is

potentially its size and the complexity of the interface. Having the control

over the development of the coupling software can also be a significant

advantage.
L52-65: whole paragraph

Based on my previous comments, this paragraph does not make it clear why there

is a need for FINAM and how it is different from other solution. It lists a

couple of desired features that, depending on your point of few, might also be

fulfilled by other software.
L55-56: "FINAM is located in the middle between a coupling library and a

coupling framework"

I do not understand why FINAM is located between a coupling library and

framework. What makes its approach significantly different from the framework

approach of ESMF?

Btw:

Recent developments in YAC allow the relatively easy implementation of

a wrapper for a component that was originally written for coupling

framework. From my point of view, this somewhat blurs the clear line

between coupling libraries and frameworks.
L75: "makes it easy for developers to wrap existing models"

This is contradicted by L364-365 ("making a model ready for FINAM can require

a significant investment of time and resources.".

Especially for existing large code bases this can be an extensive task.
L76-77: "Consequently, components can be developed in isolation without

detailed knowledge of the potential coupling partner models"

Depending on the complexity of a model, this can also be true for the

coupling library approach. And actually is one of the ideas for a coupling

library, unfortunately in practice this is often not the case.
L79-80:

Here you list again coupling approaches including the one I proposed to be

added to L21.
L81-89: whole paragraph

This paragraph compares FINAM to other approaches:
FINAM does require very little framework-specific code
Are you sure that in your examples, that same

could not be said for ESMF?

Looking at code of the Hargreaves-Samani example, the amount of

framework/library-specific code would be more or less the same, if

a similar component would have been coupled using YAC.

only minimal knowledge of the model is required
This is a very broad statement. (e.g. remapping between grids is

handled by YAC automatically, but unit conversion and handling of

varying time steps is not).

btw. the selection of the regridding method depends on the properties

to be exchange. And by experience I can assure you that you do not want

an automatic selection if the grids do not match.

using Python
this is not a unique feature

Figure 1: repetition of ", then"
L95: repetition of "handled by"

maybe: "number of in- and outputs handled by in- and output slots

respectively"
L96: "but do not have to"

maybe: "an optional internal time step"
L99: "when receiving input"

maybe: "when input is available"
L128: "Data exchange [...] takes place purely in memory"

How is data exchange in case no adapter is use (by value or reference)? How do

you avoid data copies? Is this a concern at all?
L122: "pint quantities"

This is not a common term for me. Maybe something like: "unit handing is

automatically done by the pint library"?
Section 2.1.4.:

The scheduling algorithm is only required because FINAM runs on a single

process and components can have varying time steps. If all components where

to run on dedicated processes, this should be much simpler. Or not?

You could add this information here to explain why other coupling solutions

do not have such a complex scheduling algorithm.

(As a side note: older versions of YAC could simulate an MPI-parallel run on

a single process. Similar scheduling functionality was required to support

that.)
Section 2.1.5:

Again this is only required due to the serial nature of FINAM. Maybe add a

small hint on why this approach is needed as compared to a parallel

implementation.
Figure 7: "update and the"

"updated and then the"?
Section 2.2

For a non-Python model the implementation of a FINAM wrapper might not be

trivial. Maybe you could give more information on that (e.g. add getter

routines for grid information, add Python bindings for C or Fortran routines

using Cython, ...). The FINAM wrapper for mHM could serve as an example.
L181-184: whole paragraph

Using the line count for the trivial PET example may be misleading. Again

mHM could be a more realistic example.
L194: VTK, and CSV

These are common formats (in your community)?
L194: "real-time visualization"

Do you support online visualization with Catalyst/Paraview?
Section 3.1

Depending on your targeted user group bidirectional exchanges between models

may be a regular coupling use-case and not worth writing a dedicated section

about (see "OASIS3-MCT User Guide" section "2.1 Configurations of

components supported").
L245: "This ease of use contrasts sharply with traditional frameworks, which

often require significant effort to configure and manage bidirectional

interactions."

This again depends on your perspective and usage of a coupling solution.

The provided example could be probably written in a similar fashion using the

latest YAC version.
Section 3.3

Do you make a difference between grids defined in Cartesian space and on the

sphere? Are they compatible?
L300-303:

Regridding methods do not only depend on the grid specifications, but also

on the type of fields to be exchanged. The correct regridding method and

its configuration (e.g. for conservative interpolation: order and

normalization) can have a significant impact on the coupling results. While

using default configuration can get plausible results quickly, more detailed

configurations can often lead to better results.
L316-320, Figure 19, and Figure B1:

This could give the impression that FINAM introduces conservative

interpolation, while it actually is using a basic functionality provided by

ESMF. This could be made clearer in my opinion. I do not see the added

benefit to the paper of Figure B1.
Section Discussion:

As mentioned before, without a clearer definition of the targeted users and

use-case, different conclusions could be drawn.

A couple of the points made in this section are not unique to FINAM, but are

characteristics of coupling frameworks in general. It could improve the

discussion if the paper makes it clearer where FINAM takes advantage of

general coupling framework concepts and where it deviates from other

implementation in order to generate different traits.
L328: "Python as the foundational language"

From my point of view, this only makes sense, if the paper defines clearer

goals. Your description would also description some of the requirements

for coupling global climate models, but in that case additional requirements

on compute performance, memory handling and memory consumption might lead to

a different choice (e.g. C for YAC).
L336-337: "The coupler makes use of this characteristic by requiring that each

model needs to be able to perform a single time iteration"

Maybe: "The coupler makes use of this characteristic by requiring that the

user exposes the execution of the individual time iterations

through an interface routine."
L341-345: whole paragraph

Do any of the coupling solutions to which FINAM is compared to use a pure

pull-based approach or where does the comparison to this approach come from?

Was this a potential option for implementing FINAM?
L346: "traditional coupling methods"

Maybe: "coupling libraries approach based solutions like OASIS"
L348: "must ensure data compatibility with respect to units"

In my experience that has never been an issue.
L348: "must ensure data compatibility with respect to [...] grid definitions"

For me that is a basic task for a coupler to make sure, that the user does

not have to take care of this. In case of YAC, all grid combinations are

compatible.
L348: "must ensure data compatibility with respect to [...] time reference"

In my experience that has never been an issue; at least for the application

YAC has been used for till now. This may be different for your targeted

use-case.
L349: "necessitating extensive modifications to the original model code"

Yes, coupling code is directly included in the model code, but with a good

software design it can be encapsulated and the resulting impact can be

minimal. On the other hand rewriting an existing model into a form that is

usable by a coupling framework can be a huge amount of work, which you also

mention later in this section. I would not categorize any of these

approaches as superior over the other or requiring more or less work than

the other. It primarily depends on the specific application.

You are in the particular position of having a model (mHM) for which both

approaches have already been implemented. Maybe you could compare the two

implementations in terms of measurments like lines of code, man-hours,

complexity, or ease of maintenance.
L351-352: "minimizing the need for direct alterations to model code"

This is only true, after the initial restructuring for a coupling framework

has been done.
L354-355: "regridding adapters automatically determine their required

transformation from the connected source and target components"

As mentioned before, from my experience this should not be done automatically,

because the correct configuration of the regridding depend on a variety of

factors (e.g. grid types, properties to be exchanged, masks,...).
L361-364: "parallelization"

This is potentially a very important topic and should get more explanation on

what is planned for FINAM (e.g. support for multiple serial components

running on different different processes, supporting MPI-parallelized

components, supporting compute and memory intensive highly parallel

components).

I think the authors underestimate the implications of supporting

parallelism in coupled setups.

To given an example: handling an ICON R02B11 grid is a challenge in itself.

It contains more than 300 million cells. Having a whole copy of the grid

available on a single process is often impossible. This makes online

computation of the regridding weights in a reasonable amount of time very

difficult.
L364-365: "Additionally, making a model ready for FINAM can require a

significant investment of time and resources."

As mentioned before, this could somewhat be quantified using mHM as an

example.
L383: "A unique feature of FINAM is its support for bidirectional coupling by

temporal delaying circular input/output connections"

The unique feature of FINAM is the ability to do this explicitly (I do not

know whether ESMF supports this). However, this can be done implicitly with

a coupling library.
L387: "FINAM standardizes time representation across models"

All coupling solutions have a standardized method on how to define time.

The way FINAM makes use of it is unique (at least compared to OASIS and YAC;

I do not know how it compares to the other coupling solutions mentioned

above).
L407: "forward-thinking approach"

This implies a backwards-thinking approach for other coupling solutions...

Maybe: "an approach better suited for ..."
L409-410: "FINAM represents a significant advancement in the field of

computational modeling."

I do not think that FINAM is practical for all coupling use-cases. Therefore,

I would not support this general statement.
Citation: https://doi.org/10.5194/gmd-2024-144-RC1
RC2:
'Comment on gmd-2024-144', Jannes Breier, 16 Oct 2024
General comments:
This manuscript was forwarded to me by a colleague of mine who knew that I am working on a similar but more applied model coupling library for a large-scale biosphere model using a different coupling approach. Based on this experience and the knowledge that many modelers want to couple different models without having to develop the corresponding software themselves, this endeavour, especially in its generalised form, is a highly significant scientific contribution.
In particular, the structure, underlying grammar and logic of the coupling framework and the way it is build up in the concept of components speak for themselves.
Some of the results are easily reproducible and the framework is documented in an exemplary manner, especially through the linked API documentation in the Code Availability chapter.

Specific comments:
What is the purpose of overloading the bitwise operator (>>) in the code? This is a very unique feature and not clearly explained in the text.

What would be an example for two models written in different languages, say one in Python, the other one in C++? How would the coupling work in this case? This is a feature which is mentioned in the text but not explained in detail.

What are the limitations of the regrid functionality, how are things handled like different geographical extents, different geographical coordinate systems, projections, different longitude latitude resolutions, etc.?

Final remarks:
It is noteworthy that the important limitations of the framework, such as the limitations in the parallelisation of models via MPI, are discussed in the text. Even though this might limit the applicability of the framework in some cases, it does provide a clear and well documented path for others that want to couple models for novel research questions. Therefore, this manuscript is highly recommended for publication in GMD.
Citation: https://doi.org/10.5194/gmd-2024-144-RC2

Sebastian Müller, Martin Lange, Thomas Fischer, Sara König, Matthias Kelbling, Jeisson Javier Leal Rojas, and Stephan Thober

Viewed

Total article views: 554 (including HTML, PDF, and XML)

HTML	PDF	XML	Total	BibTeX	EndNote
366	85	103	554	5	9

HTML: 366
PDF: 85
XML: 103
Total: 554
BibTeX: 5
EndNote: 9

Views and downloads (calculated since 20 Aug 2024)

Month	HTML	PDF	XML	Total
Aug 2024	181	45	7	233
Sep 2024	112	24	69	205
Oct 2024	41	11	25	77
Nov 2024	32	5	2	39

Cumulative views and downloads (calculated since 20 Aug 2024)

Month	HTML	PDF	XML	Total
Aug 2024	181	45	7	233
Sep 2024	112	24	69	205
Oct 2024	41	11	25	77
Nov 2024	32	5	2	39

Viewed (geographical distribution)

Total article views: 517 (including HTML, PDF, and XML) Thereof 517 with geography defined and 0 with unknown origin.

Country	#	Views	%

Latest update: 21 Nov 2024

Short summary

This study presents FINAM ("FINAM Is Not A Model"), a new coupling framework written in Python to dynamically link independently developed models. Python, as the ultimate glue language, enables the use of codes from nearly any programming language like Fortran, C++, Rust, and others. FINAM is designed to simplify the integration of various models with minimal effort, as demonstrated through various examples ranging from simple to complex systems.


Total:	0
HTML:	0
PDF:	0
XML:	0