GENIE running an expt

Step1: Model Source Code & Prerequisites

GENIE is kept in a Subversion (SVN) respository. Note that whenever possible, you should download one of the tested and stable releases, rather than just the most recent version on the 'trunk', for example:

svn co https://svn.ggy.bris.ac.uk/subversion/genie/tags/rel-2-4-0 --username=genie-user ~/genie

To learn more about accessing the GENIE code repository see downloading GENIE using SVN. See the GENIE versions page for more information on model releases, testing and the associated parameter tuning that accompanies a release.

If you experience problems using svn and you are behind a proxy server to the internet, edit the file .subversion/servers and inserting the lines (with their correct proxyHostname & portNumber):

• http-proxy-host = proxyHostname
• http-proxy-port = portNumber

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
  • GNU gfortran
  • or g95

GENIE can also be built for Windows platforms with a suitable build environment.

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 download page for more details.

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.

If you do need to install GENIE somewhere other than your $HOME directory-let's say the /scratch directory is convenient-you will need to edit the following:

in user.mak:

GENIE_ROOT        = /scratch/genie
OUT_DIR           = /scratch/genie_output

and in user.sh:

CODEDIR=/scratch/genie
OUTROOT=/scratch/genie_output

NB the symbol '~' is understood to be your home directory in the shell, i.e. in user.sh, but not in a makefile, i.e. it is not understood in user.mak.

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 in your working copy 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 we will run the above command only once, i.e. on all subsequent occassions 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, the run-time problems page and the Using NetCDF page. In the happy event that you have encountered no such problems, go on to type:

make test

There are three additional short 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
make testents

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

NB the tests make use of particular flavours of the model (as described in various 'config files) and, in general, they are unlikely to pass if you stray from these recipes. For example, if you change the default precision of the model (in user.mak) you cannot expect the tests to pass.

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, example configurations for various flavours of the model have been included with the source code you downloaded. Take a look at the XML files in genie-main/configs (ignoring those filenames ending with '_test.xml').

To run the 'GENIE-1' (i.e. EMBM atmosphere, GOLDSTEIN ocean and seaice) flavour of the model simply type:

cd ~/genie/genie-main
make cleanall
./genie_example.job -f configs/eb_go_gs.xml

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