fvcom ersem - UK-FVCOM-Usergroup/uk-fvcom GitHub Wiki

FVCOM can be used with a wide variety of biogeochemical models, including ERSEM, through its coupling with the http://fabm.net. This FVCOM-FABM coupler is developed by PML. Interested users can register for access to the code via http://www.pml.ac.uk/Modelling/Access_Code.

The main aspects of FABM configuration are detailed in the http://fabm.net/wiki. FVCOM-specific options are detailed below.

ERSEM's design and implementation is detailed in a http://www.geosci-model-dev.net/9/1293/2016/. More detailed instructions on configuring ERSEM can be found in https://gitlab.ecosystem-modelling.pml.ac.uk/stable/ERSEM

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'
 USE_FABM_BOTTOM_THICKNESS = F, ! allow precipitation of salts on the bathymetry in hypersaline environments
 USE_FABM_SALINITY = F, ! use FABM's internal salinity routines for hypersaline environments
 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 source:compile_fvcom#fvcom-fabmsupport_for_biogeochemical_models), 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.

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. As some of the variables require information about the boundaries you have to make sure that OBC_ON is set to T even if you are using nesting. At PML we use NESTING_ON with NESTING_TYPE = 3 when possible.

&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 source:compile_fvcom#fvcom-fabmsupport_for_biogeochemical_models and the NetCDF file specified in OFFLINE_FABM_FILE must exist in the main FVCOM input directory (INPUT_DIR).

The list of files that have been modified to enable offline simulations are

mod_fabm_data.F
mod_fabm_3D.F
mod_ncdio.F
mod_input.F
mod_obcs.F
mod_force.F
mod_main.F
bcond_gcn.F
bcond_gcy.F
internal_step.F

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.

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.

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.

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 ncdump_rivers. The MATLAB function write_FVCOM_river_ERSEM exists to create river forcing files in the FVCOM MATLAB toolbox.

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 ncdump_obc indicates the required structure. The MATLAB FVCOM toolbox function write_FVCOM_tsobcERSEM can create this file.

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 CO₂ (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 pCO₂ 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.

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

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 pelagic biogeochemical variable in the nesting file (as set by NESTING_FILE_NAME in NML_NESTING).
• FVCOM can run with a subset of the biogeochemical model state variables. It will use whatever variables are included in the file and ignore the missing ones. In that case, make sure that you have some open boundary treatment also enabled.
• If you have FABM_MODEL = F in additional model namelist but have FABM_NESTING_ON = T the model will crash possibly without a useful error.

FVCOM can run simultaneously with both FABM (ERSEM) and CSTM active. Hooks to enable FABM to see the CSTM array CSED are already in place in mod_fabm_3D.F and are enabled when FVCOM is compiled with both -DFABM and -DSEDIMENT. As it stands, the only interaction between the biogeochemistry and sediments is through additional components to the underwater light attenuation in ERSEM. These are only present in light_iop.F90 in the ERSEM code.

In mod_fabm_3D.F the whole CSED array is linked to mass_concentration_of_silt which implies that the sediment module is being run with only one size class assumed to be silt-clay with a d_50 < 62.5 micro m. The variable mass_concentration_of_silt requires units in mg/m3.

ERSEM light_iop.F90 expects both coefficients for specific absorption and backscattering and at the moment these are calculated in mod_fabm_3D.F and specific absorptions and backscattering values are hard coded.

In the near future, we will add silt_absorption and silt_bbscatter as optional inputs to fabm.yaml

Right now light_ady.F90 has been merged with light_iop_withBB.F90 into light_ady_spm.F90 so that both CDOM absorption and SPM can be accounted for in combination. light_ady_spm.F90 has to be added to the CMakelist.txt in ERSEM directory. At the moment these files are not in the git ERSEM branch but available on request through FVCOM-FABM list.

The specific absorption values have been pulled from different literature sources and they are solely based on UK studies and probably biased towards the Channel area.

• Tilstone, G.H., Peters, S.W.M., van der Woerd, H.J., Eleveld, M.A., Ruddick, K., Schönfeld, W., Krasemann, H., Martinez-Vicente, V., Blondeau-Patissier, D., Röttgers, R., Sørensen, K., Jørgensen, P.V., Shutler, J.D., 2012. Variability in specific-absorption properties and their use in a semi-analytical ocean colour algorithm for MERIS in North Sea and Western English Channel Coastal Waters. Remote Sensing of Environment 118, 320–338. https://doi.org/10.1016/j.rse.2011.11.019. Specific absorption values between 0.01-0.02 m2/g. These are for Total Suspended Matter (TSM) and include organic and non-organic particulates. These values are probably a bit too low but they are comparable to the absorption default values used in ERSEM for R4-R8.

• Babin, M., Stramski, D., Ferrari, G.M., Claustre, H., Bricaud, A., Obolensky, G., Hoepffner, N., n.d. Variations in the light absorption coefficients of phytoplankton, nonalgal particles, and dissolved organic matter in coastal waters around Europe. Journal of Geophysical Research: Oceans 108. https://doi.org/10.1029/2001JC000882. Here relevant values for absorption are 0.035 (m2/g) (similar values for irish sea and channel areas) and only relate to inorganic silt particulates. Babin reports a dependency of the specific absorption coefficient with Particulate Inorganic Matter concentrations (PIM) as abs(443) = 0.031 x PIM (all units in m g). Bowers et al 1996 (in the same paper) gives a slightly different one: abs(443) = 0.0235 x PIM

• Martinez-Vicente, V., Land, P.E., Tilstone, G.H., Widdicombe, C., Fishwick, J.R., 2010. Particulate scattering and backscattering related to water constituents and seasonal changes in the Western English Channel. J Plankton Res 32, 603–619. https://doi.org/10.1093/plankt/fbq013. Victor here has also a bbp equation as a function of PIM: bbp(532) = PIM x 0.0055(+-0.0012) + 0.0002 (+- 0.0007). The constant was not statistically significant though.

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.

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