MOSSCO  alpha
Modular System for Shelves and Coasts
The Modular System for Shelf and Coastal Seas

Project goals

The overarching goal of the project Modular System for Shelves and Coasts (MOSSCO, www.mossco.de) is to bring together the distributed capacities in coastal ocean modelling in Germany and to build a common infrastructure for the national and international coastal research community.

MOSSCO will build a framework for a modular data and model system, an infrastructure, which has been identified as research demand by the Forschungsagenda Nord- und Ostsee within framework of the Research Agenda for Sustainable Development (FONA, www.fona.de). MOSSCO integrates physical, biological, chemical and geological modules in an exchangeable way. This modular infrastructure supports synoptic studies of coastal and shelf seas including their interfaces to adjacent Earth-system components, such as sediment, atmosphere, rivers and the open ocean. Benefits of this approach are most apparent for the description of cohesive sediments where strong interactions between the benthic and pelagic compartment and between hydrodynamic, biogeochemical (BGC), ecological and sedimentary processes are largely unresolved within state-of-the-art models. MOSSCO will therefore be applied to cohesive sediment dynamics and transport problems on two spatial coastal scales: In an application to the entire German North Sea and Baltic Sea, we will demonstrate the modular concept of MOSSCO, study sediment fluxes along the coast, and support other FONA projects. In a study of two estuaries, we will focus on the impact of maintenance dredging and channel deepening on water quality and ecosystem services, including potential effects of climate change. Using a webGIS frontend of the modular system, the estuarine results will be evaluated for their compliance with coastal policies.

How to obtain the code

While the public web site with documentation on the MOSSCO project is hosted at www.mossco.de, the software, blog, and bug tracker is hosted on sf.net/p/mossco. To obtain the code, change to the Git tab at that site, or follow this link sf.net/p/mossco/code.

Choose a local directory $MOSSCO_DIR, where you would like the mossco code to reside; you should make this an environment variable. 

export MOSSCO_DIR=$HOME/some/local/directory # for bash users
setenv MOSSCO_DIR $HOME/some/local/directory # for csh users

The code is available via git for read-only access. If you don't have git, you can download and install a suitable version from git-scm.com. 

git clone git://git.code.sf.net/p/mossco/code $MOSSCO_DIR

or, alternatively using the http protocol 

git clone http://git.code.sf.net/p/mossco/code $MOSSCO_DIR

If you are a developer and registered as a participant of the MOSSCO project, you may use a modified version of this command to gain write access.

If you do not have git, you may also download a zipped version of the source code from the "Files" section at sf.net/projects/mossco/files. Note, however, that these snapshots may be outdated at the time of your download. Download the file to the directory where $MOSSCO_DIR points to, then unzip it.

Installing MOSSCO

MOSSCO has some necessary and some optional prerequisites. Please make sure you meet these prerequisites before you try to compile MOSSCO.

MOSSCO prerequisites

Necessary system prerequisites

Program Minimum version and alternatives
GNU Make >= 3.0
Fortran 2003 Compiler e.g. GNU >= 4.8.2, Intel >= 12.0, PGI >= 13.2
ESMF >= ESMF_7_1_0r, including beta versions

Optional system prerequisites

Program Minimum version and alternatives
NetCDF 3.6, preferably version 4
Message Passing Interface OpenMPI >= 1.7 or MPICH >= 3.0.4, or custom MPI

We recommend strongly that you delegate the installation of ESMF (including Fortran compiler, MPI, NetCDF) to your local tech support or IT department. Other versions of the necessary and optional required programs may also work, but have not necessarily been tested.

You may also try to go ahead with an existing lower version of any of the required software packages, report possible errors, and argue why you would like us to support your version. No argument, however, about the Fortran 2003 standard!

For help and hints on installing ESMF, MPI, and NetCDF, see the appropriate sections below. Please make sure to use the same compiler for all your software components.

  1. Choose a FORTRAN compiler
  2. Compile MPI for this specific compiler
  3. Compile NetCDF libraries with this specific compiler and MPI support
  4. Compile ESMF with matching NetCDF and MPI library settings

Documentation prerequisites

Program Minimum version and alternatives
Doxygen >= 1.8
Latex with pdf latex support

There is a pre-built documentation available online at mossco.de/doc

Installing MPI and NetCDF

