State variables and dependencies: register_state_variable vs. register_dependency vs. register_state_dependency?

[FabianGrosze]

I recently took over a project in which we started to port some very old BGC model to FABM, so I am not yet familiar with all the nitty-gritty details and might have missed pieces of information in this forum or the wiki, though my searches didn't give any matching hits.

The (FABM-style) code I took over uses register_state_variable in all BGC models that calculate rates of change for state variables - like it is described in the wiki . As a result, for each state variable registered by multiple (coupled) models, the full model yields multiple instances, e.g. model1/oxygen, model2/oxygen. When writing all registered state variables to a restart file, this file contains those multiple ("identical") variable instances. This is not the behaviour I expected (or intend to get in the end).

According to the wiki, register_dependency is only to be used for variables that a model requires only read access for. However, in many BGC models in FABM (e.g. ERSEM) I noticed the use of register_state_dependency such that a state variable is only registered (via register_state_variable) in one model, while all the other coupled models use register_state_dependency even if they calculate rates of change for this variable.

I couldn't find any documentation on register_state_dependency and haven't tested its behaviour, yet, but I wonder if using it the way it is done in, e.g., ERSEM, would resolve the described issue for the restart file? Or is there another recommended approach to avoid the described behaviour?

[jornbr]

There is one key difference between register_state_variable and register_state_dependency: the former registers a new state variable, the latter registers a dependency on a state variable that must come from another model. If this condition is not satisfied (that is, if there is no coupling made for the state dependency in fabm.yaml), the model will not run. The variable identifier that you register with either of these two routines is the same: it can be used to retrieve the state variable value and to provide source terms.

In practice, it is also possible to couple a variable registered with register_state_variable by adding a corresponding coupling entry to fabm.yaml. In that case, models end up sharing state variables without explicitly being aware of it. However, if you then omit the coupling from fabm.yaml, each module has its own independent state variable. That likely explains your multiple oxygen variables. Using register_state_dependency would protect you from that.

[FabianGrosze]

Excellent, thanks for the comprehensive and swift response!