3.2 Example of a minimum configuration file

In this chapter a sample configuration file is described. It contains only instructions which are really necessary for the execution of a simple model run (configuration files can be much more complex). The example presented here is stored in an appropriate example file (containing more than the configuration data presented here) and can be used, together with the parameter file presented in chapter 4.4.1, for the execution of a simple model run. In chapter 4.4.1 the complete mrun options which are necessary for the appropriate parameter file are described. Furthermore not all details of the configuration file are described here. Therefore you should take a look at the mrun documentation (sorry: this is only available in German, so far. If you think that you would profit from an English version, please give a message to the PALM group).

The following configuration data exclusively applies to model runs on the IBM Regatta hanni of the HLRN when using several processing elements (i.e. for the parallel version of the model). The proper installation of the model is presumed (see chapter 5.0). Furthermore it is supposed that the user is located in the directory $HOME/palm/current_version/SOURCE on its local computer. There are the FORTRAN source codes of the model (*.f90) as well as the configuration file (name: .mrun.config) and the make file (name: Makefile). The configuration file has the following contents (among other things):
  

% source_path $HOME/palm/current_version/SOURCE
% mainprog palm.f90
% use_makefile true
% fopts -O3:-g:-qrealsize=8:-Q:-q64:-qmaxmem=-1:-qtune=pwr4:-qarch=pwr4:-qnosave:-qnoescape ibmh parallel
% lopts -O3:-g:-qrealsize=8:-Q:-q64:-qmaxmem=-1:-qtune=pwr4:-qarch=pwr4:-qnosave:-qnoescape:-lesslsmp ibmh parallel
#
EC:[[ \$locat = execution]] & & cat RUN_CONTROL 
#
PARIN in:job:npe d3# ~/palm/current_version/JOBS/$fname/INPUT _p3d
#
RUN_CONTROL out:loc:tr d3# ~/palm/current_version/JOBS/$fname/MONITORING _rc
HEADER out:loc:tr d3# ~/palm/current_version/JOBS/$fname/MONITORING _header
PLOT1D_PAR out:loc:tr pr# ~/palm/current_version/JOBS/$fname/OUTPUT _pr_par
PLOT1D_DATA out:loc:tr pr# ~/palm/current_version/JOBS/$fname/OUTPUT _pr_in

The first five lines specify values of so-called environment variables. Such lines begin with a “%”- sign. After at least one blank the name of the variable (e.g. source_path) follows and then seperated by at least one blank the value of the variable. Again separated by blank the so-called validity domain can be indicated (later more). With the first three variables mrun gets to know in which directory the source code lies (source_path), the file name of the main program (mainprog) and that the make mechanism should be used for compiling (use_makefile = true). mrun needs these information, because for each model run the executable is created by compiling the source files. Normally, only the main program (palm.f90) will be compiled while all other object files are just linked. These object files have already been created from the source code files during the installation of the model (see chapter 5.0). mrun uses certain standard options for the compilation process. Beyond that you can declare additional options with the environment variable fopts. Within the value assignment of an environment variable in the configuration file no blanks must be used. If blanks are necessary they must be replaced by colons (“:”). mrun will interpret these colons as blanks (2 colons written one behind the other will be interpreted as a colon). Thus in the example above fopts has the value “-O3 -g -qrealsize=8 -Q -q64 -qmaxmem=-1 -qtune=pwr4 -qarch=pwr4 -qnosave -qnoescape”. Thus a PALM executable is generated using high level optimization (-O3). For all other options see the compiler manual on the IBM (man f90). Additional libraries which the compiler should use are described by the environment variable lopts (loader options). Here you have to indicate a special IBM library (ESSL, Engineering and Scientific Subroutine Library). On the IBM-Regatta, all compiler options have also to be given to the linker.

Compiler and loader options usually differ from computer to computer. In the configuration file therefore several value assignments for the variables fopts and lopts exist which become active for different computers. Which value assignment is used is described by the so-called validity domain which follows in the appropriate variable lines after the value of variables. In the example above the entry “ibmh parallel” stands for fopts and lopts. These lines only become active if a run on the parallel computer of the HLRN (ibmh) on several (parallel) processors is started. The activation takes place when you appropriately specify the mrun options -h and -K (see below). This way, the validity domain can be limited also for all other environment-variables. If no validity domain is indicated then the given values of variables are valid on all computers.

