LoadingBuilding and installing
LoadingHow to cite
LoadingLicensing and copyright
LoadingList of standard variables
LoadingObtaining the source code
LoadingSetting up a simulation
LoadingTips and tricks
LoadingUsing FABM from a physical model
- Obtaining the source code
- Building and installing
- Setting up a simulation
- Specific hosts
Clone this wiki locally
The General Ocean Turbulence Model is a 1D water column model for marine and limnological applications.
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.
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
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.
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
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:
usemust be set to
truefor FABM to be used and
fabm.yamlto be read. By default it is
repair_stateclips 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 (
freshwater_impactshould be set to
falseto 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.
cnparmust be set to 1 (the default) to guarantee monotonicity (non-negative values) during vertical mixing.
w_adv_discrshould 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.
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
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:
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 (xobs–x)/τ, 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
<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]
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
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 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 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.
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
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
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.