source: palm/tags/release-3.2a/DOC/app/chapter_3.2.html

Last change on this file was 62, checked in by raasch, 17 years ago

Id string added to all html files

  • Property svn:keywords set to Id
File size: 22.0 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html><head>
3<meta http-equiv="CONTENT-TYPE" content="text/html; charset=windows-1252"><title>PALM
4chapter 3.2</title> <meta name="GENERATOR" content="StarOffice 7 (Win32)"> <meta name="AUTHOR" content="Marcus Oliver Letzel"> <meta name="CREATED" content="20040726;13164873"> <meta name="CHANGED" content="20050119;9245042"> <meta name="KEYWORDS" content="parallel LES model"> <style>
5<!--
6@page { size: 21cm 29.7cm }
7-->
8</style></head>
9
10<body style="direction: ltr;" lang="en-US"><h3 style="line-height: 100%;">3.2 Example of a minimum
11configuration
12file</h3>
13<p style="line-height: 100%;">In this chapter a sample
14configuration
15file is described. It contains only instructions which are really
16necessary for the execution of a simple model run (configuration
17files can be much more complex). The example presented here is stored
18in an appropriate <a href="http://www.muk.uni-hannover.de/%7Eraasch/PALM_group/INSTALL/.mrun.config">example
19file</a> (containing more than the configuration data presented
20here)
21and can be used, together with the <a href="http://www.muk.uni-hannover.de/%7Eraasch/PALM_group/INSTALL/example_p3d">parameter
22file</a> presented in <a href="chapter_4.4.html">chapter
234.4</a>, for the execution of a simple model run. In chapter 4.4
24the
25complete <b>mrun</b> options which are necessary for the
26appropriate
27parameter file are described. Furthermore not all details of the
28configuration file are described here. Therefore you should take a
29look at the <a href="http://www.muk.uni-hannover.de/%7Eraasch/Software/mrun_beschreibung.html">mrun</a>
30documentation (sorry: this is only available in German, so far. If you
31think that you
32would profit from an English version, please give a message to the PALM
33group). </p>
34<p style="line-height: 100%;">The following configuration
35data
36exclusively applies to model runs on the IBM Regatta hanni of the
37HLRN when using several processing elements (i.e. for the parallel
38version of the model). The proper installation of the model is
39presumed (see <a href="chapter_5.0.html">chapter
405.0</a>). Furthermore it is supposed that the user is located in
41the
42directory <tt><font style="font-size: 10pt;" size="2">$HOME/palm/current_version/SOURCE</font></tt>
43on its local computer. There are the FORTRAN source codes of the
44model (<tt><font style="font-size: 10pt;" size="2">*.f90</font></tt>)
45as
46well as the configuration file (name: <tt><font style="font-size: 10pt;" size="2">.mrun.config</font></tt>)
47and the make file (name: <tt><font style="font-size: 10pt;" size="2">Makefile</font></tt>).
48The configuration file has the following contents (among other things):
49<br>&nbsp;
50</p><pre style="line-height: 100%;"><font style="font-size: 10pt;" size="2">% source_path <i>$HOME/palm/current_version/SOURCE</i></font><br><font style="font-size: 10pt;" size="2">% mainprog <i>palm.f90</i></font><br><font style="font-size: 10pt;" size="2">% use_makefile <i>true</i></font><br><font style="font-size: 10pt;" size="2">% fopts <i>-O3:-g:-qrealsize=8:-Q:-q64:-qmaxmem=-1:-qtune=pwr4:-qarch=pwr4:-qnosave:-qnoescape ibmh parallel<span style="background: transparent none repeat scroll 0% 50%; -moz-background-clip: initial; -moz-background-origin: initial; -moz-background-inline-policy: initial;"></span></i></font><br><font style="font-size: 10pt;" size="2">% lopts <span style="font-style: italic;">-O3:-g:-qrealsize=8:-Q:-q64:-qmaxmem=-1:-qtune=pwr4:-qarch=pwr4:-qnosave:-qnoescape:-lesslsmp ibmh parallel</span></font><br><font style="font-size: 10pt;" size="2">#</font><br><font style="font-size: 10pt;" size="2">EC:[[ \$locat = execution]] &amp; &amp; <i>cat </i>RUN_CONTROL </font><br><font style="font-size: 10pt;" size="2">#</font><br><a href="chapter_3.4.html#PARIN"><font style="font-size: 10pt;" size="2">PARIN</font></a><font style="font-size: 10pt;" size="2"> in:job:npe d3# ~/palm/current_version/JOBS/$fname/INPUT _p3d</font><br><font style="font-size: 10pt;" size="2">#</font><br><a href="chapter_3.4.html#RUN_CONTROL"><font style="font-size: 10pt;" size="2">RUN_CONTROL</font></a><font style="font-size: 10pt;" size="2"> out:loc:tr d3# ~/palm/current_version/JOBS/$fname/MONITORING _rc</font><br><a href="chapter_3.4.html#HEADER"><font style="font-size: 10pt;" size="2">HEADER</font></a><font style="font-size: 10pt;" size="2"> out:loc:tr d3# ~/palm/current_version/JOBS/$fname/MONITORING _header</font><br><a href="chapter_3.4.html#PLOT1D_PAR"><font style="font-size: 10pt;" size="2">PLOT1D_PAR</font></a><font style="font-size: 10pt;" size="2"> out:loc:tr pr# ~/palm/current_version/JOBS/$fname/OUTPUT _pr_par</font><br><a href="chapter_3.4.html#PLOT1D_DATA"><font style="font-size: 10pt;" size="2">PLOT1D_DATA</font></a><font style="font-size: 10pt;" size="2"> out:loc:tr pr# ~/palm/current_version/JOBS/$fname/OUTPUT _pr_in</font></pre>
51<p style="line-height: 100%;"><font face="Thorndale, serif">The first
52five lines specify values of
53so-called environment variables. Such lines begin with a
54&ldquo;%&rdquo;-
55sign. After at least one blank the name of the variable</font> <font face="Thorndale, serif">(e.g.
56</font><tt><i><font face="Thorndale, serif">source_path</font></i></tt><font face="Thorndale, serif">)
57follows and then seperated by at least one blank the value of the
58variable. Again separated by blank t<font face="Thorndale, serif">he
59so-called validity domain</font> can be indicated (later more).
60With the first three variables <b>mrun</b> gets to know in
61which
62directory the source code lies (</font><tt><i><font face="Thorndale, serif">source_path</font></i></tt><font face="Thorndale, serif">),
63the file name of the main program (</font><tt><i><font face="Thorndale, serif">mainprog</font></i></tt><font face="Thorndale, serif">)
64and that the <font face="Thorndale, serif">make mechanism
65should be
66used </font>for compiling (</font><tt><font face="Thorndale, serif"><i>use_makefile
67=</i> <i>true</i></font></tt><font face="Thorndale, serif">). <b>mrun
68</b>needs these information, <font color="#000000">because
69for each
70model run the executable is created by compiling the source files.</font>
71Normally, only the main program (palm.f90) will be compiled while all
72other object files are just linked. These object files have already
73been created from the source code files during the installation of the
74model
75(see </font><a href="chapter_5.0.html"><font face="Thorndale, serif">chapter
765.0</font></a><font face="Thorndale, serif">).
77<b>mrun</b> uses
78certain standard options for the compilation process. Beyond that you
79can
80declare additional options with the environment variable </font><tt><i><font face="Thorndale, serif">fopts</font></i></tt><font face="Thorndale, serif">.
81Within the value assignment of an environment variable in the
82configuration file no blanks must be
83used. If blanks are necessary they must <font face="Thorndale, serif">be
84replaced </font>by colons (&ldquo;:&rdquo;). <b>mrun</b>
85will
86interpret these colons as blanks (2 colons written one behind the
87other will be interpreted as a colon). Thus in the example above </font><tt><font face="Thorndale, serif">fopts
88has the value </font></tt>&ldquo;<font style="font-size: 10pt; font-family: monospace;" size="2"><i>-O3
89-g
90-qrealsize=8 -Q -q64 -qmaxmem=-1 -qtune=pwr4 -qarch=pwr4 -qnosave
91-qnoescape</i></font><tt><i><font face="Thorndale, serif"><font color="#000000">&rdquo;</font></font></i></tt><font face="Thorndale, serif"><font color="#000000">.
92Thus a PALM executable is generated using high level optimization (</font></font><font color="#000000"><span style="font-style: italic; font-family: monospace;">-O3</span></font><font face="Thorndale, serif"><font color="#000000">).</font></font><font color="#000000"><font face="Thorndale, serif">
93For all other options
94see the compiler manual on the IBM (</font><font size="2"><font face="Cumberland, monospace">man</font></font></font><tt><font color="#000000">
95<font size="2"><font face="Cumberland, monospace">f90</font></font></font></tt><font face="Thorndale, serif"><font color="#000000">).
96Additional libraries
97which the compiler should use are described by
98the environment variable </font></font><tt><font size="2"><font face="Cumberland, monospace"><font color="#000000">lopts</font></font></font></tt><font color="#000000">
99<font face="Thorndale, serif">(loader options).</font></font><font color="#800000">
100</font><font face="Thorndale, serif"><font color="#000000">Here you
101have to indicate a special IBM library (ESSL, </font></font>Engineering
102and Scientific Subroutine Library)<font face="Thorndale, serif"><font color="#000000">.</font><font color="#800000">
103</font>On the
104IBM-Regatta, all compiler options have also to be given to the linker.</font><font color="#000000"><font face="Thorndale, serif"> </font></font>
105</p><p style="line-height: 100%;"><font color="#000000">Compiler and
106loader options usually differ from computer to computer. In the
107configuration file therefore several value assignments for the
108variables </font><tt><font style="font-size: 10pt;" size="2"><font color="#000000">fopts</font></font></tt><font color="#000000">
109and </font><tt><font style="font-size: 10pt;" size="2"><font color="#000000">lopts</font></font></tt><font color="#000000">
110exist which become active for different computers.</font><font color="#800000">
111<font color="#000000">Which value assignment is used is
112described by
113the so-called validity domain which follows in the appropriate
114variable lines after the value of variables.</font></font><font color="#000000">
115In the example above the entry &ldquo;</font><font color="#000000"><font style="font-size: 11pt; font-style: italic; font-family: monospace;" size="2">ibmh</font></font><tt><font color="#000000"><span style="font-style: italic; font-family: monospace;">
116</span></font><font color="#000000"><i><font style="font-size: 11pt;" size="2">parallel</font></i></font></tt><font color="#000000">&rdquo;
117stands for </font><tt><font style="font-size: 10pt;" size="2"><font color="#000000">fopts</font></font></tt><font color="#000000">
118and </font><tt><font style="font-size: 10pt;" size="2"><font color="#000000">lopts</font></font></tt><font color="#000000">.
119These lines only become active if a run on the parallel computer of
120the HLRN (</font><tt><i><font style="font-size: 10pt;" size="2">ibmh</font></i></tt><font color="#000000">)
121on several <font color="#000000">(</font><tt><i><font style="font-size: 10pt;" size="2"><font color="#000000">parallel</font></font></i></tt><font color="#000000">)
122</font>processors is started. The activation takes place when you
123appropriately specify the <span style="font-weight: bold;">mrun</span>
124options </font><tt><font color="#000000">-h</font></tt><font color="#000000">
125and </font><tt><font color="#000000">-K</font></tt><font color="#000000">
126(see below). This way, the validity domain can be limited also for all
127other environment-variables. If no validity domain
128is indicated then the given values of variables are valid on all
129computers. </font>
130</p><p style="line-height: 100%;">After the value
131assignment for the
132variables the so-called error commands follow which have to begin with
133&ldquo;<tt><font style="font-size: 11pt;" size="2">EC:</font></tt>&rdquo;
134in the first column (comment lines begin with &ldquo;<tt>#</tt>&rdquo;).
135Directly
136after the colon Unix commands follow (korn shell syntax) which are
137processed by <b>mrun</b> if errors arise during
138the model run. The command described in the example (<tt><font style="font-size: 10pt;" size="2">cat
139RUN_CONTROL</font></tt>) is executed thereby only on the
140condition that errors during the execution of the model (<tt><font style="font-size: 10pt;" size="2">execution</font></tt>)
141arise. An <b>mrun </b>internal environment variable which
142indicates
143the
144respective abort place in case of errors is <tt><a href="http://www.muk.uni-hannover.de/institut/software/mrun_beschreibung.html#locat">locat</a></tt>.
145In order to determine the actual value of this variable at the
146execution of <b>mrun</b> the &ldquo;<tt>$</tt>&rdquo;
147- prefix
148must be protected by a &ldquo;\&rdquo; since the configuration
149file has been
150already interpreted once when reading in through <b>mrun</b>
151and the
152value from
153<tt>locat</tt> would then supply the empty character
154string. If
155errors arise during the model run this command
156copies the data written by the model up to then to the local file
157<a href="chapter_3.4.html#RUN_CONTROL">RUN_CONTROL</a>
158on the standard output where they can be checked after
159job end.<font color="#000000"> RUN_CONTROL is an output
160file of the
161model which has to be copied according to the default configuration
162file
163(see below) after the end of the model run to a permanent file of the
164user but this action would not be performed in case of errors
165in the model run, so that the file content would be lost.</font>
166With
167the help of the error command one can secure it nevertheless. </p>
168<p style="line-height: 100%;">Before and/or after
169the error commands in the example file you can find the so-called input
170and/or output commands which are implemented before and/or after the
171model run. </p>
172<p style="line-height: 100%;">After the output commands<font color="#000000">
173<font color="#000000">in the example file t</font>he
174so-called file
175connection statements</font> <font color="#000000">follow
176</font>via
177which tell <span style="font-weight: bold;">mrun</span>
178how to connect
179the local files in the temporary working
180directory of the model with the respective permanent files of the user.
181<b>mrun</b> copies the input and output files in accordance
182with the
183data in these connection statements. The file connection statements are
184explained in detail in the <b>mrun</b>
185description (<a href="http://www.muk.uni-hannover.de/institut/software/mrun_beschreibung.html#chapter6.3">chapter
1866.3</a>, in German) and are described here only as far as being
187necessary. A
188file connection statement usually consists of entries in 5 columns
189whereby all columns are separated from each other by one or more blanks
190(the blanks define the individual columns). In the
191first column the local file name (e.g. <tt><font size="2">PARIN</font></tt>)
192is given as it is addressed by the model. It must begin directly at
193the start of the line. In the second column the so-called file
194attributes
195are given. These determine whether the file is an input file (<tt><font style="font-size: 10pt;" size="2">in</font></tt>)
196or an output file (<tt><font size="2">out</font></tt>),
197whether output
198files are to be transferred to the local computer of the user (<tt><font style="font-size: 10pt;" size="2">tr</font></tt>)
199or whether they are to be archived (<font size="2"><font face="Cumberland, monospace">fl</font></font>).
200If a file has several attributes then they are separated by a <font color="#000000">colon
201in each case .</font> </p>
202<p style="line-height: 100%;">With the entries in the
203third column one
204specifies the conditions under which a file connection statement
205becomes active i.e. under
206which circumstances it is executed by <b>mrun</b>. Then <b>mrun</b>
207copies the appropriate in or output files only if at least one of the
208character strings registered in column 3 (again two or more character
209strings have to be separated from each other by a colon) is
210indicated within the mrun <b>call</b> by the option <a href="http://www.muk.uni-hannover.de/institut/software/mrun_beschreibung.html#Opt-r">-r</a>.
211Thus a call of the form </p>
212<ul> <pre style="margin-bottom: 0.5cm; line-height: 100%;"><font style="font-size: 10pt;" size="2">mrun - h ibmh -d abcde -r d3</font></pre></ul>
213<p style="line-height: 100%;">would lead to the fact that
214the input
215file with the local name PARIN is made available and the output files
216RUN_CONTROL and HEADER are copied to permanent files. The output
217files PLOT1D_PAR and PLOT1D_DATA are not copied so that their
218contents are not available to the user after the end of the job. If
219these files are to be copied of <b>mrun</b> then the call
220must be</p>
221<ul> <pre style="margin-bottom: 0.5cm; line-height: 100%;"><font style="font-size: 10pt;" size="2">mrun -h ibmh -d abcde -r "d3 pr"</font></pre></ul>
222<p style="line-height: 100%;">Instead of the option -r you
223can
224separately address the file connection statements for input and/or
225output files with the options -i and -o. If one likes to make sure with
226these two options that in the example configuration
227file all file connection statements are actually executed then
228the call must be: </p>
229<ul> <pre style="margin-bottom: 0.5cm; line-height: 100%;"><font style="font-size: 10pt;" size="2">mrun -h ibmh -d abcde -i d3 -o "d3 pr"</font></pre></ul>
230<p style="line-height: 100%;"><font color="#000000">The
231names of the
232local files assigned permanent files are build from the entries in
233the 4th and 5th column of the file connection statements and the
234value of the <span style="font-weight: bold;">mrun</span>
235option </font><tt><font style="font-size: 10pt;" size="2"><font color="#000000">-d</font></font></tt><font color="#000000">
236in the following way:</font><font color="#800000"> </font>
237</p><ul> <p style="line-height: 100%;">File
238name (inclusive path) = &ldquo;value of
239the 4th column&rdquo; + &ldquo;value of the option <tt><font size="2">-d</font></tt>&rdquo;
240+ &ldquo;value of the 5th column&rdquo;.</p>
241</ul><p style="line-height: 100%;">The 4th column
242contains the path name
243whereby <tt><a href="http://www.muk.uni-hannover.de/institut/software/mrun_beschreibung.html#fname">$fname</a></tt>
244is replaced by the value indicated for the option <tt><font size="2">-d</font></tt>.
245The 5th column contains the so-called file name extension. The name
246of the permanent file which was copied by <b>mrun</b> to
247the local
248file <tt>PARIN</tt> thereby reads: </p>
249<ul> <pre style="margin-bottom: 0.5cm; line-height: 100%;"><font style="font-size: 10pt;" size="2">~/palm/current_version/JOBS/abcde/INPUT/abcde_p3d.</font></pre></ul>
250<p style="line-height: 100%;">In the same way the names of
251the
252permanent files of the remaining <font color="#000000">file
253connection statements </font>can be formed. </p>
254<p style="line-height: 100%;">With this example
255configuration file
256exactly one input file is copied into the temporary working directory
257of the model. This file has the local name <a href="chapter_3.4.html#PARIN">PARIN</a>
258and contains the steering parameters for the model and has to be
259provided by the user for each model run. </p>
260<p style="line-height: 100%;">The example configuration
261file also
262instructs <b>mrun</b> to copy four output files of the
263model to
264appropriate permanent files of the user at the end of the run.
265There are timestep information (local file name <tt><a href="chapter_3.4.html#RUN_CONTROL">RUN_CONTROL</a></tt>),
266the so-called header file, in which the values of the most selected
267parameters for this run (<tt><a href="chapter_3.4.html#HEADER">HEADER</a></tt>)
268are located, as well as a file with data of horizontally averaged
269vertical profiles
270(<tt><a href="chapter_3.4.html#PLOT1D_DATA">PLOT1D_DATA</a></tt>)
271and an associated parameter file (<tt><a href="chapter_3.4.html#PLOT1D_PAR">PLOT1D_PAR</a></tt>),
272which can be used as input files for the plot program <a href="http://www.muk.uni-hannover.de/institut/software/profil_beschreibung.html">profil</a>.
273A model run does not presuppose neither the file connection statements
274for
275output files nor their activation. But without declaring AND activating
276them usually the data produced by the model
277are lost after the end of the model run! </p>
278<p style="line-height: 100%;">As already mentioned the
279configuration
280file offers a variety of further possibilities to steer the
281execution of the model run. Some of them are described in the next
282chapter. Same applies to possible other options of the <b>mrun</b>
283call. For these please refer to the <a href="http://www.muk.uni-hannover.de/%7Eraasch/Software/mrun_beschreibung.html">mrun</a>
284documentation (in German). An <b>mrun </b>call for the
285execution of a
286model run
287on several processors on the IBM Regatta "hanni" of the HLRN must be
288supplemented by the following options in each case: </p>
289<ul> <pre style="margin-bottom: 0.5cm; line-height: 100%;"><font style="font-size: 10pt;" size="2">mrun - K parallel -X &hellip; -t &hellip; -m &hellip;</font></pre></ul>
290<p style="line-height: 100%;">Only the indication of <tt><font style="font-size: 11pt;" size="2">-K
291parallel</font></tt> causes the parallel execution of the
292run on
293several processors (otherwise a scalar execution on one processor is
294accomplished). In addition to this the number of the
295processing elements which shall be used has to be pre-scribed with the
296option <tt><font style="font-size: 10pt;" size="2">-X</font>
297</tt><font size="2">(</font><font style="font-size: 10pt;" size="2">e.g.
298</font><tt><font style="font-size: 10pt;" size="2">-X
2994</font></tt><font size="2">).</font>
300In each case the permitted CPU time in seconds and the required memory
301size in MB must be indicated by the options <tt><font style="font-size: 11pt;" size="2">-t</font></tt>
302and <tt><font style="font-size: 11pt;" size="2">-m</font></tt>,
303respectively<font face="Thorndale, serif">.</font>
304Alternatively, these can be set by the appropriate environment
305variables in the configuration file: </p>
306<blockquote style="line-height: 100%;"><tt><font style="font-size: 10pt;" size="2"><font face="Cumberland, monospace">%
307memory&nbsp; <i>1630</i> ibmh parallel</font></font></tt><font style="font-size: 10pt;" size="2"><font face="Cumberland, monospace"><br> </font></font><tt><font style="font-size: 10pt;" size="2"><font face="Cumberland, monospace">%
308cputime <i>1000</i> ibmh parallel</font></font></tt></blockquote>
309<p style="line-height: 100%;">The values indicated there
310can be
311overridden with the values of the options <tt><font style="font-size: 10pt;" size="2">-t</font></tt>
312and/or <tt><font style="font-size: 10pt;" size="2">-m</font></tt>,
313respectivly. </p>
314<hr><p style="line-height: 100%;"><br>
315<font color="#000080"><font color="#000080"><a href="chapter_3.1.html"><font color="#000080"><img src="left.gif" name="Grafik1" align="bottom" border="2" height="32" width="32"></font></a><a href="index.html"><font color="#000080"><img src="up.gif" name="Grafik2" align="bottom" border="2" height="32" width="32"></font></a><a href="chapter_3.3.html"><font color="#000080"><img src="right.gif" name="Grafik3" align="bottom" border="2" height="32" width="32"></font></a></font></font></p><p style="line-height: 100%;"><i>Last change:&nbsp;</i>
316$Id: chapter_3.2.html 62 2007-03-13 02:52:40Z banzhafs $</p>
317</body></html>
Note: See TracBrowser for help on using the repository browser.