Skip to content

Home

Jump to bottom
Jorn Bruggeman edited this page Jan 4, 2026 · 56 revisions

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:

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 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 fabmos at any later time:

conda update -n fabmos -c conda-forge 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.yml

    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. This allows you to see which compiler was used, among others (provided you do not have an existing build directory).

    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 can add to the [build_ext] section of setup.cfg include:

    • debug=1 to build in debug mode
    • force=1 to empty the build directory before every build
    • compiler=<COMPILER_EXECUTABLE> to specify which Fortran compiler should be used

    Note that each of these options will need to be on its own seperate line.

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.

logo

Clone this wiki locally