README.md 3.89 KB
Newer Older
Carsten Lemmen's avatar
Carsten Lemmen committed
1
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.597629.svg)](https://doi.org/10.5281/zenodo.597629)
2
[![Build Status](https://travis-ci.org/platipodium/mossco-code.svg?branch=master)](https://travis-ci.org/platipodium/mossco-code)
Carsten Lemmen's avatar
Carsten Lemmen committed
3

4
5
6
7
8
9
This is the main directory of MOSSCO, also called `$MOSSCO_DIR`

To *quickly start*, read the file `QuickStart.md` or `QuickStart.pdf`

# Why MOSSCO?

Carsten Lemmen's avatar
Carsten Lemmen committed
10
11
12
13
14
15
16
17
18
19
20
21
MOSSCO, the "Modular System for Shelves and Coasts" is a framework for coupling
processes or domains that are originally developed in standalone numerical models.

The software MOSSCO implements this infrastructure in the form of a library of
components and couplers, and of example coupled applications.  The components
"wrap" external models used in coastal and shelf sciences, such as the Framework
for Aquatic Biogeochemistry (FABM), the General Ocean Turbulence Model (GOTM),
or the Delft3D erosion model (EROSED).  These wrapped components are then coupled
to each other in the Earth System Modeling Framework (ESMF).

MOSSCO is free software: you can redistribute it and/or modify it under the terms
of the GNU General Public License v3+.  MOSSCO is distributed in the  hope that
Carsten Lemmen's avatar
Carsten Lemmen committed
22
it will be useful, but WITHOUT ANY WARRANTY.  Consult the file
Carsten Lemmen's avatar
Carsten Lemmen committed
23
24
`doc/license/LICENSE.GPL` or http://www.gnu.org/licenses/gpl-3.0.txt for the full
license terms.
25

26
# What is here?
27

Carsten Lemmen's avatar
Carsten Lemmen committed
28
This main directory $MOSSCO_DIR contains four subdirectories
29

Carsten Lemmen's avatar
Carsten Lemmen committed
30
31
32
33
34
- `./src` for the library of drivers, components, and couplers.  You should not
have to change this unless you want to develop your own components;
- `./doc` for documentation. You really should read this or the online
documentation at <http://www.mossco.de/doc>;
- `./examples` for example applications to be used as templates.
35

36
37
## What is not here?

Carsten Lemmen's avatar
Carsten Lemmen committed
38
39
40
41
42
43
This directory produces only the libraries (from `./src`) and some example
executables (from `./examples`).  It does *not* contain forcing files or
parameters to run a scientifically usable simulation.   Please `git clone` the
separate repository located at `http://git.code.sf.net/p/mossco/setups` into a
directory of your choice (which you should point to with the environment
variable `$MOSSCO_SETUPDIR`).
44
45

# The documentation
Carsten Lemmen's avatar
Carsten Lemmen committed
46

47
To create the documentation with full installation instructions, type
48

Carsten Lemmen's avatar
Carsten Lemmen committed
49
		make doc
50

Carsten Lemmen's avatar
Carsten Lemmen committed
51
52
53
54
55
This generates a pdf file in `$MOSSCO_DIR/doc/mossco_reference_manual.pdf` and a
html version at `$MOSSCO_DIR/doc/reference_manual/html/index.html`. There is also
a pre-built online documentation at `http://www.mossco.de/doc` with detailed
installation instructions, if your system is missing latex/doxygen for building
the documentation yourself.
56
57
58

# Installation

Carsten Lemmen's avatar
Carsten Lemmen committed
59
60
61
To make the MOSSCO libraries, i.e. drivers, components, and utilities, you need
to have a compiled version of the Earth System Modeling Framework (ESMF), with
known location of the `esmf.mk` Makefile pointed to by the variable `$ESMFMKFILE`
62
63
64

Then, simply type

Carsten Lemmen's avatar
Carsten Lemmen committed
65
		make
66
67
68

To make some examples, type

Carsten Lemmen's avatar
Carsten Lemmen committed
69
70
71
72
		make examples

If you want to learn what you can do with MOSSCO examples, read the very short
tutorial in the file `$MOSSCO_DIR/QuickStart.md`
73

Carsten Lemmen's avatar
Carsten Lemmen committed
74
75
76
Should you encounter errors or annoyances (such that this just does not work out
of the box,  please consult the documentation, and visit the bugs database at
<http://www.mossco.de/bugs>.
77

Carsten Lemmen's avatar
Carsten Lemmen committed
78
79
80
81
More components and examples are built when external models, like FABM, GOTM,
GETM, or EROSED are installed  on your system. Please consult the documentation
for information on how to build MOSSCO with any of these external models. Or,
simply try
82

Carsten Lemmen's avatar
Carsten Lemmen committed
83
		make external
84
85
86

# Running an example

Carsten Lemmen's avatar
Carsten Lemmen committed
87
88
89
In the folder `$MOSSCO_DIR/examples/generic` several coupling specifications have
been compiled describing different coupled systems, see `QuickStart.md` to learn
quickly about one example.
90

Carsten Lemmen's avatar
Carsten Lemmen committed
91
92
93
The example executables should *not* be executed locally, but instead, you should
download/create a set of setups and run the examples within a setup.  Again, see
`QuickStart.md` or the full documentation for more information.