GENIE:GENIEToolboxTutorial

GENIE Toolbox Tutorial
The GENIE Toolbox has been designed to accommodate a wide range of computational resource on the Grid. Interfaces are provided for resources managed by the Globus Toolkit (v2.4), Condor (native, SSH, CondorWS) and Microsoft Compute Cluster. GENIE models can be submitted to systems running various operating systems including Linux/UNIX, Windows and MAC OSX. In such a heterogeneous environment it cannot be assumed that a compiler can be configured and used on a remote compute node. It is therefore necessary to build the GENIE model offline for any target system you intend to use before exploiting the Toolbox to use the computational Grid.

The GENIE Toolbox supports release rel-2-1-0 of the GENIE code as tagged in the CVS repository. This tutorial will demonstrate how to execute and manage this release of the GENIE framework on appropriate resource. We strongly recommend that you provide your own build(s) for production studies as described in the next section.

Preparing GENIE Model Archive
The GENIE toolbox provides a management and coordination layer for model binaries and their output data. The system does not, at the present time, interface to the CVS code repository and does not provide a compilation environment. It is therefore assumed that the user will provide a file archive (tar.gz or zip format) containing the model binary to be studied and any static input data files that this binary requires. To prepare such an archive:


 * Export the version of the code you wish to study from the GENIE CVS repository. We strongly recommend tagging the version of the code to be studied and checking out against this tag.
 * Compile and build the model binary for each target platform you intend to use on the Grid. At present, this is most easily achieved by invoking the genie_example.job script with the required changes to makefile.arc and using the appropriate config file for the study. Instructions for building GENIE on UNIX/Linux and Win32 platforms are available in the genie-main module directory.
 * If the model makes assumptions about the locations of input files (ie. input files that are not specified in the configuration files) or requires sub-directories to write output to then create an empty directory hierarchy and place the binary at the appropriate place (also copy the netcdf.dll file if required for a win32 run). Again, this is most easily achieved by editing genie_example.job, commenting out the actual genie.exe invocation and running the script – the runtime directory hierarchy is created and the binary copied to the appropriate location - it just remains to remove any configuration files that may have been written.
 * Archive the directory hierarchy containing the binary and input files. The Toolbox will assume that linux / unix archives are in the tar.gz format and that win32 archives are zip files.

Example
For a standard Linux build the following steps would create a suitable archive:  Checkout / Export the GENIE code from CVS using a release tag if applicable > cvs export –r rel-2-1-0 core Make any changes to makefile.arc and/or genie_example.job as appropriate for your local environment Comment out the execution of the genie.exe binary from the genie_example.job script</li> echo 'STARTING EXPERIMENT:' date echo 'ENDING EXPERIMENT:' Run the genie_example.job</tt> script using a config file if appropriate for your build</li> > cd genie-main > ./genie_example.job –f config/genie_ig_go_sl.config Create an archive containing the output directory structure, the GENIE binary and the input data files. E.g.</li> > cd .. > tar zcvf genie_ig_go_sl_runtime.tar.gz \ genie_output \ genie-main/data/input \ genie-main/inputdata \ genie-igcm3/data/input \ genie-goldstein/data/input \ genie-slabseaice/data/input \ genie-fixedchem/data/input \ genie-fixedicesheet/data/input </ol> The input data directories contain a lot of files that are only applicable to a particular build of the model. We recommend only adding files that your build requires to keep the archive size to a minimum.
 * 1) time ./genie.exe || ABORT EXECUTE

Job Submission
To execute a GENIE model using the toolbox three descriptive data structures must be created in the Matlab workspace. These variables provide a comprehensive description of the specific GENIE model configuration to execute, a local runtime environment in which model instances can be prepared for execution and a computational resource on which the simulation will be performed.

Configuration
Create a description of a specific instance of the GENIE model. At the Matlab command prompt enter:

<ol> >> configuration = genie_ig_go_sl_gaalbedofluxcorr1

configuration =

genie_main: [1x1 struct] genie_igcm3: [1x1 struct] genie_goldstein: [1x1 struct] genie_fixedchem: [1x1 struct] genie_fixedicesheet: [1x1 struct] genie_slabseaice: [1x1 struct] </ol>

This executes the genie_ig_go_sl_gaalbedofluxcorr1</tt> function which is a direct port of the genie_ig_go_sl_gaalbedofluxcorr1.config</tt> file from the GENIE CVS repository. The function has loaded a complete set of parameters for the GENIE-2 model comprising the IGCM atmosphere, the GOLDSTEIN ocean, slab sea-ice, fixed chemistry and fixed ice sheet modules. The genie_main</tt> field contains the parameters controlling the execution of the whole model. For the purposes of the demonstration we will reduce the total number of timesteps in the configuration so that the simulation lasts for a single month.


 * >> configuration.genie_main.Parameter.GENIE_CONTROL_NML.koverall_total = 720;</tt>

Runtime
A local runtime data structure is created to provide details about the locations of the model binary and a directory in which new model invocations can be managed. For the purposes of this demonstration we will initially execute the model on the local machine. The local runtime needs to provide the appropriate binary for the OS on which Matlab is running. The runtime for the demonstration binary is specified as follows:


 * Windows (Win32)
 * >> runtime.RuntimeArchive=fullfile('../demo/runtime','genie_ig_go_sl_runtime.zip');</tt>
 * >> runtime.RuntimeArchiveTool=fullfile('../demo/runtime','unzip.exe');</tt>
 * >> runtime.LocalRunDir='..\demo\runtime'</tt>
 *  </tt>
 *  runtime = </tt>
 *         RuntimeArchive: '..\demo\runtime\genie_ig_go_sl_runtime.zip'</tt>
 *     RuntimeArchiveTool: '..\demo\runtime\unzip.exe'</tt>
 *            LocalRunDir: '..\demo\runtime'</tt>


 * Linux / UNIX / Mac OSX
 *  >> runtime.RuntimeArchive=fullfile('../demo/runtime','genie_ig_go_sl_runtime.tar.gz');</tt>
 * <tt> >> runtime.LocalRunDir='..\demo\runtime'</tt>
 * <tt> </tt>
 * <tt> runtime = </tt>
 * <tt>        RuntimeArchive: '..\demo\runtime\genie_ig_go_sl_runtime.tar.gz'</tt>
 * <tt>           LocalRunDir: '..\demo\runtime'</tt>

Resource
The final data structure describes the computational resource on which the model will run. For this demonstration the model will be executed on the local machine. A utility script is provided for configuring the resource data structure:


 * <tt>>> resource = createResource</tt>


 * [[image:resourcetype.png|Type of resource]]


 * Select 'local'


 * [[image:resourceos.png|Operating System of the resource]]


 * Select the operating system of the machine you are running Matlab on


 * <tt>Please provide a short meaningful name for the resource:</tt>


 * Type: local machine


 * <tt>Please specify the maximum number of jobs that may be submitted to this resource [10]: >></tt>


 * Type: 1


 * <tt>Upload this resource to the database? Y/N [N]:</tt>


 * Select N

resource =

type: 'local' name: 'local machine' MaxJobs: 1 broker: 'fork' RemoteTargetOS: 'win32' RemoteFileSep: '\'