The General Ocean Turbulence Model is a 1D water column model for marine and limnological applications.
Building GOTM-FABM from scratch
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
This will create a new
gotm directory with the GOTM source code. For details see the GOTM website.
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.
Now download the FABM code. If you are using a stable GOTM release, take note of the corresponding FABM version (mentioned in the GOTM release notes). Then download the required stable FABM release as a zip or tar.gz file. Otherwise, if you are using the developer's version of the GOTM code, check out the latest FABM code 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 build GOTM with FABM support, make sure you have CMake 2.8.8 or higher and a supported Fortran compiler. Then follow our platform-specific instructions for running CMake; you need to specify
<GOTMDIR>/src as the source directory and set option
<GOTMDIR> is the directory with GOTM source code and
<FABMDIR> is the directory with FABM source code.
On Linux-like systems, building is typically achieved by executing something like:
mkdir -p ~/build/gotm && cd ~/build/gotm cmake <GOTMDIR>/src -DFABM_BASE=<FABMDIR> make install
This will produce a GOTM executable at
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 gotmrun.nml, gotmmean.nml, etc.).
In addition, GOTM provides access to several settings that control the interaction between GOTM and FABM. These settings are configured in
gotm_fabm.nml, which must be present. A working copy of this file is provided with the FABM source code at
<FABMDIR>/testcases/GOTM/gotm_fabm.nml. You can get started quickly by copying this file to the directory with your GOTM setup.
An example of the contents of
gotm_fabm.nml is shown here:
&gotm_fabm_nml fabm_calc = .true., cnpar = 1.0, w_adv_discr = 6, ode_method = 3, split_factor = 1, bioshade_feedback = .true., bioalbedo_feedback = .true., biodrag_feedback = .true., repair_state = .false. salinity_relaxation_to_freshwater_flux = .false. no_precipitation_dilution = .false. save_inputs = .false. /
An overview of these settings is given in the following table:
||Whether to use FABM. If this is not set to
||“Implicitness” of numerical scheme used for diffusion. Common values are: 0 = fully explicit (forward Euler), 1st order accurate in time; 0.5 = Crank-Nicolson, 2nd order in time; 1 = fully implicit (backward Euler), 1st order in time. Only a value of 1 preserves monotonicity (including non-negativity).||1|
||Numerical scheme used to solve the advection equation that describe residual vertical movement (sinking, floating, active movement) of biogeochemical tracers. Possible values: 1 = 1st order upwind, monotone, 3 = 3rd order upwind, non-monotone, 4 = 2nd order upwind with Superbee limiter, monotone, 5 = 2nd order upwind with MUSCL limiter, monotone, 6 = 3rd order upwind with ULTIMATE QUICKEST limiter, monotone. If needed, GOTM will used multiple iterations to satisfy the CFL condition.||6|
||Numerical method use to time-integrate local sink and source terms. Possible values: 1 = Forward Euler; 2 = Runge-Kutta 2; 3 = Runge-Kutta 4; 4 = 1st order Patankar, positivity-preserving, non-conservative; 2nd order Patankar, positivity-preserving, non-conservative; 7 = 1st order Modified Patankar, positivity-preserving1, conservative2; 8 = 2nd order Modified Patankar, positivity-preserving1, conservative2; 10 = 1st order Extended Modified Patankar, positivity-preserving, conservative; 11 = 2nd order Extended Modified Patankar, positivity-preserving, conservative.||3|
||Number of biogeochemical time steps per external (GOTM) time step. This parameter may be increased to improve the stability and accuracy of biogeochemical computations, as well as the likelihood that constraints such as non-negativity are respected. However, increasing this parameter reduces performance.||1|
||Allow feedback from biogeochemistry to temperature (heating through light absorption).||
||Allow feedback from biogeochemistry to surface albedo.||
||Allow feedback from biogeochemistry to wind drag coefficient.||
||Whether to clip values of biogeochemical state variable to the nearest boundary when they lie outside their valid range. 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 parameter off. If you consider switching it on, it is recommended to verify first whether the true model solution respects the variable bounds, by increasing
||Whether to disable the effect of surface freshwater fluxes (precipitation, evaporation) on biogeochemical variables (NB: biogeochemical models can separately exclude specific variables from being affected by freshwater fluxes). This option can be activated to close the column for mass, in order to check the conservation properties of biogeochemical models.||
||Whether to translate the relaxation-induced change in column-integrated salt into a surface freshwater flux, and impose that (as precipitation or evaporation) on biogeochemical variables. Activating this ensures that the changes in total salt are mirrored by changes in the total of conserved biogeochemical quantities. However, this is non-physical and may perturb the depth-structure of variables. It should be used only if salinity relaxation is meant to represent precipitation/evaporation.||
||Whether to include prescribed biogeochemical variables in GOTM output.||
1These schemes preserve positivity by selectively dampening sink terms in the model. To allow this, models should provide their source and sink terms in the form of production and distribution matrices, see Burchard et al. 2003. If models instead provide bulk rates of change (as is the default in FABM), the positivity-preserving property is lost, and the schemes are simply a very expensive type of Runge-Kutta scheme.
2These schemes are conservative only under particular circumstances, as described in Bruggeman et al. 2007. Typically, they are conservative for single-currency models (e.g., carbon-only, nitrogen-only).
Prescribing biogeochemical variables
In GOTM, you can prescribe values for biogeochemical variables by creating configuration file
fabm_input.nml. 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 are specified in
fabm_input.nml in a single
observations namelist for each observed variable. This namelist can contain the following parameters:
|parameter||meaning||data type||default value|
||name of the prescribed variable in FABM. This name consists of the name of the model instance defined in
||path to the data file containing the observations. Cannot be used in combination with
||the index (column number) of the variable in the data file. Only used in combination with
||constant value to use. Cannot be used in combination with
||Time scale at which the model variable is relaxed towards the prescribed values, in seconds. This can be used only if
||real||1015 s (no relaxation)|
For instance, an initial nutrient profile can be imposed for the NPZD model by adding:
&observations variable = 'nut/c' 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:
&observations variable = 'nut/c' file = 'obs.dat' index = 2 /
index 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 noted above, this should be used with caution!). Internally, this is implemented by imposing an additional source term (xobs–x)/τ, with xobs denoting the observed value, x denoting the modelled value, and τ denoting the relaxation time in seconds. Relaxation is enabled by specifying the relaxation time in the namelist, as variable
&observations variable = 'nut/c' 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:
&observations variable = 'carbonate/mole_fraction_of_carbon_dioxide_in_air' file = 'pco2a.dat' /
Here, "carbonate/mole_fraction_of_carbon_dioxide_in_air" specifies the name of the surface pCO2 dependency declared by the "carbonate" model instance.
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 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 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 precede the start time of the simulation, and the time of the last observation must lie beyond 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.
GOTM will conserve biogeochemical quantities (e.g., totals of chemical elements), provided the biogeochemical model does so itself (e.g., in a 0D setup). 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 model is designed to conserve mass, you will need to pay attention to a few GOTM settings in order to ensure that mass conservation is achieved during the simulation:
- ensure that surface elevation is constant throughout the simulation (set
obs.nml). With variable surface elevation, GOTM will pull in/push out water horizontally to allow the layers to compress or inflate. 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
gotm_fabm.nml) 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.