Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Setting up a simulation
FABM is a framework, not a standalone 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 you would normally do. Thus, the FABM directory is used at the compilation stage only; at run-time, everything runs via the host.
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
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:
||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|
||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
||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
||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
||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
||If the model instance has external dependencies|
||This flag specifies whether to use this model instance. If set to
||No. By default this flag is
||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
||No. By default this flag is
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, numeric values (integers or real numbers) use the usual numeric formats, Boolean values must be either