Quite likely, a version MPI and NetCDF are preinstalled on your system. If not, it is preferable to use your package manager (Yast, zypper, apt, port, etc. ...) to install these programs. Make sure that both MPI and NetCDF are compiled with the same Fortran 2003 compiler that you would like to use for ESMF and MOSSCO subsequently. Often, this is not the case (unless you're using a very recent operating system), so please check carefully. We experienced a lot of difficulties and bugs with outdated compilers, and mismatches between the compiler (and respective libraries) used for the different requirements for MOSSCO. You may also consult the bug data base mossco.de/bugs for solving these problems.

For ESMF, you need the NetCDF C library. For GOTM and the NetCDF data components in MOSSCO, you need to install the NetCDF Fortran library (if using NetCDF > 4.1.3).

Installing ESMF

Decide on a directory where to put the ESMF source, and set the environment variable $ESMF_DIR to point to this directory. Decide on a directory where to put the ESMF installation, and set the environment variable ESMF_INSTALL_PREFIX=$HOME/opt`.

  • download the git repository of esmf:
    git clone git://esmf.git.sourceforge.net/gitroot/esmf/esmf $ESMF_DIR
  • change to this directory :
    cd $ESMF_DIR
  • checkout the ESMF_7_1_0r tagged version:
    git checkout ESMF_7_1_0r
  • set ESMF's environment variables (these can be a lot, see below and consult the ESMF user guide for details)

An example environment for ESMF could look like this:

Environment variable value
ESMF_DIR $HOME/opt/src/esmf
ESMF_COMM mpich2
ESMF_NETCDF split
ESMF_NETCDF_INCLUDE $HOME/opt/include
ESMF_NETCDF_LIBPATH $HOME/opt/lib
ESMF_LAPACK netlib
ESMF_PIO internal

See the ESMF manual for a complete list of ESMF environment variables and their relevance.

  • build and install ESMF by issuing make
  • for MOSSCO and the ESMF tools to work, you need to define the environment variable $ESMFMKFILE, e.g.

Alternatively, you can automate this process by using the script $MOSSCO_DIR/scripts/install/install_esmf_versions.sh. This will read some environment variables

ESMF_COMPILERS, ESMF_TAGS, ESMF_COMMUNICATORS

, or assume default values and then install ESMF for you.

Environment variable value
ESMFMKFILE $HOME/opt/lib/libg/Linux.gfortran.64.mpich2.default/esmf.mk

Auto-installing external programs

Some external software packages will be installed for you by MOSSCO, if you like. These are

  1. GOTM General Ocean Turbulence Model
  2. GETM General Estuariene Transport Model
  3. FABM Framework for Aquatic Biogeochemical Models
  4. EROSED DELFT3D Erosion/Sedimentation Module
  5. FLIBS Fortran utility library
  6. FJSON JSON Fortran implementation

All these software packages will be downloaded to a subdirectory of $MOSSCO_DIR/external when you issue 

make external

You may have to set certain specific environment variables for these external packages, we recommend to set

Variable Package
NETCDF_VERSION GETM
NETCDF GOTM
FORTRAN_COMPILER GOTM, FABM

Also note that FABM and GOTM have cmake as a dependency.

Using external programs

You can and should use MOSSCO with your own software packages. We have already implemented a structure for the following packages

  1. FABM
  2. GOTM
  3. GETM
  4. HAMSOM
  5. TRACER
  6. EROSED

MOSSCO is aware of these packages as soon as you set the environment variables $MOSSCO_FABMDIR, $MOSSCO_GETMDIR, etc. These environment variables should point to the location of your software package. MOSSCO will detect it, and build it according to rules we defined in $MOSSCO_DIR/src/Rules.make.

Building MOSSCO

To create the MOSSCO libraries, simply issue make in your $MOSSCO_DIR. This will automaticall build the src target and provide the libraries in $MOSSCO_DIR/lib/$FORTRAN_COMPILER

To create the documentation (the file you're reading right now), issue

make doc

(don't worry too much about the warning messages that occur with outdated doxygen version. Also, some of the heading and table markup may not render correctly with old doxygen versions). If you do not have doxygen installed, you can alternatively consult the fairly recent online documentation at www.mossco.de/doc, or download a - probably outdated - pdf of the documentation from sf.net/projects/mossco/files/Reference%20Manual/.

To create the examples and test your installation, issue

make examples

Then change to the examples subdirectories and run the testcases (see later sections below)

To clean everything and start anew, type

make distclean

Summary settings

It may be convenient for you to assemble all variable settings in a shell resource file or add variable settings to your shell's login commands. Only very few environment variables should be set after your first installation.

Sample setting for bash could look as follows 

export MOSSCO_DIR=${HOME}/opt/mossco/code
export NETCDF_VERSION=NETCDF4
export ESMFMKFILE=/opt/esmf/lib/libO/Linux.gfortran.64.openmpi.ESMF_7_1_0r/esmf.mk

For csh you would, in a similar fashion, say 

setenv MOSSCO_DIR ${HOME}/opt/mossco/code
setenv NETCDF_VERSION NETCDF4
setenv ESMFMKFILE /opt/esmf/lib/libO/Linux.gfortran.64.openmpi.ESMF_7_1_0r/esmf.mk

Reporting errors

Bugs as well as annoyances and feature requests are collected in a bug tracker located at https://sf.net/p/mossco/tickets/. Please search for an existing ticket before reporting a new one.

Do report any issue that you observe, even if this later turns out to be a problem related to your local computing environment and not to the MOSSCO code itself. We encourage to document any problem that you encountered during the installation of MOSSCO: someone else might have the same issue and could profit from your experience.

You are also welcome to fix errors yourself, commit them in your local repository, and upload the patch to the bug tracker. If you would like to get involved more, you are welcome to join our team. Please contact us via the sourceforge project web site.

MOSSCO modular structure

MOSSCO itself is structured in a modular fashion, with usually three levels in a hierarchy. These hierarchies are drivers, components, and examples.

Hierarchy of examples, components, drivers, and external models

Driver

At the driver level, MOSSCO includes code that is specific to an external model. The driver level code serves as an interface level between the external model and the component. Typically

  • a driver uses modules from an external model
  • does not use esmf
  • replaces or complements external model codes
  • is hand-coded

Component

At the component level, MOSSCO includes code that exhibits the data from external models wrapped in an ESMF component. The component level code is a major product of MOSSCO, and should be integrateable into other ESMF coupled codes.

  • a component does not use modules from an external model
  • a component uses a driver
  • is a fully specified ESMF component, i.e. contains SetServices, Initialize, Finalize, and Run routines
  • handles an externally provided clock
  • creates fields on which the external model data is represented
  • is hand-coded or automatically processed (with the scripts/create_component.py script)

Example

At the example level, MOSSCO provides examples of ESMF coupled modular systems. The example level code is a major product of MOSSCO, providing both scientifically exploitable coupled systems, as well as template code for user defined couplings.

  • an example represents a complete compile-time coupled system
  • results in a application, that is executed in a setup (see below)
  • automatically processed (with the examples/generic/create_coupling.py script), or, for reference, hand-coded.

MOSSCO status

The MOSSCO system was successfully tested on the following machines and environments. Please report successful testing on your machine (e.g., in the project wiki), and issue a new tag, if you area developer.

Successful compilation and execution of examples

Operating System Compiler Configuration Machine Status
Ubuntu Linux 3.8.0 gfortran-4.7.3/mpich2 FABM/ESMF phy-203 (IOW, kk) complete
SUSE Linux 2.6.16 ifort-12.1 FABM bicegate (HLRN, kk) complete
SUSE Linux 3.0 ifort-12.1.5 FABM ICE-X (BAW) complete
OSX 10.14 gfortran-8.3/clang-6.0/openmpi ESMF/FABM/GOTM sugarglider (cl) complete
Redhat Linux 2.6 intel14/impi  ESMF/FABM/GOTM ocean (cl) complete
Ubuntu Linux 4.13 gfortran-7/clang-4/openmpi FABM/ESMF/GOTM ksez8002 (cl) complete
Redhat Linux 3.10 gfortran-4.8/openmpi  FABM/ESMF/GOTM ifksrv (cl) complete
Redhat Linux 2.6 intel-16/impi FABM/ESMF/GETM/SCHISM mistral (cl) complete

We are working on testing the pgfortran and nag compiler on different systems.

Coupling strategy

[This section is experimental and a Request For Comments] Analogous to FABM, all components to MOSSCO that are available at compile time will be compiled and aggregated in [a single, multiple?] library in $MOSSCO_DIR/lib/$FORTRAN_COMPILER. At run-time, only those components that are used, are executed [this calls for dynamic loadable libraries]. The coupling itself is described in a text file, with a defined YAML structure [also add namelist, SiSi, CDL as allowed meta specifications]. A couping could be described as follows

coupling:
- components: [GOTM FABM0d]
interval: 40 min
- components: [GOTM FABMSED]
interval: 60 min
- components: [FABM0D GOTM]
interval: 90 min
direction: forward
- components: [FABMSED FABM0d]
interval: 60 min
direction: both

This example describes a system of 3 coupled components [find a shorter way to specify this?] and the data exchange intervals between these components. Within the coupling structure, a pair of components is specified with an update interval of data exchange and (optionally) the direction of coupling. Direction can be any of forward, backward, and both, the default value is forward coupling.

In this example, the GOTM component provides data to FABM0D at 40 min intervals and to FABMSED at 60 min intervals. FABMSED provides data to FABM0D at 60 min intervals, and FABM0D provides data to GOTM at 90 minutes, and to FABMSED at 60 minutes intervals (note the direction "both" argument).

During initialize, the components add alarms with the specified interval to the parent clock [demonstrate that this works], each alarm obtains as attributes the meta-information about each two-way coupling.

The parent clock in the top level component, which calls FABM0D, GOTM and FABMSED repeatedly in its Run() routine, examines its alarms for those next ringing ones and calls each component with a time duration until the next alarm suitable for that component. It then advance its own clock to the next alarm time, exchanges data, and calls the Run() routines of the two components whos alarm had triggered with a time duration until the next alarm related to each component.

In our example above. 1) GOTM and FABM0D are run for 40 mins, FABMSED for 60 mins 2) at t=40 GOTM gives data to FABM0D, GOTM and FABM0D are run for another 20 minutes 3) at t=60 GOTM and FABM0D give data to FABMSED, FABMSED gives data to FABM0D; GOTM and FABM0D are run for 20 mins, FABMSED for 60 mins. 4) at t=80 GOTM gives data to FABM0D, GOTM and FABM0D are run for 10 mins 5) at t=90 FABM0D gives data to GOTM, both are run for another 30 minutes 6) at t=120, steps (1) and (2) are repeated.

Timers and alarms

Running the testcases

There are several examples that you can run, amongst them

  • a FABM standalone sediment driver (in examples/standalone/omexdia_p)
  • a FABM/ESMF sediment component (in examples/esmf_sediment)
  • a GOTM/ESMF test case driver (in examples/esmf_gotm)
  • an empty ESMF test case driver (in examples/esmf_empty)
  • an erosed test case (in examples/standalone/erosed)
  • a coupled A/O test case (in examples/esmf_remtc)
  • a FABM0D / FABM sediment combined test case (non-functional yet)

The FABM standalone sediment driver

All configuration files are contained in the example. Run

(cd $MOSSCO_DIR/examples/standalone/omexdia_p ; ./omexdia_p_test)

The ESMF/FABM sediment driver

All configuration files are contained in the example. Run

(cd $MOSSCO_DIR/examples/esmf/sediment ; ./sediment)

The GOTM testcase driver

You need to download the GOTM test cases first to a directory of your choice. Let's assume your GOTM test cases should be installed in the directory $GOTMCASEDIR, then run

git clone git://git.code.sf.net/p/gotm/gotm-cases $GOTMCASEDIR

To run the northern North Sea annual testcase, issue the following

(cd $GOTMCASEDIR/nns_annual ; $MOSSCO_DIR/examples/esmf/gotm/gotm)

The FABM 0d driver

Prerequisites are both FABM and GOTM. FABM has to have the mossco driver compiled, in order to use MOSSCO's FABM-0d driver:

make -C $FABMDIR/src mossco

Then compile MOSSCO, go to $MOSSCO_DIR/examples/esmf/fabm0d and run the example:

(cd $MOSSCO_DIR/examples/esmf/fabm0d ; ./fabm0d)

All configuration files are contained in the example.

erosion-sedimentation (erosed) test case

Prerequisite for this test case is ESMF. You also need to obtain original Delft3D routines. Create a directory $EROSED_DIR, and get up-to-date sources via subversion

svn checkout https://svn.oss.deltares.nl/repos/openearthtools/trunk/programs/SandMudBedModule/03_Fortran/example/example $EROSED_DIR

Access to the Delft3D open source repository is restricted to registered users. You can register at oss.deltares.nl (look at the top right)

After compilation of the example, you can run it in the local directory.

References

mossco
Collection of modules for MOSSCO utilities.
Definition: mossco.F90:18