FABM 3.0

The changes described below were merged into the master branch on 9 December 2025.

FABM 3.0 is in most respects a minor release and it is fully backwards compatible with all biogeochemical models and couplers that worked with FABM 2.0. It receives a new major version number only because it adds new features to the Application Programming Interfaces for coupling to physical models (the "host API").

As part of this release, the preprocessor variable _FABM_API_VERSION_ in fabm_version.h increases from 2 to 3. This allows a coupler to distinguish whether it is being built against FABM ≤ 2 or FABM 3. It can then wrap code that uses version-3-specific features (see below) with #if _FABM_API_VERSION_ > 2 ... #endif. The resulting code will be compatible with FABM 3 as well as earlier versions.

Host API extensions

FABM 3.0 adds a new part_of_state member (a logical) to diagnostic variables. Variable for which this flag is .true. should be included in any snapshot of the model state, for instance, in restart files.

The part_of_state flag will be .true. for two categories of variables:

• Diagnostic variables for which the old value is used to compute values for the new time step. These are diagnostics for which the "owning" biogeochemical model instance requests read access (see the end of section https://github.com/fabm-model/fabm/wiki/Developing-a-new-biogeochemical-model#diagnostic-variables), or diagnostics that another model instance requests with <TARGET_NAME>@old in its coupling section.
• Variables used by FABM to calculate time-filtered inputs, for instance, a moving average or a moving maximum.

As FABM's time filters use scalar (zero-dimensional) variables to track the model time, among others, FABM 3.0 also adds a new "scalar" category of diagnostic variables, just so they can be flagged with part_of_state and included in state snapshots. The list of scalar diagnostic variables is available as <MODEL>%scalar_diagnostic_variables, which is newly added next to the existing <MODEL>%interior_diagnostic_variables and <MODEL>%horizontal_diagnostic_variables.

Both new elements are also exposed in pyfabm, as the new part_of_state attribute of diagnostic variables and as the list <MODEL>.scalar_diagnostic_variables.

Deprecated macros, variables, APIs

The following are deprecated and will be removed in FABM v4. Alternatives have been available since FABM v1, which was released April 2020.

• Preprocessor macros:

  old macro name	new macro name
  _SET_ODE_	_ADD_SOURCE_
  _SET_BOTTOM_ODE_	_ADD_BOTTOM_SOURCE_
  _SET_SURFACE_ODE_	_ADD_SURFACE_SOURCE_
  _SET_BOTTOM_EXCHANGE_	_ADD_BOTTOM_FLUX_
  _SET_SURFACE_EXCHANGE_	_ADD_SURFACE_FLUX_
  _SET_VERTICAL_MOVEMENT_	_ADD_VERTICAL_VELOCITY_

• Variable-specific feedback APIs for biogeochemical models, which have been replaced by generic add_to_aggregate_variable functionality:

  API name	alternative (call from initialize)
  get_light_extinction	call self%add_to_aggregate_variable(standard_variables%attenuation_coefficient_of_photosynthetic_radiative_flux, <ID>)
  get_drag	call self%add_to_aggregate_variable(standard_variables%surface_drag_coefficient_in_air, <ID>)
  get_albedo	call self%add_to_aggregate_variable(standard_variables%surface_albedo, <ID>)

  If you would like to add expressions of variables to the above aggregate quantities, this can be done by creating a diagnostic for the expression, and using the diagnostic identifier in the call to add_to_aggregate_variable. The value of the diagnostic would then typically be set from do (attenuation) or do_surface (surface drag and albedo).

• The get_light API for biogeochemical models was renamed to do_column

• type_bulk_standard_variable was renamed to type_universal_standard_variable

• The fabm_v0_compatibility module for use by hosts will be removed altogether.