GOTM

About GOTM

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

Support for data assimilation in GOTM is implemented in EAT.

Support for sensitivity analysis and calibration with GOTM is implemented in parsac.

Installing

Getting GOTM from Anaconda

Pre-built versions of the latest stable release of GOTM are available for Windows, Linux and Mac. These include the latest stable release of FABM. Unless you want to modify the GOTM or FABM source code yourself, we recommend using such a pre-built version:

1. Ensure you have Anaconda:

   • Linux/Mac: execute conda --version in a terminal
   • Windows: look for "Anaconda prompt" in the start menu

   If you do not have Anaconda, install Miniconda. This does not require root/administrator privileges.

2. Open a terminal (Windows: "Anaconda prompt" in the start menu) and create an isolated environment with GOTM:

   conda create -n gotm -c conda-forge gotm
   

   If you experience problems, we recommend you first execute conda update conda to ensure your conda is up to date. Should this fail because of lack of permissions, we recommend you install Miniconda. After you have an up-to-date conda, retry the conda create ... command.

3. Activate the gotm environment in your terminal whenever you want to use GOTM:

   conda activate gotm
   

   You should now be able to run GOTM. For instance, try gotm --version.

Building from scratch

If you want to modify the GOTM or FABM source code, for instance, to use new or modified biogeochemical models, you will need to build GOTM-FABM yourself:

1. Make sure you have:

   • CMake 3.13 or higher
   • a supported Fortran compiler
   • NetCDF with Fortran support

   If needed, you can obtain these from Anaconda with conda install -c conda-forge cmake fortran-compiler netcdf-fortran on Linux and Mac, or conda install -c conda-forge cmake m2w64-toolchain netcdf-fortran on Windows.

2. Download the source code

   We recommend you use the latest stable release of the GOTM source code. Make sure you then download the source code including submodules and extract the code to a directory of you choice. Alternatively, you can obtain the latest developers' version directly from GOTM's git repository: git clone --recursive https://github.com/gotm-model/code.git gotm. This puts the source code in a new gotm directory.

   Note that GOTM already comes with FABM (under extern/fabm); there is no need to get and build the FABM source code separately.

3. Create the build configuration in a new directory named build:

   cmake -S <GOTMDIR> -B build
   

   Here, <GOTMDIR> is the directory with the GOTM source code.

4. Build and install

   cmake --build build --target install
   

   This will produce a GOTM executable at ~/local/gotm/bin/gotm on Linux and Mac, and %LOCALAPPDATA%\gotm\bin\gotm.exe on Windows.

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 CO₂, needed by the carbonate chemistry model to calculate air-sea exchange of CO₂.
• 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 (x_obs–x)/τ, with x_obs 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 CO₂ (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 pCO₂. 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.