Difference between revisions of "GENIE Main"

From SourceWiki
Jump to navigation Jump to search
m (GENIE:Main moved to GENIE Main)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
==Philosophy & Design==
 
==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 for and significantly benefits the task of extending and improving the model over time.
+
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.
  
 
[[Image:genie-hierarchy.png|center|700px]]
 
[[Image:genie-hierarchy.png|center|700px]]
  
Values are exchanged between coupled components by '''argument passing'''.  They are declared in genie-main and 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!
+
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==
 
==Default Settings==
  
GENIE has a number of compile-time and run-time settings.  The default values of these creates what may be termed as the ''vanilla'' model.  The default compile-time settings reside in the makefiles (user.mak and makefile.arc).  The run-time defaults are listed in '''runtime_defaults.sh''' as ''var=value'' pairs.
+
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==
 
==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 ''flavours'' available.
+
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.)
 
(The tests use special case config' files.  The filenames of these end with ''_test.config''.  Please do not edit these files.)
Line 21: Line 25:
 
Key files in the build system are:
 
Key files in the build system are:
  
; user.mak      : for details of your local setup
+
; '''user.mak'''     : for details of your local setup
; makefile.arc  : main body of makefile variables and settings
+
; '''makefile.arc''' : main body of makefile variables and settings
; makefile      : rules and targets
+
; '''makefile'''     : rules and targets
; testing.mak  : holds the testing targets
+
; '''testing.mak'''   : holds the testing targets
  
Sub-makefiles in the various component directories are called from the top-level makefile (and useful varibales such as the compiler name and flags are exported).
+
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.
 
Top-level make targets include: '''cleanall''', '''docs''', '''tags''' (for emacs users), '''test''', '''testebgogs''', '''testbiogem''', '''testglimmer''', together with a number of '''assumedgood''' targets.
Line 33: Line 37:
  
 
The model is run (and can be compiled) through '''genie_example.job'''.  This BASH script makes use of other scripts, including:
 
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.
 +
 +
===Old Version===
  
; user.sh : containing detail of your local run-time setup.
+
'''NB'''.  For a limited time only, the old version, renamed to '''old_genie_example.job''' also exists.  This uses:
; runtime_defaults.sh : vanilla settings.
+
; '''user.sh''' : containing the details of your local run-time setup.
; XXX.config : most likely you will also make use of a config' file.
+
; '''runtime_defaults.sh''' : vanilla model settings.
; namelists.sh : to translate your run-time sttings into a format easily digested by Fortran (namelists).
+
; '''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==
 
==Source Code==
Line 43: Line 54:
 
Key source code files in genie-main include:
 
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_control.f90''' : includes flags to control the component coupling as well as details of the model grid(s)
; genie_global.f90
+
; '''genie_global.f90'''
 
: any common variables (i.e. those used during coupling)
 
: any common variables (i.e. those used during coupling)
 
: constants, e.g. Pi
 
: constants, e.g. Pi
: functions or subroutines which should be common e.g. I/O or error checking (these should be in a separate module)
+
: 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
+
; '''genie.F'''
: the overall coupling logic and time loop
+
: the overall coupling logic and time loop, which has a simple general form:
 
<pre>
 
<pre>
 
do koverall=1,koverall_total
 
do koverall=1,koverall_total
Line 62: Line 73:
 
(The files ''genie_ini_wrappers.f90'' and ''genie_loop_wrappers.f90'' serve to temporarily simplify genie.F and so aid a refactoring.)
 
(The files ''genie_ini_wrappers.f90'' and ''genie_loop_wrappers.f90'' serve to temporarily simplify genie.F and so aid a refactoring.)
  
==The Future==
+
The key features of genie.f as of this date (09/11/2007) are summarised in a [[media:Flow-genie.png|flow chart for genie.F]]This is a PNG graphics file (SVG and JPG also available) created using the package ''understand for Fortran''.
 
 
In the future, the way we store the compile- and run-time settings is likely to changeA rationalised format (most likely in XML) will enable a number of different applications to read these settings and launch GENIE in different environments.
 

Latest revision as of 14:27, 26 March 2008

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

Old Version

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.