Introduction

FVCOM can be used with a wide variety of biogeochemical models, including ERSEM, through its coupling with the Framework for Aquatic Biogeochemical Models (FABM). This FVCOM-FABM coupler is developed by PML. Interested users can register for access to the code via PML's modelling website.

The main aspects of FABM configuration are detailed in the FABM wiki. FVCOM-specific options are detailed below.

ERSEM's design and implementation is detailed in a Geoscientific Model Development paper. More detailed instructions on configuring ERSEM can be found in its code repository (registation required).

Namelist

Online FVCOM-FABM

To enable FVCOM-FABM, edit the main FVCOM namelist &NML_ADDITIONAL_MODELS section to include the following:

 FABM_MODEL = T,

To save instantaneous FABM outputs, in the &NML_NETCDF section, add:

 NC_FABM = T

To save time-averaged FABM outputs, in the &NML_NETCDF_AV section, add:

 NCAV_FABM = T

Finally, add a new &NML_FABM section:

&NML_FABM
 STARTUP_FABM_TYPE = 'constant', ! 'constant' or 'set values'
 FABM_DEBUG        = F, ! outputs debugging information to the FVCOM log file
 FABM_DIAG_OUT     = F  ! outputs diagnostic ERSEM variables
/

If you have built FVCOM-FABM for offline simulation (see compiling FVCOM-ERSEM), you further need to add OFFLINE_FABM_FILE to the NML_FABM namelist; this variable must be set to the path to the NetCDF file with offline forcing information.

Offline FVCOM-FABM

For offline runs, all hydrodynamic variables which have a strong CFL constraint are not solved in the offline setup. To get FVCOM to generate all the variables necessary for an offline FVCOM-FABM run, configure the namelist as for the online run above, but set FABM_MODEL to F. All the variables needed for offline FVCOM-FABM can be saved from an FVCOM-FABM run by setting NC_OFFLINE set to T in the NML_NETCDF section of the FVCOM namelist:

&NML_NETCDF
 NC_ON              = T,
 NC_FIRST_OUT       = '2005-06-01 00:00:00',
 NC_OUT_INTERVAL    = 'seconds = 900.',
 NC_OUTPUT_STACK    = 0,
 NC_SUBDOMAIN_FILES = 'FVCOM',
 NC_GRID_METRICS    = T,
 NC_FILE_DATE       = T,
 NC_VELOCITY        = F,
 NC_SALT_TEMP       = F,
 NC_TURBULENCE      = F,
 NC_AVERAGE_VEL     = T,
 NC_VERTICAL_VEL    = F,
 NC_WIND_VEL        = F,
 NC_WIND_STRESS     = F,
 NC_EVAP_PRECIP     = F,
 NC_SURFACE_HEAT    = F,
 NC_GROUNDWATER     = F,
 NC_BIO             = F,
 NC_WQM             = F,
 NC_VORTICITY       = F,
 NC_OFFLINE         = T
/

Note: if NC_OFFLINE is set to T, then NC_VELOCITY, NC_SALT_TEMP and NC_VERTICAL_VEL must be set to F (the model will crash with an error that it cannot create a variable as it has already been defined).

Subsequent runs must be compiled with offline support and the NetCDF file specified in OFFLINE_FABM_FILE must exist in the main FVCOM input directory (INPUT_DIR).

Inputs

FVCOM-FABM needs additional inputs that specify the configuration and initial condition of the biogeochemical model. it can also read in the concentration of pelagic biogeochemical variables in rivers and at the open boundaries.

Biogeochemical model configuration

A FABM configuration is stored as a YAML file; a number of example configurations are provided in the testcases directories of FABM and ERSEM. This file must be named fabm.yaml and placed alongside the main FVCOM namelist when running FVCOM.

Initial conditions

Biogeochemical variables can be initialised with a constant value or with spatially varying fields read from the restart file. The initialisation behaviour is configured through the STARTUP_FABM_TYPE variable in namelist NML_FABM:

  • To initialize each FABM variable across the entire domain with its default value in fabm.yaml, set STARTUP_FABM_TYPE to 'constant'.
  • To initialize with spatially explicit values from a restart file (its path set through variable STARTUP_FILE in namelist NML_STARTUP), set STARTUP_FABM_TYPE to 'set values'. A sample MATLAB script uses the FVCOM MATLAB toolbox to read in outputs from a larger regularly gridded model and interpolate them to the FVCOM grid before writing out the new values to a new restart file.

Rivers

To prescribe the values of pelagic biogeochemical variables in river discharges, no FABM-specific options need to be set. FVCOM will simply look for each FABM variable in its river file(s). If present, the prescribed time series will be used. If not present, the value of that variable is assumed to be zero in the river discharge. An example of a river forcing file including ERSEM nutrients is detailed in this NetCDF structure. The MATLAB function write_FVCOM_river_ERSEM exists to create river forcing files in the FVCOM MATLAB toolbox.

Open boundaries

