Setting up a simulation

FABM is a framework, not a stand-alone program. It is compiled as part of the host (typically a hydrodynamic model), and it is there to handle biogeochemistry only. To run a simulation with FABM, set up the host model as you would normally do, then add FABM-specific settings to that setup. After that, run the host model as usual. Thus, the FABM directory is used at the compilation stage only; at run-time, everything runs via the host.

fabm.yaml

FABM uses a single configuration file fabm.yaml, which describes what biogeochemical models to use and how they are parameterized. fabm.yaml is a text file in YAML format. It contains a hierarchy of information, represented by space-based indentation. Each active model has its own block in the configuration file. For instance, fabm.yaml for a modular NPZD model with separate nut, phy, zoo and det instances looks like this:

instances:
  nut:
    long_name: nutrient
    model: examples/npzd/nut
    initialization:
      c: 4.5                         # concentration (mmol m-3)
  phy:
    long_name: phytoplankton
    model: examples/npzd/phy
    parameters:
      p0: 0.0225                     # background concentration (mmol m-3), default = 0.0225
      kc: 0.03                       # specific light extinction (m2 mmol-1), default = 0.03
      i_min: 25.0                    # minimum light intensity in euphotic zone (W m-2), default = 25.0
      rmax: 1.0                      # maximum specific growth rate (d-1), default = 1.0
      alpha: 1.35                    # half-saturation nutrient concentration (mmol m-3), default = 0.3
      rpn: 0.01                      # excretion rate (d-1), default = 0.01
      rpdu: 0.02                     # mortality in euphotic zone (d-1), default = 0.02
      rpdl: 0.1                      # mortality below euphotic zone (d-1), default = 0.1
      w_p: -1.0                      # vertical velocity (<0 for sinking) (m d-1), default = -1.0
    initialization:
      c: 1e-15                       # concentration (mmol m-3)
    coupling:
      uptake_target: nut/c           # nutrient source (mmol m-3)
      excretion_target: nut/c        # sink for excreted matter (mmol m-3)
      mortality_target: det/c        # sink for dead matter (mmol m-3)
  zoo:
    long_name: zooplankton
    model: examples/npzd/zoo
    parameters:
      z0: 0.0225                     # background concentration (mmol m-3), default = 0.0225
      gmax: 0.2                      # maximum specific grazing rate (d-1), default = 0.5
      iv: 1.1                        # Ivlev grazing constant (m3 mmol-1), default = 1.1
      rzn: 0.01                      # excretion rate (d-1), default = 0.01
      rzd: 0.02                      # mortality (d-1), default = 0.02
    initialization:
      c: 1e-15                       # concentration (mmol m-3)
    coupling:
      grazing_target: phy/c          # prey source (mmol m-3)
      excretion_target: nut/c        # sink for excreted matter (mmol m-3)
      mortality_target: det/c        # sink for dead matter (mmol m-3)
  det:
    long_name: detritus
    model: examples/npzd/det
    parameters:
      w_d: -5.0                      # vertical velocity (<0 for sinking) (m d-1), default = -5.0
      kc: 0.03                       # specific light extinction (m2 mmol-1), default = 0.03
      rdn: 0.003                     # remineralization rate (d-1), default = 0.003
    initialization:
      c: 4.5                         # concentration (mmol m-3)
    coupling:
      mineralisation_target: nut/c   # sink for remineralized matter (mmol m-3)

At the top-level, the file contains a single instances element. Below this, active model instances appear. Each active model instance is given a short name, which is an arbitrary string that can consist of letters, digits and underscores only (e.g., nut, phy, zoo, det). This is followed by an indented block describing instance specifics, among which a descriptive name, the model type, parameter values, initial state variable values, and a list of couplings to other model instances:

Attribute	Interpretation	Required
long_name	Descriptive name for the model. It can contain letters, digits, underscores and spaces. The long name will be used as prefix for long variable names in model output.	No. If not provided, the short name of the model instance will be used
model	Name of the model type. This must be a name known to FABM, as FABM will use it to create an appropriate model object with data (e.g., model parameters) and routines (e.g., the model equations). Typically, the model name is a path consisting of strings (letters, digits, underscores only) separated by slashes, e.g., examples/npzd/phy. FABM will resolve the components of the path one by one, starting from src/fabm_library.F90, and looking into institute-specific model libraries from there on.	Yes
parameters	A dictionary with parameter names and values. Not all parameters used by the model instance need to be listed; for a missing parameter, a default value will be used (provided the model type specifies default values!). Model authors: the parameters in this dictionary must be registered by the model from its initialize routine, by calling self%get_parameter.	No
initialization	A dictionary with state variables names and associated initial values. Model authors: the variables in this dictionary must be registered by the model from its initialize routine, by calling self%register_state_variable.	No
coupling	A dictionary with the names of model variables, and the target variable that they should be coupled to. These target variables must be part of other model instances; they are specified as paths consisting of the short name of the model instance, a slash, and the short name of the target variable. For instance nut/c for variable c in model instance nut. Model authors: variables registered with register_dependency or register_state_variable_dependency must appear here. Additionally, variables registered with register_state_variable may appear as well.	If the model instance has external dependencies
use	This flag specifies whether to use this model instance. If set to false, the model instance will be ignored. This is equivalent to commenting out all lines belonging to the model instance.	No. By default this flag is true, which means the instance will be used.
check_conservation	This flag specifies whether to add diagnostics for the change in conserved quantities (e.g., total carbon), as associated with source terms and with fluxes across the surface and bottom interfaces. The diagnostics will be named <INSTANCE>_change_in_<CONSERVED_QUANTITY>, <INSTANCE>_change_in_<CONSERVED_QUANTITY>_at_surface, and <INSTANCE>_change_in_<CONSERVED_QUANTITY>_at_bottom. Here, <INSTANCE> is the name of the model instance, and <CONSERVED_QUANTITY> is the name of the conserved quantity. For instance, adding check_conservation to the phy instance in the above example will give you a phy_change_in_total_nitrogen diagnostic. Model authors: set this flag to true to verify whether your do, do_surface, and do_bottom routines conserve mass.	No. By default this flag is false.

About the YAML format

• Indentation is used to create a hierarchy of information, as in the Python programming language. Indentation can consist of spaces only - tabs are not permitted.
• The comment character in YAML is #. On any given line, everything after and including the first # symbol is ignored.
• Values are formatted as follows:
  • strings do not require quotation (FABM does not support quoted strings, even though the YAML specification itself does)
  • numeric values (integers or real numbers) use the usual numeric formats
  • Boolean values must be either true or false (case-insensitive)