IOW Earth system model documentation

This is the main documentation for the IOW earth system model (ESM) project.

In the following the intended concept of working with IOW ESM software package is described. Subsequently, the reader is lead to a step-by-step description of how to start using the package.

For the scientific background of this model please read [Karsten et al., 2023] and Coupling concept.

Note that the documentation is work in progress and by far not complete yet (see TODOs)!

Working concept

Before working with the IOW ESM it is important to understand the intended working concept. The basic idea for the workflow is that you clearly can separate the place where you store and/or develop the source code and where the model is running. The model will potentially run on many different machines such as supercomputers. However, the development should take place only in one central place to avoid the mess of having locally different and incompatible versions at different places.

This philosophy leads to a one-to-many relation as depicted in Fig. 1.


Fig. 1 Visualization of the intended working concept

In other words there is one place where you as a developer work, this might be your personal computer or an IOW server. From this place, which can be thought of as a control center you can develop the code, start a built and start simulations with subsequent post-processing. On the hand there are many places where the model can work which might be any server suitable to handle the planned simulations. These servers are refered to as targets or destinations in the following. The great advantage is, that you can always keep the sources on all targets in sync with your single personal working place.

Getting started

Be sure you have read the Readme at and fulfill all the prerequisites. You might then go to First use to set up everything and perform your first run.



Sven Karsten, Hagen Radtke, Matthias Gröger, Ha T M Ho-Hagemann, Hossein Mashayekh, Thomas Neumann, and H E Markus Meier. Exchange-grid coupling approach for the iow earth system model of the baltic sea region. in submission, 2023.

Documentation history


0.01.00 (in preparation)





  • initial version of jupyter-book documentation

  • not complete yet