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”).

Initial conditions

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.

The restart values for FABM variables are collected in a single file INPUT/ocean_fabm.res.nc. The names of variables in this file 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:

import pyfabm,subprocess
model = pyfabm.Model('../fabm.yaml')
with open('fabm_init.nco','w') as f:
    for variable in model.interior_state_variables:
        f.write('%s=temp*0+%s;\n' % (variable.output_name,variable.value))
subprocess.call(['ncap2','ocean_temp_salt.res.nc','ocean_fabm.res.nc','-S','fabm_init.nco','-O','-v'])
subprocess.call(['ncatted','-a','long_name,,d,,','-a','checksum,,d,,','ocean_fabm.res.nc'])

Note that the above code is expected to be executed from the INPUT directory of your MOM setup.

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

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

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.