Home

About FABM-OS

FABM-OS is a Python package for simulation of aquatic biogeochemistry, built on top of the Framework for Aquatic Biogeochemical Models (FABM). It focuses on spatially resolved (for instance, 2D or 3D) simulation using prescribed transports (e.g., currents, diffusivities). These are typically derived from prior simulation with a hydrodynamic model.

Currently FABM-OS supports the following transport engines:

• the Transport Matrix Method (TMM)

FABM-OS is being developed in the EU Horizons project NECCTON. Individual transport engines may be developed by other projects, for instance, TMM is developed in the EU Horizons project OceanICU.

Installation

First, 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.

From here on, we will be working in a terminal window. On Windows, open a terminal by choosing "Anaconda prompt" in the start menu.

With conda

Pre-built versions of FABM-OS are available for Windows, Linux and Mac. Unless you want to modify the FABM-OS source code or the underlying biogeochemical models, we recommend using such a pre-built version:

1. In your terminal, create an isolated environment with fabmos:

   conda create -n fabmos -c conda-forge -c bolding-bruggeman fabmos
   

   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.

2. Activate the fabmos environment in your terminal whenever you want to use FABM-OS:

   conda activate fabmos
   

   If you are using Windows and receive a warning stating that "You seem to have a system wide installation of MSMPI", we recommend you remove MPI from your conda environment with conda remove --force msmpi.

Now you are ready to run the examples that are distributed with FABM-OS.

To upgrade to the latest version of FABM-OS at any later time:

conda update -n fabmos -c conda-forge -c bolding-bruggeman fabmos

Build from source

If you want to modify the source code of the underlying biogeochemical models, or add new ones, you need to build FABM-OS from source:

1. In your terminal, obtain the latest stable release of the FABM-OS source code:

   git clone --recursive https://github.com/BoldingBruggeman/fabmos.git
   

   If this fails because the git command is not recognized, you will need to install a git client first. This can for instance be done with conda install -c conda-forge git.

2. Move to the directory with the FABM-OS source code and create an isolated environment for fabmos:

   cd fabmos
   conda env create -f <ENVIRONMENT_FILE>
   

   Here, <ENVIRONMENT_FILE> must be environment.yml on Linux and Mac, environment-win.yml on Windows.

   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 env create ... command.

3. Activate your new conda environment with conda activate fabmos, then build and install:

   pip install .

   If you want to see the progress of the build process in more detail, add -v.

   Before running pip install, you can customize the options used to build the underlying FABM library by providing a file named setup.cfg in <FABMOSDIR>. For instance, to include a new collection of biogeochemical models under institute name "ihamocc", the contents of this file would read:

   [build_ext]
   cmake_opts=-DFABM_EXTRA_INSTITUTES=ihamocc -DFABM_IHAMOCC_BASE=<IHAMOCC_DIR>
   

   Other options you could add to setup.cfg are debug=1 to build in debug mode and force=1 to empty the build directory before every build.

The source code for biogeochemical models can be found in <FABMOSDIR>/extern/fabm/src/models and <FABMOSDIR>/extern/fabm/extern. If you make changes there, you will need to repeat step 3 above.

To upgrade to the latest version of FABM-OS at any later time:

cd <FABMOSDIR>
git pull --recurse-submodules
conda env update -f <ENVIRONMENT_FILE>
conda activate fabmos
pip install .

To setup a FABM-OS development environment please go here.

Test cases

A set of standard test cases is provided in the fabmos-cases repository.