How to read the documentation

This document is the official scientific documentation of GOTM. Due to the fast and continuing evolution of GOTM, we have been looking for a new and flexible way of giving a comprehensive and up-to-date documentation for GOTM. We decided for the following strategy.

Every module of GOTM is accompanied by an introductory text on the general theory of the subject, including mathematical derivations, bibliographic references, and the definition of the most important variables. These introductory parts, which should give the reader a brief theoretical overview of what is coded in the modules, are expected to be relatively stable. References are given to more comprehensive introductory or advanced media for each subject.

For the actual documentation of the FORTRAN95 code, which is more likely subject to frequent changes and extensions, a different strategy has been followed. For every module, internal or external subroutine or function, a short piece of documentation in LATEX has been directly written into the code. These fragments of the documentation will be updated every time the code changes. We use a software called PROTEX, which looks into every FORTRAN file of GOTM, extracts the LATEX parts, and compiles some information about the FORTRAN interfaces, public member functions, public data members, defined parameters, etc. All these pieces of information are assembled by PROTEX to yield a nice documentation including table of contents, figures, tables, references, and formulae for each part of the program. The largest part of the report has been created in this way. Note that PROTEX looks for certain key words in the FORTRAN code to organise the structure of the final document. Therefore, don't be confused if you find things like !DESCRIPTION:, !INTERFACE:, !PUBLIC DATA MEMBERS:, etc, in the FORTRAN files. These are always preceded by an exclamation mark, and thus invisible for your FORTRAN compiler.

If you are new to GOTM, we recommend to completely go through the core parts of GOTM described in section 2, section 3, and section 4. In these sections, you will find also references to the relevant introductory literature. The other parts of this documentation should be used like an encyclopedia: you can look up things fast when you need more information about parts of the program. Extra comments can be found in the form of standard FORTRAN comments that should help users to find their way through the lines of the code.

A special status in this documentation has section 12 illustrating particular scenarios prepared for GOTM. This section contains useful information about the theoretical background and the implementation of each scenario currently available in GOTM. Scenarios range from simple test cases, like a turbulent Couette flow, to full oceanic applications including meteorological forcing and comparison to measured data. The most simple scenarios descibed in section 12 serve as a little tutorial, in which the key algorithms of GOTM are introduced in a practical way.

This documentation does not contain information about how to download, compile and run the code and the test cases. All information necessary to run GOTM on a number of well-known platforms is compiled at www.gotm.net. If you wish to directly contact to the GOTM developers, please write an e-mail to gotm-devel@googlegroups.com. All users of GOTM, who signed up on the GOTM web page, will be on the users' mailing list, gotm-users@googlegroups.com. Information about updates, bug fixes, and new versions of GOTM are communicated via this list.

Karsten Bolding 2012-12-28