source: palm/trunk/DOC/app/chapter_3.2.html @ 5

Last change on this file since 5 was 5, checked in by raasch, 14 years ago

html-documentation added

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