After the value assignment for the variables the so-called error commands follow which have to begin with “EC:” in the first column (comment lines begin with “#”). Directly after the colon Unix commands follow (korn shell syntax) which are processed by mrun if errors arise during the model run. The command described in the example (cat RUN_CONTROL) is executed thereby only on the condition that errors during the execution of the model (execution) arise. An mrun internal environment variable which indicates the respective abort place in case of errors is locat. In order to determine the actual value of this variable at the execution of mrun the “$” - prefix must be protected by a “\” since the configuration file has been already interpreted once when reading in through mrun and the value from locat would then supply the empty character string. If errors arise during the model run this command copies the data written by the model up to then to the local file RUN_CONTROL on the standard output where they can be checked after job end. RUN_CONTROL is an output file of the model which has to be copied according to the default configuration file (see below) after the end of the model run to a permanent file of the user but this action would not be performed in case of errors in the model run, so that the file content would be lost. With the help of the error command one can secure it nevertheless.

Before and/or after the error commands in the example file you can find the so-called input and/or output commands which are implemented before and/or after the model run.

After the output commands in the example file the so-called file connection statements follow via which tell mrun how to connect the local files in the temporary working directory of the model with the respective permanent files of the user. mrun copies the input and output files in accordance with the data in these connection statements. The file connection statements are explained in detail in the mrun description (chapter 6.3, in German) and are described here only as far as necessary. A file connection statement usually consists of entries in 5 columns whereby all columns are separated from each other by one or more blanks (the blanks define the individual columns). In the first column the local file name (e.g. PARIN) is given as it is addressed by the model. It must begin directly at the start of the line. In the second column the so-called file attributes are given. These determine whether the file is an input file (in) or an output file (out), whether output files are to be transferred to the local computer of the user (tr) or whether they are to be archived (fl). If a file has several attributes then they are separated by a colon in each case .

With the entries in the third column one specifies the conditions under which a file connection statement becomes active i.e. under which circumstances it is executed by mrun. Then mrun copies the appropriate in or output files only if at least one of the character strings registered in column 3 (again two or more character strings have to be separated from each other by a colon) is indicated within the mrun call by the option -r. Thus a call of the form

would lead to the fact that the input file with the local name PARIN is made available and the output files RUN_CONTROL and HEADER are copied to permanent files. The output files PLOT1D_PAR and PLOT1D_DATA are not copied so that their contents are not available to the user after the end of the job. If these files are to be copied of mrun then the call must be

Instead of the option -r you can separately address the file connection statements for input and/or output files with the options -i and -o. If one likes to make sure with these two options that in the example configuration file all file connection statements are actually executed then the call must be:

The names of the local files assigned permanent files are build from the entries in the 4th and 5th column of the file connection statements and the value of the mrun option -d in the following way:

The 4th column contains the path name whereby $fname is replaced by the value indicated for the option -d. The 5th column contains the so-called file name extension. The name of the permanent file which was copied by mrun to the local file PARIN thereby reads:

In the same way the names of the permanent files of the remaining file connection statements can be formed.

With this example configuration file exactly one input file is copied into the temporary working directory of the model. This file has the local name PARIN and contains the steering parameters for the model and has to be provided by the user for each model run.

The example configuration file also instructs mrun to copy four output files of the model to appropriate permanent files of the user at the end of the run. There are timestep information (local file name RUN_CONTROL), the so-called header file, in which the values of the most selected parameters for this run (HEADER) are located, as well as a file with data of horizontally averaged vertical profiles (PLOT1D_DATA) and an associated parameter file (PLOT1D_PAR), which can be used as input files for the plot program profil. A model run does not presuppose neither the file connection statements for output files nor their activation. But without declaring AND activating them usually the data produced by the model are lost after the end of the model run!

As already mentioned the configuration file offers a variety of further possibilities to steer the execution of the model run. Some of them are described in the next chapter. Same applies to possible other options of the mrun call. For these please refer to the mrun documentation (in German). An mrun call for the execution of a model run on several processors on the IBM Regatta "hanni" of the HLRN must be supplemented by the following options in each case:

Only the indication of -K parallel causes the parallel execution of the run on several processors (otherwise a scalar execution on one processor is accomplished). In addition to this the number of the processing elements which shall be used has to be pre-scribed with the option -X (e.g. -X 4). In each case the permitted CPU time in seconds and the required memory size in MB must be indicated by the options -t and -m, respectively. Alternatively, these can be set by the appropriate environment variables in the configuration file:

% memory  1630 ibmh parallel
% cputime 1000 ibmh parallel

The values indicated there can be overridden with the values of the options -t and/or -m, respectivly.


Last change:  $Id: chapter_3.2.html 97 2007-06-21 08:23:15Z weinreis $