Skip to content
jornbr edited this page Nov 10, 2020 · 44 revisions

About GOTM

The General Ocean Turbulence Model is a 1D water column model for marine and limnological applications.

Building GOTM-FABM from scratch

Download code

We recommend you use the latest (developer's) version of the GOTM source code. This can be obtained from its Git repository:

git clone https://github.com/gotm-model/code.git gotm
cd gotm
git submodule update --init --recursive

This will create a new gotm directory with the GOTM source code. For details see the GOTM website. The git submodule command is needed to pull in additional code bases that GOTM depends on, including FABM itself.

Note that if you intend to use gotm-lake, that is, GOTM with support for inflows, outflows and hypsograph, you will need to switch to the "lake" branch after cloning the GOTM repository. To do so, execute git checkout lake from within the gotm directory.

Build

To build GOTM, make sure you have CMake 3.0 or higher and a supported Fortran compiler. Then follow our platform-specific instructions for running CMake; as source code directory, specify the directory where you clone GOTM (gotm in the above).

On Linux-like systems, building is typically achieved by executing something like:

mkdir -p ~/build/gotm
cd ~/build/gotm
cmake <GOTMDIR>
make install

This will produce a GOTM executable at ~/local/gotm/bin/gotm.

The location of the build directory is arbitrary; the above ~/build/gotm is merely a suggestion.

On Windows you can perform the same steps through the "CMake (cmake-gui)" program.

Setting up a simulation with FABM support

As always in FABM, the main configuration step is to provide a fabm.yaml configuration file, which must be placed in the directory with your GOTM setup (i.e., the directory that also contains gotm.yaml).

In addition, GOTM provides access to several settings that control the interaction between GOTM and FABM. These settings are configured in gotm.yaml under the section entitled fabm.

An example of the this section is shown here:

fabm:                                    # Framework for Aquatic Biogeochemical Models
   use: true                             # enable FABM [default=false]
   freshwater_impact: true               # enable dilution/concentration by precipitation/evaporation [default=true]
   feedbacks:                            # feedbacks to physics
      shade: false                       # interior light absorption [default=false]
      albedo: true                       # surface albedo [default=false]
      surface_drag: true                 # surface drag [default=false]
   repair_state: false                   # clip state to minimum/maximum boundaries [default=false]
   numerics:
      ode_method: 1                      # time integration scheme applied to source terms [1=Forward Euler, 2=Runge-Kutta 2, 3=Runge-Kutta 4, 4=first-order Patanker, 5=second-order Patanker, 7=first-order modified Patanker, 8=second-order modified Patanker, 10=first-order extended modified Patanker, 11=second-order extended modified Patankar; default=1]
      split_factor: 1                    # number of substeps used for source integration [min=1; max=100; default=1]
      w_adv_discr: 6                     # vertical advection scheme for settling/rising [1=first-order upstream, 3=third-order upstream-biased polynomial, 4=third-order TVD with Superbee limiter, 5=third-order TVD with MUSCL limiter, 6=third-order TVD with ULTIMATE QUICKEST limiter; default=6]
      cnpar: 1.0                         # "implicitness" of diffusion scheme [fraction; min=0.0; default=1.0]
   input:

Each setting is documented in the comments on the same line. The following is worth keeping in mind:

  • use must be set to true for FABM to be used and fabm.yaml to be read. By default it is false!
  • repair_state clips biogeochemical state variable that lie outside their valid range to the nearest boundary. Out-of-range values usually indicate problems with the biogeochemical model or the selected numerical schemes. Clipping values will obscure this. It is therefore recommended to leave this setting to false. If you consider switching it on, it is recommended to verify first whether the true model solution respects the variable bounds, by decreasing the model time step (dt)
  • freshwater_impact should be set to false to achieve perfect mass conservation. That is because non-lake versions of GOTM do not let precipitation/evaporation affect surface elevation (i.e., total water content); therefore any dilution or concentration of tracers would not be accompanied with the change in water volume necessary to achieve mass conservation. This restriction was lifted in the lake branch of GOTM.
  • cnpar must be set to 1 (the default) to guarantee monotonicity (non-negative values) during vertical mixing.
  • w_adv_discr should be any other value than 3 to guarantee monotonicity (non-negative values) during vertical movement through the water (sinking, floating, active movement). The use of higher order schemes (4,5,6) is recommended.

Prescribing biogeochemical variables

In GOTM, you can prescribe values for biogeochemical variables by adding entries under the fabm/input section (empty by default, as shown above). This can serve different purposes:

  • To provide a depth-varying initial condition (profile) for pelagic biogeochemical variables.
  • To provide external dependencies to a biogeochemical model that requires these. For instance, to specify a time-varying partial pressure of atmospheric CO2, needed by the carbonate chemistry model to calculate air-sea exchange of CO2.
  • To override the values of biogeochemical variables during simulation. For state variables, this can be achieved by relaxing variable values to prescribed values; for diagnostic variables, this is done by having prescribed values replace model-provided values. This option should be used with caution, as the combination of prescribed and modelled values in model calculations can cause unexpected behaviour, including severe violation of mass balances.

Prescribed variable values each have their own section in gotm.yaml under fabm/input. Such a section looks as follows:

<VARIABLE_NAME>:                               # name of the variable as known to FABM
   method: 0                                   # method [0=constant, 2=from file; default=0]
   constant_value: 0.0                         # value to use throughout the simulation [default=0.0]
   file:                                       # path to file with time series [default=]
   column: 1                                   # index of column to read from [default=1]

The variable is configured to either remain constant (method: 0), in which case constant_value will be used, or to be read from file (method: 2), in which case it will be read from file. In the later case, you can optionally also specify the column in the file to read from. The format of these files is discussed further down.

If the variable should remain constant, this can also be specified more compactly with:

<VARIABLE_NAME>: <VALUE>

If the variable in question is a state variable, the specified value will only be used for initialization. If you want to override the variable value during the simulation, you can relax modelled values towards the observations (use with caution! it can easily lead to unstable models and/or loss of mass balance). This is implemented with an additional source term (xobsx)/τ, with xobs denoting the observed value, x denoting the modelled value, and τ denoting the relaxation time in seconds. Relaxation is configured by specifying the relaxation time scale τ as relax_tau in the variable's section in gotm.yaml:

<VARIABLE_NAME>:                               # name of the variable as known to FABM
   method: 0                                   # method [0=constant, 2=from file; default=0]
   constant_value: 0.0                         # value to use throughout the simulation [1e-6; default=0.0]
   file:                                       # path to file with time series [default=]
   column: 1                                   # index of column to read from [default=1]
   relax_tau: 864000                           # relaxation time scale [s; default=1e15]

Examples

nut/c:
   method: 2
   file: nut.dat

Here, "nut/c" references state variable "c" (concentration) defined by the "nut" model instance; "nut.dat" is the name of the file containing the observations (format described below).

If an observations file contains multiple variables, the namelist may also specify the index of the variable in the file, like so:

nut/c:
   method: 2
   file: obs.dat
   column: 2

Here, the column parameter indicates that "nut/c" is the second observed variable in "obs.dat".

For state variables, it is possible to relax modelled values towards the observations during the simulation as described in the previous section:

nut/c:
   method: 2
   file: nut.dat
   relax_tau: 864000.

In this case, relax_tau specifies a relaxation time of 864000 seconds (10 days).

Observations are prescribed in the same manner for all variables, whether they are depth-varying or depth-independent, and whether they are state variables, diagnostic variables, or external model dependencies. Thus, a time-varying partial pressure of atmospheric CO2 (a depth-independent model dependency) could be imposed by adding:

mole_fraction_of_carbon_dioxide_in_air:
   method: 2
   file: pco2a.dat

Here, "mole_fraction_of_carbon_dioxide_in_air" is FABM's standard name for surface pCO2. Note that this works only if one or more models in FABM register a dependency on this variable.

The actual format of an observations file depends on the variable type, which can be depth-varying (pelagic variables) or depth-independent (surface and bottom variables). These file formats are described in the following sections.

Depth-dependent variables

Depth-dependent variables use the GOTM “profile” file format, which describes a collection of depth profiles, each taken at a different time. Observation depths are profile-specific and can therefore vary with time. Profiles must be stored in a plain text file, and must appear in chronological order. Each profile begins with a single line that contains the date and time (UTC, ISO 8601 format, e.g., “1998-01-01 00:00:00”), the number of depth levels in the profile (an integer), and a flag that specifies the ordering of depth levels (a value of 1 denotes bottom to surface; any other value denotes surface to bottom); these three items must be separated by blanks (e.g., tab or space). Subsequent lines each represent observations at a single depth level. Such lines contain blank-separated values for the observation depth (a negative real number) and one or more observed variables. Thus, a single profile for a single variable could be stored as:

1998-01-01 00:00:00  13 2
-2.5  8.06867027
-7.5  8.08003998
-12.5  8.08532047
-17.5  8.0909996
-22.5  8.09687042
-27.5  8.10340977
-32.5  8.10943031
-37.5  8.11474991
-42.5  8.11933994
-47.5  8.12364006
-55.  8.12893963
-67.5  8.13638973
-85.5  8.14319992

Observation depths do not need to match the depths of the vertical layers in the simulation; GOTM uses linear interpolation to determine the values at layer centres. Model layers with a depth outside the observed range (above the most shallow observation depth or below the deepest observation depth) are assigned the nearest observed value.

GOTM requires that the time of the first profile precedes the start time of the simulation. A profile file may contain just a single profile, i.e., depth-varying values at a single point in time. This will suffice, for instance, if it is to be used as initial condition for a biogeochemical variable, in which case only a snapshot at the start time of the simulation is used. If the file contains multiple profiles, these must span the entire simulated period. GOTM then uses linear interpolation in time to obtain values throughout the simulated period.

Depth-independent variables

Depth-independent variables use the GOTM “observations” file format, which describes a collection of scalar values at different points in time. Observations must appear in chronological order. Every line describes observed values at a single point in time, and starts with the date and time (UTC, ISO 8601 format, e.g., “1998-01-01 00:00:00”), followed by the values of one or more observed variables. All items must be separated by blanks (e.g., a tab or space). For instance, an observations file with a single observed variable could contain:

1995-01-01 00:00:00   360.63
1996-01-01 00:00:00   362.36
1997-01-01 00:00:00   363.48
1998-01-01 00:00:00   366.49
1999-01-01 00:00:00   368.14
2000-01-01 00:00:00   369.40
2001-01-01 00:00:00   371.08
2002-01-01 00:00:00   373.17
2003-01-01 00:00:00   375.80
2004-01-01 00:00:00   377.50
2005-01-01 00:00:00   379.78

GOTM requires that the observations span the entire simulated period: the time of the first observation must equal (or precede) the start time of the simulation, and the time of the last observation must exceed (not just equal!) the end time of the simulation. GOTM uses linear interpolation in time.

Note on profile and scalar file formats: Comments (lines starting with ! or #) + empty lines are allowed in the files.

Mass conservation

GOTM will conserve biogeochemical quantities (e.g., totals of chemical elements), provided the biogeochemical model does so itself (i.e., when the sources minus sinks of a conserved quantity within a single grid box sum to 0). If the model includes non-conservative fluxes over the water surface (e.g., air-sea gas exchange) or the bottom (e.g., burial), or non-conservative sinks or sources in the interior, the totals of conserved quantities will predictably show drift over time. However, even if your FABM model is designed to conserve mass, you will need to pay attention to a few settings in gotm.yaml in order to ensure that mass conservation is achieved during the simulation:

  • ensure that surface elevation is constant throughout the simulation (set mimic_3d/zeta/method to 0). If surface elevation varies in time, GOTM will pull in/push out water horizontally to allow the layers to inflate/deflate. These horizontal fluxes also import/export biogeochemical variables, which means the column is no longer closed for mass.
  • ensure that precipitation does not dilute biogeochemical variables (set fabm/freshwater_impact to false). Otherwise, precipitation will dilute biogeochemical variables in the surface layer, but since this does not go combined with an increase in elevation (GOTM does not include the effect of precipitation on water level), you will experience loss of mass in the long run.