MOM

About MOM

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

FABM

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, and <COMPILER> with the Fortran compiler that you will use to compile MOM5 (e.g., mpif90). After make install completes, your FABM library will be located at $HOME/local/fabm/mom5/lib/libfabm.a, and the FABM module files will be located at $HOME/local/fabm/mom5/include.

MOM

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 (<MOMDIR>/bin/mkmf.template.*):

• add the line INCLUDE += -I$(HOME)/local/fabm/mom5/include below the line that first sets the include directories (it starts with INCLUDE =)
• add the line LIBS += -L$(HOME)/local/fabm/mom5/lib -lfabm below the lines that first set LIB (they start with LIB :=)

Activating FABM

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 field_table:

"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)*m³ 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!

Initial conditions

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.nc contains 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.nc contains 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 INPUT directory:

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 gotm_npzd_nut, gotm_npzd_phy, gotm_npzd_zoo, gotm_npzd_det in 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., "OCN")
• 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 (.true. or .false.)
• 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 data_table file:

"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 diag_table itself.

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 nut, phy, zoo and det state variables of FABM's gotm_npzd model can be added with the following lines in diag_table:

"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 m³.

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.