FABM 2.0 - fabm-model/fabm GitHub Wiki

The changes described below were merged into the master branch on 9 October 2023.

FABM 2.0 is in most respects a minor release, but it includes a few backward-incompatible changes that warrant a new major version number. These changes are described here, along with information on how to migrate to the new release.

Users:

• FABM 2.0 drops support for very old (> 5 years) versions of cmake, gfortran and Python. This is unlikely to cause problems, as most production systems have newer versions of these packages installed.
• Users of pyfabm will need to adopt the new (simpler) installation mechanism.
• CMake must always be called on the top-level FABM directory (<FABMDIR>); it can no longer be called on <FABMDIR>/src (this was already deprecated with the release of FABM 1.0).
• When building host models against a precompiled FABM installation, at least some compilers now require module files from both <FABM_BASE>/include and <FABM_BASE>/include/yaml. The latter is new - you may therefore have to add it to your list of include directories when building the host model. Try this if you get error messages about opening the yaml_settings module file.

Developers:

• Biogeochemical models do not require changes to support FABM 2.0.
• Host models only require source code changes if they directly access the metadata or value of biogeochemical parameters, which is rare.

General:

• FABM 2.0 now respects the (previously undocumented) top-level require_initialization attribute in fabm.yaml: if this attribute is true, FABM verifies that all state variables defined by a model instance are given an initial value in its initialization section. Missing values will trigger a runtime error. Previous versions of FABM ignored the require_initialization attribute altogether. The consequence of this change is that some fabm.yaml files will need to be updated by (1) adding missing initial values, or, (2) removing require_initialization: true (or setting it to false)

FABM 2.0 drops support for older releases (from 5 years or more ago) of cmake, gfortran, and Python. This has enabled simplication and clean-up of the code. More details are available here. The minimum supported versions now are:

• cmake 3.13 (NB releases of FABM v2 prior to 2024-01-11 required 3.14)
• gfortran 5.1 (only relevant if you use gfortran; other Fortran compilers are also fine, e.g., Intel, Cray, AMD, NVIDIA)
• Python 3.7 (only relevant if you use pyfabm)

To verify if your system meet these requirements, you can execute cmake --version, gfortran --version, python --version. (NB on some systems, the latest Python will be python3 rather than python)

pyfabm is now installed using normal Python conventions:

pip install <FABMDIR>

The replaces the old installation mechanism that required you to create a build directory, call cmake, and build the "install" target. Underneath, the pip-based installation calls cmake. Therefore, you do still need cmake and a Fortran compiler. If you want to customize cmake options (e.g., to customize FABM_INSTITUTES, or manually specify the Fortran compiler to use), the easiest way to do this is to create a file named setup.cfg in the toplevel FABM directory, with contents

[build_ext]
cmake_opts=<CMAKE-OPTIONS>

You can enumerate all active model instances and their parameters like this:

type (type_model_list_node), pointer :: instance
type (type_key_value_pair),  pointer :: pair

! Get pointer to the first model instance
instance => model%root%children%first

do while (associated(instance))
   if (instance%model%user_created) then
      print *, 'Instance ', trim(instance%model%name)
      pair => instance%model%parameters%first
      do while (associated(pair))
         select type (value => pair%value)
         class is (type_real_setting)
            print *, '  ', pair%name, ': ', value%pvalue
         class is (type_integer_setting)
            print *, '  ', pair%name, ': ', value%pvalue
         class is (type_logical_setting)
            print *, '  ', pair%name, ': ', value%pvalue
         class is (type_string_setting)
            print *, '  ', pair%name, ': ', value%pvalue
         end select
         pair => pair%next
      end do
   end if
   instance => instance%next
end do

You can detect which FABM version is used at compile time: preprocessor symbol _FABM_API_VERSION_, defined in fabm_version.h, is 2 for FABM 2.x, 1 for FABM 1.x, and 0 for earlier versions. Based on the value of this symbol, you can stop compilation and tell users to upgrade, or activate different code paths.