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
The Modular Ocean Model is a 3D structured grid ocean model.
A FABM coupler for MOM5 is developed and maintained by Bolding & Bruggeman ApS. (the authors of FABM).
A version of MOM5 with the FABM coupler integrated is distributed from a separate repository on GitHub. This is a fork of the official MOM5 repository; the only changes
compared to the official version are the addition of the FABM coupler (
ocean_fabm.F90) and a few small changes in the MOM code to enable it to pass additional physical fields (shortwave radiation, bottom shear stress) to FABM.
Getting the code and building
First get the FABM source from its git repository:
git clone https://github.com/fabm-model/fabm.git
This will create a new
fabm directory with the FABM source code.
To create the FABM library, run cmake and make:
mkdir build cd build cmake <FABMDIR>/src -DFABM_HOST=mom5 -DCMAKE_Fortran_COMPILER=<COMPILER> make install
In the above, replace
<FABMDIR> with the path to the
fabm directory with source code,
<COMPILER> with the Fortran compiler that you will use to compile MOM5 (e.g.,
make install completes, your FABM library will be located at
the FABM module files will be located at
Now get the MOM source code including the FABM coupler from its git repository:
git clone https://github.com/BoldingBruggeman/mom.git -b 5.1.0-fabm
This will create a new
mom directory with the MOM5 source code.
Then follow the MOM quickstart instructions to compile, with two changes to your template file (
- add the line
INCLUDE += -I$(HOME)/local/fabm/mom5/includebelow the line that first sets the include directories (it starts with
- add the line
LIBS += -L$(HOME)/local/fabm/mom5/lib -lfabmbelow the lines that first set
LIB(they start with
FABM support in a MOM simulation must be activated in the
field_table configuration file. Without this, FABM is not used and
fabm.yaml is not read! FABM is activated by adding the following lines to
"tracer_packages","ocean_mod","ocean_fabm" use=.true. /
This will cause MOM5 to read FABM-specific settings from
fabm.yaml (see section “Setting up a simulation”).
Units of pelagic variables
Read this carefully! The units of FABM variables in MOM restart and output files are different from what you might expect.
MOM defines tracer concentrations as tracer quantity per seawater mass. This differs from FABM and many other hydrodynamic models, which express tracer as quantity per seawater volume. The MOM-FABM coupler takes care of the transformation between tracer quantity per mass (MOM) and tracer quantity per volume (FABM) by dividing or multiplying with seawater density whenever needed - no changes are needed in FABM's biogeochemical models (which should always use tracer quantity per volume).
The result of this, however, is that whenever MOM reads or writes the values of FABM's pelagic tracers, they will have units equal to (FABM units)*m3 kg-1 - the original FABM units divided by seawater density (approximately 1025 kg m-3). This affects restart files as well as the MOM output. Therefore, care needs to be taken when:
- writing restart files: divide values in original FABM units by density!
- interpreting pelagic variable outputs: multiply with density to get original FABM units!
Quick start: use
<MOMDIR>/exp/FABM_create_initial_condition.py to generate initial conditions. Run this script with
-h for more information.
Initial conditions in MOM are specified in “restart files”, which use the NetCDF format. Examples of restart files can be found in every MOM experiment, in the file
INPUT/ocean_temp_salt.res.nc, which contain initial values for temperature and salinity. The MOM documentation contains additional information on how restart files may be created by regridding existing data in NetCDF format. Therefore, this section only describes issues that are specific to FABM.
MOM-FABM uses two restart files:
INPUT/ocean_fabm.res.nccontains restart values for all of FABM's pelagic state variables. The units of these variables are equal to those specified in FABM, divided by the seawater density in kg m-3.
INPUT/ocean_fabm_2d.res.nccontains restart values for all of FABM's horizontal state variables, that is, state variables associated with the water surface or the bottom. The units of these variables are equal to those specified in FABM.
The names of variables in these files must match the names of the target variables in FABM, e.g., “gotm_npzd_nut” for the nutrient variable in the NPZD model.
To generate simple, spatially homogenous initial conditions for FABM state variables, one can use the netCDF Operators (NCO). This set of utilities allows you to create biogeochemical initial conditions from existing restarts for e.g. temperature, and overwrite these with a constant value. To achieve this, the following command can be used within the
ncap2 ocean_temp_salt.res.nc ocean_fabm.res.nc -s gotm_npzd_nut=temp*0+4.5 -s gotm_npzd_phy=temp*0+1e-15 -s gotm_npzd_zoo=temp*0+1e-15 -s gotm_npzd_det=temp*0+4.5 -O -v
This creates new variables
ocean_fabm.res.nc, with the spatial extents of the temperature variable, but with a constant value across the entire domain (resp. 4.5, 1e-15, 1e-15, 4.5).
The restart file for an arbitrary FABM setup (fabm.yaml file) can be created automatically by a simple Python script in combination with the FABM-Python driver. This script is located at
<MOMDIR>/exp/FABM_create_initial_condition.py, and needs to be run with the path to your experiment directory as first argument.
The MOM-FABM coupler also requires restart files to be present for chlorophyll and irradiance fields. These can be created with:
ncap2 ocean_temp_salt.res.nc ocean_chl.res.nc -s chl=0.*temp -O -v ncap2 ocean_temp_salt.res.nc ocean_irr.res.nc -s irr=0.*temp -O -v
If FABM is initialized at the very start of an experiment (this is rare – typically, an experiment is spun up for several years with physics only to obtain stable flow fields), it will by default set the values of all variables to their model-specified, spatially-independent initial value. This can be overridden for each individual variable in the configuration file
field_table, by explicitly specifying that it should not be initialized with the default constant value (but from the restart file instead). For instance, to make the nutrient variable in the NPZD model initialize from the restart file (default: variable "gotm_npzd_nut" in
INPUT/ocean_fabm.res.nc), the following lines may be added to field_table:
"prog_tracers","ocean_mod","gotm_npzd_nut" const_init_tracer = .false. /
Prescribing biogeochemical variables
External fields can be used to provide FABM with necessary external dependencies, or to override the values of FABM variables with observed data [the latter should be used with caution, as it can cause strange model behaviour, and loss of mass conservation!].
MOM allows external fields to be specified in the configuration file
data_table. This file contains a list of variables (one per line) that should be retrieved from auxiliary, user-provided NetCDF files. Each line contains the following comma-separated items:
- the name of target grid (for FABM, this is always the ocean, i.e.,
- the name of the target variable in the model. For FABM, this corresponds to the name of the FABM variable, prefixed with “fabm_” The name of the FABM variable can either be the name of a specific model variable, or the name of a standard variable.
- the name of the source variable in the NetCDF file
- the path to the NetCDF file
- an “ongrid” flag specifying whether the grids of the model and the NetCDF file match (
- the scale factor that must be applied to [multiplied with] the NetCDF variable in order to arrive at the units that the model expects (use 1.0 for no scaling).
Strings need to be enclosed in double quotes. Optionally, the source path and variable name may be omitted; in that case, the target variable is set to the value of the "scale factor", throughout the domain, and constant in time.
Thus, to impose a time-varying partial pressure of atmospheric CO2, the following line may be added to the
"OCN", "fabm_mole_fraction_of_carbon_dioxide_in_air", "pco2a", "./INPUT/pco2a.nc", .false., 1.
This specifies that the
INPUT directory of the experiment contains a NetCDF file
pco2a.nc. This file contains a horizontal (x,y) variable "pco2a" that must contain the partial pressure of atmospheric CO2. It may be noted that MOM allows the source variable to be either time-variable or time-independent; in the latter case, a constant (but still spatially variable) pressure is imposed. In the above case, the (horizontal) grid of the pCO2 variable does not need to match that of the model (due to the one-but-last value of
.false.). However, for performance reasons it is typically beneficial to regrid external variables to the model grid (using the regrid_2d preprocessing tool provided with MOM).
Including FABM variables in output
Quick start: use
<MOMDIR>/exp/FABM_create_diag_table.py to generate lines to go into
diag_table. Run this script with
-h for more information.
MOM includes variables in its NetCDF output only if explicitly requested by the user. To do so, the configuration file
diag_table must be edited. This file defines which output files to generate, and which variables to include in them. The use of
diag_table is described in the MOM manual, and in the comments within
For FABM variables, it is important to know that from the perspective of the MOM's diagnostics manager, they are part of module
ocean_model. Moreover, the full names of FABM variables equal the name of the FABM model, followed by an underscore, followed by the name of the variable within the FABM model. Thus, if
diag_table defines an output file
ocean_month, then the
det state variables of FABM's
gotm_npzd model can be added with the following lines in
"ocean_model","gotm_npzd_nut","gotm_npzd_nut","ocean_month","all",.true.,"none",2 "ocean_model","gotm_npzd_phy","gotm_npzd_phy","ocean_month","all",.true.,"none",2 "ocean_model","gotm_npzd_zoo","gotm_npzd_zoo","ocean_month","all",.true.,"none",2 "ocean_model","gotm_npzd_det","gotm_npzd_det","ocean_month","all",.true.,"none",2
The FABM variables that can be mentioned here include all state variables (interior, bottom-attached, surface-attached) and all diagnostics (interior, horizontal), as well as the totals of conserved quantities across the domain. For the latter, use the name of the conserved quantity with postfix "_global_int", for instance, "total_nitrogen_global_int". The units of these variable will be the units of the conserved quantity defined in FABM, multiplied by m3.
For the meaning of all elements on these lines, please see the MOM documentation or the comments in the
diag_table files provided with the MOM test cases.
As for the restart files, you can use the Python-FABM driver to generate the additional diag_table entries. A script that does so is located at
<MOMDIR>/exp/FABM_create_diag_table.py. It needs to be run with the path to your experiment directory as first argument, and will write lines for you
diag_table to stdout. It supports additional command line arguments to configure ouytput settings in more detail; run the script with the
-h switch to see these.