GENIE Main

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.

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 src/xml-config/xml/definition.xml.

NB. For a limited period, the old location for the default run-time settings also exists in parallel for backward compatibility--runtime_defaults.sh.

Configuration Files

The repository contains a number of XML 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.

NB. For a limited time only, the old format configuration files, i.e. those ending .config, are also in the config directory. These are not used by the framework by default, however.

(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.

src/xml-config/xml/definition.xml

vanilla model settings.

config/*.xml

overrides to the vanilla settings.

XSLT translation scripts in src/xml-config/xslt

to convert XML configuration information into namelist format for consumption by Fortran.

NB. For a limited time only, the old version, renamed to old_genie_example.job also exists. This uses:

user.sh

containing the details of your local run-time setup.

runtime_defaults.sh

vanilla model settings.

config/*.config

most likely you will also make use of a config' file.

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 key features of genie.f as of this date (09/11/2007) are summarised in a flow chart for genie.F. This is a PNG graphics file (SVG and JPG also available) created using the package understand for Fortran.

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.