GENIE Main

From SourceWiki
Jump to navigation Jump to search

Philosophy & Design

GENIE (Grid ENabled Integrated Earth system model) is comprised of a number of state-of-the-art components contributed by various authors. genie-main acts as the linchpin and couples together the other components. GENIE has a strict hierarchical design. Anything which is common or shared between components should reside in genie-main. Maintenance of this hierarchy promotes clarity and massively benefits the task of extending and improving the model over time.

Genie-hierarchy.png

Values are exchanged between coupled components by argument passing. Variables are declared in genie-main and are passed to the relevant components through subroutine calls. This significantly aids traceability and debugging and avoids the pitfalls of spaghetti-code, which may use common blocks as 'secret passages' between components--the source of many a debugging headache!

Default Settings

GENIE has a number of compile-time and run-time settings. The default values of these create what may be termed the vanilla model. The default compile-time settings reside in the makefiles (primarily user.mak and makefile.arc). The run-time defaults are listed in runtime_defaults.sh as variable=value pairs.

Configuration Files

The repository contains a number of configuration files in the directory genie-main/configs. Any compile-time or run-time default can be overridden in a config' file. In this way we can morph the vanilla model into one of the numerous possible flavours of GENIE.

(The tests use special case config' files. The filenames of these end with _test.config. Please do not edit these files.)

Compile

Key files in the build system are:

user.mak
for details of your local setup
makefile.arc
main body of makefile variables and settings
makefile
rules and targets
testing.mak
holds the testing targets

Sub-makefiles in the various component directories are called from the top-level makefile (and useful variables such as the compiler name and flags are exported).

Top-level make targets include: cleanall, docs, tags (for emacs users), test, testebgogs, testbiogem, testglimmer, together with a number of assumedgood targets.

Run the Model

The model is run (and can be compiled) through genie_example.job. This BASH script makes use of other scripts, including:

user.sh
containing the details of your local run-time setup.
runtime_defaults.sh
vanilla model settings.
*.config
most likely you will also make use of a config' file. These are kept in genie-main/configs.
namelists.sh
translates your run-time settings into a format easily digested by Fortran (i.e. into namelists).

Source Code

Key source code files in genie-main include:

genie_control.f90
includes flags to control the component coupling as well as details of the model grid(s)
genie_global.f90
any common variables (i.e. those used during coupling)
constants, e.g. Pi
functions or subroutines used by more than one component model, such as those used for I/O or error checking for example, should be centralised. They should be placed in a separate module, so as to be accessed separately to any variables used for coupling.
genie.F
the overall coupling logic and time loop, which has a simple general form:
do koverall=1,koverall_total
  if .. then
    ..
  else
    ..
  end if
end do

(The files genie_ini_wrappers.f90 and genie_loop_wrappers.f90 serve to temporarily simplify genie.F and so aid a refactoring.)

The Future

In the future, the way we store the compile- and run-time settings is likely to change. A rationalised format (most likely in XML) will enable a number of different applications to read these settings and launch GENIE in different environments.