To prescribe the concentration of FABM variables at open boundaries, set OBC_FABM_NUDGING=T in namelist NML_OPEN_BOUNDARY_CONTROL. By default, FVCOM will then look for prescribed boundary values in file <CASENAME>_obc.nc. This path can be configured with variable OBC_FABM_FILE in namelist NML_OPEN_BOUNDARY_CONTROL. The rate at which FABM variables are relaxed towards their boundary value (only in the case of inflow across the boundary!) is controlled by variable OBC_FABM_NUDGING_TIMESCALE in namelist NML_OPEN_BOUNDARY_CONTROL. Note that this relaxation increases from off to fully active during the model’s start-up phase, defined in number of internal time steps by IRAMP in NML_INTEGRATION.

The FVCOM-FABM coupler does not demand that boundary conditions are prescribed for all pelagic biogeochemical variables; for variables not present in the forcing file, no boundary forcing will be applied. This effectively assumes a zero-gradient condition across the boundary for that variable.

The following example NetCDF structure indicates the required structure. The MATLAB FVCOM toolbox function write_FVCOM_tsobcERSEM can create this file.

Additional forcing for biogeochemistry

Some biogeochemical model configurations (fabm.yaml files) may depend on environmental fields that are not provided by FVCOM. For instance, ERSEM depends on the atmospheric partial pressure of CO2 (pCO2; a 2D field) and on light attenuation by suspended silt (a 3D field). In such cases, you can prescribe constant values for these fields by adding entries to fabm.yaml. For instance, to set pCO2 to 385 ppm and light absorption by silt to 0.07 m-1, you would add the following:

  pCO2a:
    model: horizontal_constant
    parameters:
      standard_name: mole_fraction_of_carbon_dioxide_in_air
      value: 385.0
  silt_absorption:
    model: interior_constant
    parameters:
      standard_name: absorption_of_silt
      value: 0.07

(instance names pCO2a and silt_absorption are arbitrary)

It is also possible to prescribe time- and/or space-varying values. For that purpose, provide a fabm_input.nml file along with your setup with something like:

&NML_FABM_INPUT
  VARIABLE_NAME='mole_fraction_of_carbon_dioxide_in_air'
  FILE='co2.nc'
/

This will make FVCOM look for a 2D variable named “mole_fraction_of_carbon_dioxide_in_air” in co2.nc. If the variable has a different name in that file, you can specify that by adding NC_VARIABLE_NAME='<NAME>' to the NML_FABM_INPUT namelist.

To read the data from NetCDF, the coupler relies on the infrastructure provided by FVCOM itself. Therefore, your NetCDF file must follow the same conventions as any other 2D or 3D FVCOM inputs when it comes to spatial and temporal dimensions, variable attributes, etc.

If you want to use multiple forcing variables, you can add additional namelists to fabm_input.nml.

Output

By default, the set of biogeochemical variables included in FVCOM's instantaneous output (if NC_FABM = T in NML_NETCDF) and in its time-averaged output (if NCAV_FABM = T in NML_NETCDF_AV) includes every variable registered by the FABM modules listed in fabm.yaml. This includes state variables (e.g., concentrations) and diagnostic variables (e.g., rates), although the latter category can be excluded by setting FABM_DIAG_OUT = F in namelist NML_FABM.

You can further control the variable selection by providing a file named fabm_output.yaml along with your setup. This is a file in YAML format, which explicitly specifies which variables to include in the output. Variables not mentioned in this file will be omitted. It has the following format:

variables:
  <VARIABLE1>: true
  <VARIABLE2>: true
  <VARIABLE3>: true

Here, variable names such as <VARIABLE1> can be the name of a variable as it would appear in the NetCDF output (for instance, N3_n and P1_c for ERSEM nitrate and diatom carbon), or expressions ending with an asterisk symbol (*) to include all variables with a name that starts with characters preceding the asterisk (e.g., P1_* for all diatom variables in ERSEM).

Nesting

FVCOM-FABM supports both reading and writing of nesting data for biogeochemical variables:

  • When FVCOM is configured to write out boundary data for a nested domain (NCNEST_ON = T in NML_NCNEST), the written files will include all of FABM's pelagic state variables.
  • If you want to use FVCOM's nesting functionality to provide the values of biogeochemical variables at the boundaries (e.g., values derived from a larger FVCOM setup that was configured to write out nesting data), you need to add FABM_NESTING_ON = T in namelist NML_NESTING. This will cause FVCOM to look for data for each pelagic biogeochemical variable in the nesting file (as set by NESTING_FILE_NAME in NML_NESTING).

Notes

All other aspects of the model simulation remain intact, i.e. surface forcing, rivers and boundary conditions for ERSEM are all still used. The one outstanding aspect which at the moment doesn't have a quick solution is to include an internal loop in ERSEM to refine the time integration of vertical transport of sinking particulates (as already implemented in the sediment code in FVCOM).

In theory it should be possible to run both offline sediment and ERSEM as variables do not have the same names. But as it stands, each offline option (sediments and ERSEM) expects a netCDF file and both read and update FVCOM state variables. Ideally these should be merged so that when either or both of them are true a single update_offline_forcing is used.

Example output: FVCOM-FABM-ERSEM

The figure series below shows a range of ERSEM output variables in June 2006 for the UK west coast.