GENIE running an expt

Step1: Get the Model Source Code

GENIE is kept in a Subversion (SVN) respository. To learn more about accessing the GENIE code repository see downloading GENIE using SVN. Note that whenever possible, you should download one of the tested and stable releases, rather than just the most recent version, for example:

svn co http://source.ggy.bris.ac.uk/subversion/genie/tags/rel-2-1-0 --username genie-user ~/genie

See the GENIE versions page for more information on model releases, testing and the associated parameter tuning that accompanies a release.

Prerequisites

Note that in addition to the source code GENIE makes use of several applications and packages. You must have the following list of prerequisites installed on your computer, before you can run GENIE:

• Python.
• Perl (for the automatically generated documentation).
• GNU make.
• The BASH shell.
• The NetCDF libraries. See the using netCDF page for more information about downloading and installing netCDF.
• A C++ compiler, such as that from the GNU Compiler Collection (GCC).
• A Fortran compiler (including support for Fortran90). Compilers which are known to work with GENIE include:
  • Intel
  • PGI
  • Pathscale
  • Sun

NB the GNU Fortran compilers (g95 and gfortran) will not currently work with GENIE.

If you would like to use the GLIMMER ice sheet model in conjunction with GENIE, you will also need to download and install GLIMMER separately. See the GLIMMER downlaod page for more details on that.

Step2: Your Local Setup

Before you compile and run GENIE, you must provide information about, for example:

• where you have installed the source code,
• the Fortran compiler you are using,
• the location of the netCDF libraries that you have created

The simplest way to do this is to edit the files user.mak and user.sh in the directory genie-main. Comments in those files explain which lines need to be edited. NB if you place your source code in ~/genie and provide the dir ~/genie_output in which to collect your output files, your setup step will be considerably easier.

There is considerable flexibility in the way in which you can run the model and there are alternatives to the file edits above.

Step3: Test the Model

Before running an experiment, you must ensure that your installed version of the model is working correctly. To make this step as easy as possible, GENIE has a built in suite of tests which you can run using just a few simple commands.

First change directory to genie-main and type:

make cleanall

This will ensure that your model is in a pristine, uncompiled state (this is important as GENIE has a number of compile-time options). Now we will create a set of reference files against which we will compare all our future model outputs. Since the model has been tested before you downloaded the code, these files are assumed to be 'good'. Type:

make assumedgood

NB that we will run the above command only once, i.e. on all subsequent occassions (unless explicitly instructed) you will just give the test command below. (Note the generated 'assumedgood' files, held in your GENIE output directory, are your responsibility and you should ensure that they are not changed or deleted.)

This is the first juncture where you may encounter a compile-time or run-time error. If this is the case, please take a look at the compilation tips page or the run-time problems page. In the happy event that you have encountered no such problems, go on to type:

make test

There are two additional tests which make use of reference files kept in the source code repository--knowngood files. These tests exercise the non-chaotic flavours of the model and so we can create reference files which are comparable across machine architectures, compilers etc. To run these type:

make testebgogs
make testbiogem

If you are using GENIE in conjunction with the GLIMMER icesheet model, you should also run:

make assumedgood_ig_fi_fi_glim

remember, only once!:) and the test:

make testglimmer

Step4: Run from a Configuration File

Now that you have tested your model, you can begin running your experiments. The simplest way to do this is to use a configuration file. Happily, a number of these for various flavours of the model have been included with the source code you downloaded. Take a look in genie-main/configs (ignoring those filenames ending with '_test.config').

To run the model, simply type:

cd ~/genie/genie-main
make cleanall
./genie_example.job -f configs/<my_chosen_config_file>

Step5: Run using GENIELab

Once you have a tested model that you would like to study extensively, the GENIELab software can be used to execute and manage models instances on a range of computing platforms incuding the UK National Grid Service, local HPC clusters and Condor pools. GENIELab also provides an interface to the GENIE Database repository where model output can be archived and shared with colleagues. The OptionsMatlab design search and optimisation package is also included to enable users to tune the parameters of their model to improve the fit to observational data.

The GENIELab software is a collection of toolboxes for the Matlab problem solving environment. Instructions for downloading and installing GENIELab are available here.

The GENIE Toolbox Quick Start guide describes how to execute a model on the local machine

In order to run your GENIE model on remote platforms you need to package the binary and static input data files into a software archive (.zip or .tar.gz file). Utility functions are provided to help with this.

GENIE models are managed in the Matlab workspace by defining three descriptive data structures:

• Model configuration - structure specifying all configurable model parameters
• Local runtime environment - structure specifying the local environment for managing model instances]]
• Compute resource - structure specifying the compute platform on which to execute the model instances]]

Each model execution is invoked through a call to the gc_jobsubmit function