Trait-based Adaptive Ecosystem Model (TAME)

This is a the development repository of TAME. TAME is a collection of FABM models and further utilities. TAME is currently under development and is not a production-ready product.

The history of TAME is the Model for Adaptive Ecosystems (MAECS), originally coded by Kai Wirtz and published as Wirtz & Kerimoglu (2016). It is a variation of a nutrient-phytoplankton-zooplankton-detritus (NPZD) ecosystem model, but different from other ecosystem models, it featured: - the physiological adaptation of allocation within phytoplankton, - optional loss terms by virus.

MAECS was used extensively in the FABM version 0 framework for Southern North Sea applications in the MOSSCO project (Wirtz 2019; Slavik et al. 2019; Nasermoaddeli et al. 2018; Lemmen 2018). The necessity to move to a new model resulted from - difficulties of porting to FABM version 1 and above, - strong reliance on namelists, - complexity of the code.

TAME will try to remedy the above difficulties, and it's concept is from the beginning targeted towards flexibility, user friendliness, and compatibility with the current version of the FABM framework.

Obtaining and operating TAME

All of TAME and its dependencies are free and open source software. To operate it locally on your computer, you need (1) a compilation toolchain and (2) the sources of TAME, FABM, and GOTM.

Compiler toolchain

TAME is written in the programming language Fortran and uses the NetCDF binary self-documenting output format. So you need a Fortran compiler and a compatible installation of the NetCDF developer library. The sources are hosted on a git repository, and the build is facilitated by cmake. The easiest way is to install those for your system in a package manager, such as apt, brew, or conda.

Typically on Ubuntu linux (and others) you would use apt apt install gfortran libnetcdff-dev cmake git

Typically on Linux or Mac with the homebrew package manager you would use brew brew install gcc netcdf-fortran cmake git

Typically on Linux or Mac with conda package manager you would use conda or mamba conda create -n tame python=3.12 conda activate tame conda install gfortran netcdf-fortran cmake git

Obtaining source codes

TAME itself is a model within the FABM framework, which relies on GOTM as a hydrodynamic driver. So you need to get download three software packages to get this to work. Before you do, decide on a directory where you install your sources and define the environment variables GOTM_BASE, FABM_BASE, and TAME_BASE to point to these. We will here assume they are all located in your $HOME/devel/ folder.

``` export TAMEBASE=$HOME/devel/tame export FABMBASE=$HOME/devel/fabm export GOTM_BASE=$HOME/devel/gotm

git clone https://codebase.helmholtz.cloud/kse/tame.git $TAMEBASE git clone https://github.com/fabm-model/fabm.git $FABMBASE git clone https://github.com/gotm-model/code.git $GOTM_BASE ```

As the 0d driver needs a stable version of GOTM, change to this one and also recursively download all GOTM dependencies (cd $GOTM_BASE && git checkout v6.0 && git submodule update --init --recursive)

How to build TAME

As TAME is a FABM model, we rely on the build structure implemented in FABM and give it separate arguments to also consider TAME in its model hierarchy. Therefore, the source directory we supply to CMake is $FABM_BASE. And it is good style to do an out-of-tree build, i.e., to compile in a directory separate from your sources. We will define this as $BUILD_GOTM, as GOTM is the default FABM host

``` export BUILDGOTM=$HOME/devel/build-gotm mkdir $BUILDGOTM

cmake -B $BUILDGOTM -S $FABMBASE -DFABMHOST=gotm -DFABMBASE=$FABMBASE -DFABMINSTITUTES="tame;bb" -DFABMTAMEBASE=$TAMEBASE -DGOTMBASE=$GOTM_BASE make ```

For more information on the FABM CMake build, consult their building and installing page.

The continuous integration setup on GitHub now includes automated checks for the Fortran components, ensuring they compile correctly and pass a basic runtime test using the 0D driver.

Note that -DFABM_INSTITUTES=tame will make FABM compile our models as the only available biogeochemical models. If you additionally want to have access to other biogeochemical models included with FABM, you can set FABM_INSTITUTES to a semi-colon separated list, e.g., -DFABM_INSTITUTES="tame;vims;iow", as in the example above.

You may also want to build the 0d model, which you achieve by changing the source directory to CMake

``` export BUILD0d=$HOME/devel/build-0d mkdir $BUILD0d

cmake -B $BUILD0d -S $FABMBASE/src/drivers/0d -DFABMHOST=0d -DFABMBASE=$FABMBASE -DFABMINSTITUTES="tame;bb" -DFABMTAMEBASE=$TAMEBASE -DGOTMBASE=$GOTM_BASE make ```

How to build the parser

The parser is contained in the folder ./parser. It is a simple C program and can be compiled with any suitable C compiler.

There is also a python template based parser in development in the ./python folder

Report when it is working/not working for you!

Build test with build chain suggested above

| System | Type | Compiler | Status | | ------ | ------ | ------------- | ------ | | quoll | arm64 | gfortran | | | femto | x86-64 | ifort | | | kuro | x86-64 | intel/openmpi | | | strand | x86-64 | ifort | |

License information

Copyright 2024-2025 Helmholtz-Zentrum hereon GmbH.

Code files in this repository are licensed under the GPL-3.0-or-later, if not stated otherwise in the file. Documentation files in this repository are licensed under CC-BY-4.0, if not stated otherwise in the file. Supplementary and configuration files in this repository are licensed under CC0-1.0, if not stated otherwise in the file. Please check the header of the individual files for more detailed information.

License management is handled with reuse. If you have any questions on this, please have a look into the contributing guide or contact the maintainers of TAME.

Contributing to TAME

We welcome contributions to TAME. See the contributing guide for details.

Rules for coding TAME

1. All rates and parameters provided are in per day basis. Time is always provided as day, and the conversion is done at the fabm host `_ADD_SOURCE_`.
2. Common global parameters are defined in the `tame_types`.
3. Functions are defined separately only if they are called more than once.
4. Use intuitive expressive names for variables.
5. Use pure and elemental function declarations in your functions for efficiency.

Global parameters

Global parameters are defined in the tame_types. For example: dayspersecond and secondperday are always used