source: palm/trunk/DOC/app/chapter_5.0.html @ 515

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

simple installation method documented and updated; bugfix for PGI compiler in buoyancy

  • Property svn:keywords set to Id
File size: 44.7 KB
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
6<meta http-equiv="CONTENT-TYPE" content="text/html; charset=windows-1252"><title>PALM chapter 5.0</title> <meta name="GENERATOR" content="StarOffice 7 (Win32)"> <meta name="AUTHOR" content="Siegfried Raasch"> <meta name="CREATED" content="20041103;12380720"> <meta name="CHANGED" content="20041123;15532356"> <meta name="KEYWORDS" content="parallel LES model"> <style>
8@page { size: 21cm 29.7cm }
10</style></head><body style="direction: ltr;" lang="en-US"><h2 style="line-height: 100%;"><font size="4">5.0
11Code installation<br>
13<font color="#000000">This chapter
14describes the installation of PALM on a Linux workstation (local host). There are two methods to install and run PALM. With the <span style="font-style: italic;">simple method</span>, you can run PALM interactively on the local computer. This method is using the scripts <span style="font-weight: bold;">palm_simple_install</span> and <span style="font-weight: bold;">palm_simple_run</span>.&nbsp;
15The simple method cannot create batch jobs itself, and cannot be used
16to create restart runs. Also file handling and most other features of
17the <span style="font-style: italic;">advanced method</span> are not available. This method is only recommended for those who like to test PALM quickly.<br>
19The <span style="font-style: italic;">advanced method</span> is for running PALM in batch mode on a suitable remote computer. The installation procedure is using the script <span style="font-weight: bold;">mbuild</span>. All jobs are started on the local host using the script <b>mrun</b>. The PALM output is automatically sent back from the remote host to the
20local host. Alternatively, <span style="font-weight: bold;">mrun</span>
21can also be used to start PALM in interactive mode on the local host, or
22as a batch job on the local host (if a queueing system like NQS, PBS, or LoadLeveler is
25Only the <span style="font-style: italic;">advanced method</span> gives full access to all PALM features.<br>
27</font><p style="line-height: 100%;"></p><p style="line-height: 100%;"><font color="#000000"><span style="font-weight: bold; text-decoration: underline;">Requirements</span></font></p><p style="line-height: 100%;"><font color="#000000">The
28installation and operation of PALM requires at mimimum (for the <span style="font-style: italic;">advanced method</span> on both, the
29local and the remote host, unless stated otherwise):</font></p><ol><li><font color="#000000">A Korn-shell (AT&amp;T ksh or public
30domain ksh); must be
31available under<span style="font-family: Courier New,Courier,monospace;"> </span></font><font style="font-family: Courier New,Courier,monospace;" color="#000000">/bin/ksh</font><font color="#000000">.<span style="font-weight: bold;"></span><span style="font-weight: bold;"></span><span style="font-family: Courier New,Courier,monospace;"></span></font><font color="#000000"><span style="font-weight: bold;"></span><span style="font-weight: bold;"></span></font></li><li><font color="#000000">A NetCDF-library with version number not earlier than 3.6.2 (for
32NetCDF, see under <a href=""></a>).</font></li><li><font color="#000000">A FORTRAN90/95 compiler.</font></li><li><font color="#000000">The Message Passing Interface (MPI), at
33least on the remote host, if the parallel version of PALM shall be used.</font></li><li><font color="#000000">On the local host, the revision control
34system <span style="font-weight: bold;">subversion</span>
35(see <a href=""></a>).
36This is already included in many Linux distributions (e.g. SuSe). <span style="font-weight: bold;">subversion requires port 3690 to
37be open for tcp/udp.</span> <span style="font-weight: bold;">If
38there are firewall restrictions concerning this port, the PALM code
39cannot be accessed.</span> The
40user needs a permit to access the PALM repository. For getting a permit
41please contact the PALM group (<a href=""></a>)
42and define a username under which you like to access the repository.
43You will then receive a password which allows access under this
45    <br>
46The <span style="font-style: italic;">advanced method</span> additionally requires:<br>
47</font></li><li><font color="#000000">A
48job queueing system on the remote host. Currently, <span style="font-weight: bold;">mrun</span> can handle
49LoadLeveler (IBM-AIX) and NQS/PBS (Linux-Clusters, NEC-SX).</font></li><li><font color="#000000">ssh/scp-connections to and from the remote
50host must not be blocked by a firewall.<br></font></li></ol><font color="#000000"><span style="font-weight: bold;"></span></font><font color="#000000"> Currently, <span style="font-weight: bold;">mrun</span> is configured
51to be used on a limited number of selected machines. These are SGI-ICE
52systems at computing center HLRN in Hannover (<span style="font-style: italic;">lcsgih</span>), Berlin (<span style="font-style: italic;">lcsgib</span>),
53IBM-Regatta systems<span style="font-style: italic;"></span>
54at Yonsei University (<span style="font-style: italic;">ibmy</span>), <span style="font-style: italic;"></span> and at DKRZ, Hamburg (<span style="font-style: italic;">ibmh</span>), an NEC-SX8 system at RIAM,
55Kyushu University, Fukuoka (<span style="font-style: italic;">necriam</span>),
56as well as on the Linux cluster of IMUK (<span style="font-style: italic;">lcmuk</span>), Tokyo
57Institute of Technology (<span style="font-style: italic;">lctit</span>),
58Kyoto computing center (<span style="font-style: italic;">lckyoto</span>), and Cray-XT4/5 systems at the Bergen Center for Computational Science (<span style="font-style: italic;">lcxt4</span>) and at the Finish Meteorological Institute (<span style="font-style: italic;">lcxt5m</span>).
59The strings given in brackets are the systems names (host identifiers)
60under which <span style="font-weight: bold;">mrun</span>
61identifies the
62different hosts.<br><br>You can also use <span style="font-weight: bold;">mrun</span>/PALM on other
63Linux-Cluster, IBM-AIX, or NEC-SX machines. See <a href="#configuration_for_other_machines">below</a> on
64how to configure <span style="font-weight: bold;">mrun</span>for
65other machines. However, these configurations currently (version
663.7a) allow to run PALM in interactive mode only. Batch mode requires
67manual adjustments for the respective queing system and MPI
68installation in scripts <span style="font-weight: bold;">mrun</span>, <span style="font-weight: bold;">mbuild</span>, and <span style="font-weight: bold;">subjob</span>.<br><span style="font-weight: bold;"></span><span style="font-weight: bold;"></span><span style="font-weight: bold;"></span><span style="font-weight: bold;"></span></font><p style="line-height: 100%;"><font color="#000000">The
69examples given in this chapter refer to an
70installation of PALM on an IMUK Linux workstation and (for the <span style="font-style: italic;">advanced method</span>) the SGI-ICE
71system of HLRN, used as&nbsp;remote host. They are just referred to as local and
72remote host from now on. </font></p><p style="line-height: 100%;">
73</p><p style="line-height: 100%;">The installation
74process for the <span style="font-style: italic;">advanced method</span> requires a valid
75account on the local and on the remote host as well.</p>
76<p style="line-height: 100%;">The <span style="font-style: italic;">advanced installation method</span> is described below. For the <span style="font-style: italic;">simple  method</span> see the <a href="#simple_installation_method">end of this chapter</a>.<br>
77&nbsp; </p>
80 All hosts (local as well as remote) are
81accessed via the secure shell (ssh). The user must establish
82passwordless login using the private/public-key mechanism (see e.g. the
83<a href="">HLRN
84documentation</a>). <b>To ensure proper function of mrun,
85passwordless login must be
86established in both directions, from the local to the remote host as
87well as from the remote to the local host!</b> Test this by
89out e.g. on the local host: <p style="line-height: 100%;"><span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
90</span><span style="font-family: Courier New,Courier,monospace;">ssh&nbsp;
91&lt;username on remote host&gt;@&lt;remote
92IP-address&gt;</span><br> </p> <p style="line-height: 100%;">and on the remote host:<br>
93</p> <p style="line-height: 100%;"><span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
94</span><span style="font-family: Courier New,Courier,monospace;">ssh&nbsp;
95&lt;username on local host&gt;@&lt;local IP-adddress&gt;</span><br>
96</p> In both cases you should&nbsp;not be
97prompted for a password. <b>Before continuing the further
99process, this must be absolutely guaranteed!</b> It must also
101guaranteed for <b>all</b> other remote hosts, on which
102PALM shall run.<br><br>Please
103note that on many remote hosts, passwordless login must also work <b>within the remote host</b>, i.e. for ssh connections from the
104remote host to itself. Test this by executing on the remote host:<br>
105  <br>
106  <span style="font-family: Courier New,Courier,monospace;">&nbsp;&nbsp; ssh
107&lt;username on remote host&gt;@&lt;remote IP-address&gt;</span>&nbsp;&nbsp;&nbsp;&nbsp; .<br>
108  <br>
109You should not be prompted
110for a password.<br><br>
112<p style="line-height: 100%;"><span style="font-weight: bold; text-decoration: underline;">Package
113Installation</span></p><p style="line-height: 100%;">The <b>first installation step</b> requires creating a
114set of directories on the local and, for the <span style="font-style: italic;">advanced method</span>, on the
115remote host<span style="font-style: italic;"></span>. These are:</p><div style="margin-left: 40px; font-family: Courier New,Courier,monospace;">~/job_queue<br></div><div style="margin-left: 40px; font-family: Courier New,Courier,monospace;">~/palm<br></div><div style="margin-left: 40px; font-family: Courier New,Courier,monospace;">~/palm/current_version<br></div><div style="margin-left: 40px;"><span style="font-family: Courier New,Courier,monospace;">~/palm/current_version/JOBS</span><br></div><p style="line-height: 100%;">The names of these directories can be
116freely selected (except <big><tt><font size="2"><big>~/job_queue</big></font></tt></big>),
117however new users should choose them as suggested, since many
118examples in this documentation as well as all example files are based on these settings. The directory <big><span style="font-family: monospace;">~/palm/current_version</span></big>
119on the local host will be called the working directory from now on. </p>
120<p style="line-height: 100%;"><font color="#000000">In
121the <b>second
123a working copy of the recent PALM version,
124including the source code, scripts, documentation, etc.&nbsp; must
126copied to the working directory (</font><font color="#000000">local
127host!) by executing the following
128commands. Replace &lt;your username&gt; by the name that you have chosen to
129access the repository, and &lt;#&gt; by any of the available
131releases, e.g. "<span style="font-style: italic;">3.7a</span>"
132(new releases will be announced to members of the PALM mailing list).</font></p><div style="margin-left: 40px;"><span style="font-family: Courier New,Courier,monospace;">cd
133~/palm/current_version</span><br style="font-family: Courier New,Courier,monospace;"><span style="font-family: Courier New,Courier,monospace;">svn
134checkout --username &lt;your username&gt;
135svn://;#&gt; trunk</span><br></div><p style="line-height: 100%;"><font color="#000000">You
136will then be prompted for your password. After completion, there should be a subdirectory</font><font style="font-family: Courier New,Courier,monospace;" color="#000000"> trunk </font><font color="#000000">in your working directory. It contains a number of further
137subdirectories, which contain e.g. the PALM source code (</font><font style="font-family: Courier New,Courier,monospace;" color="#000000">SOURCE</font><font color="#000000">)
138and the scripts for running PALM (</font><font style="font-family: Courier New,Courier,monospace;" color="#000000">SCRIPTS</font><font color="#000000">).</font></p><p style="line-height: 100%;">Alternatively,&nbsp;executing</p><pre style="line-height: 100%; margin-left: 40px; font-family: Courier New,Courier,monospace;">svn checkout --username &lt;your username&gt; svn://;#&gt; abcde</pre><p style="line-height: 100%;">will place your working copy in a
139directory named<span style="font-family: Courier New,Courier,monospace;"> abcde </span>(instead
140of a directory named<span style="font-family: Courier New,Courier,monospace;"> trunk</span>).
141But keep in mind that you will have to adjust several paths given
142below, if you do not use the default directory<span style="font-family: Courier New,Courier,monospace;"> trunk</span>.</p><p style="line-height: 100%;">Please never touch any file in
143your working copy of PALM, unless you&nbsp;know what you
144are doing.</p><p style="line-height: 100%; font-weight: bold;"><span style="font-weight: normal;">You can also get a copy of the
145most recent developer code by executing</span></p><pre style="line-height: 100%; margin-left: 40px; font-family: Courier New,Courier,monospace;">svn checkout --username &lt;your username&gt; svn:// trunk</pre>This version may contain new features (they might not be documented well), but it may also contain bugs.<span style="font-weight: bold;"><br>
147<p style="line-height: 100%;"></p><p style="line-height: 100%;"><font color="#000000"><span style="font-weight: bold; text-decoration: underline;">Package
148Configuration</span></font></p><p style="line-height: 100%;"><font color="#000000">To
149use the PALM scripts, the <span style="font-family: Courier New,Courier,monospace;">PATH</span>-variable
150has to be extended and the
151environment variable<span style="font-family: Courier New,Courier,monospace;">
152PALM_BIN </span>has to be set (on local and remote host)
153in the respective profile of the users default shell (e.g. in<span style="font-family: Courier New,Courier,monospace;"> .profile</span>,
154if<span style="font-family: Courier New,Courier,monospace;">
155ksh </span>is used):</font></p><p style="line-height: 100%; margin-left: 40px;"><font style="font-family: Courier New,Courier,monospace;" color="#000000">export
156PATH=$HOME/palm/current_version/trunk/SCRIPTS:$PATH</font><font color="#000000"><br><span style="font-family: Courier New,Courier,monospace;">export
157PALM_BIN=</span></font><font style="font-family: Courier New,Courier,monospace;" color="#000000">$HOME/palm/current_version/trunk/SCRIPTS</font></p><p style="line-height: 100%;"><font color="#000000">You
158may have to login again in order to activate these settings.</font></p><font color="#000000">On the local and on the remote host, some
159small helper/utility programs have to be installed, which
160are&nbsp;later used by <span style="font-weight: bold;">mrun</span>&nbsp;e.g.
161for PALM data postprocessing. The installation is done by <span style="font-weight: bold;">mbuild</span>. This script
162requires a configuration file<span style="font-family: Courier New,Courier,monospace;">
163.mrun.config</span>, which will be also used by <span style="font-weight: bold;">mrun</span> in the
164following. A copy has to be put into the working directory under the
165name<span style="font-family: Courier New,Courier,monospace;">
166.mrun.config </span>by</font><p style="line-height: 100%; margin-left: 40px;"><font color="#000000"><span style="font-family: Courier New,Courier,monospace;">cp
167trunk/SCRIPTS/.mrun.config.default .mrun.config</span></font></p><font color="#000000">Beside many other things, this file contains
168typical installation parameters
169like compiler name, compiler options, etc.
170for a set of different (remote) hosts. Please edit this file, uncomment
171lines like</font><div style="margin-left: 40px; font-family: Courier New,Courier,monospace;">#%remote_username
172&nbsp;&lt;replace by your ... username&gt; &nbsp;
173&lt;host identifier&gt;</div><p style="line-height: 100%;"><font color="#000000">by
174removing the first hash (<span style="font-family: Courier New,Courier,monospace;">#</span>)
175character and replace the string "<span style="font-family: Courier New,Courier,monospace;">&lt;replace
176by ...&gt;</span>" by your username on the respective host
177given in the <span style="font-family: Courier New,Courier,monospace;">&lt;host
179You only have to uncomment lines for those hosts on which you intend to
180use PALM.</font></p><p style="line-height: 100%;"><font color="#000000"><span style="font-weight: bold;">Warning:
181When editing the configuration file, please NEVER use the TAB key.
182Otherwise, very confusing errors may occur when mrun is executing.</span></font></p><p style="line-height: 100%;"><font color="#000000">Beside the default configuration file</font><font style="font-family: Courier New,Courier,monospace;" color="#000000"> .mrun.config.default</font><font color="#000000">, the directory<span style="font-family: Courier New,Courier,monospace;">
183trunk/SCRIPTS </span>contains additional configuration files
184which are already adjusted for special hosts</font><font color="#000000">, e.g.</font><font color="#000000"><span style="font-family: Courier New,Courier,monospace;">
185.mrun.config.imuk </span>can be used at Hannover University</font><font color="#000000">, etc.. </font><font color="#000000">These files have to be edited in the same way as described
186above.</font></p><p style="line-height: 100%;"><font color="#000000">After modifying the configuration file, the
187respective executables are generated by executing</font></p><p style="line-height: 100%; margin-left: 40px; font-family: Courier New,Courier,monospace;"><font color="#000000">mbuild -u -h lcmuk<br>mbuild -u -h
188lcsgih</font></p><p style="line-height: 100%;"><font color="#000000">The
189second call also copies the PALM scripts (like <span style="font-weight: bold;">mrun</span> and <span style="font-weight: bold;">mbuild</span>) to the
193</font></p><p style="line-height: 100%;"></p><p style="line-height: 100%;"><font color="#000000"><span style="font-weight: bold; text-decoration: underline;">Pre-Compilation
194of PALM Code</span></font></p><font color="#000000">
195</font><br><font color="#000000">To avoid the
196re-compilation of the complete source code for each model run, PALM
197willl be pre-compiled once on the remote host by again using the script
198<span style="font-weight: bold;">mbuild</span>. Due
199to the use of
200FORTRAN modules in the source code, the subroutines must be compiled
201in a certain order. Therefore the so-called <i>make</i>
203is used (see the respective man-page of the Unix operating system),
204requiring a<span style="font-family: Courier New,Courier,monospace;">
205</span></font><font style="font-family: Courier New,Courier,monospace;" color="#000000">Makefile</font><font color="#000000">,
206in which the dependencies are described. This file is found in
207subdirectory <span style="font-family: Courier New,Courier,monospace;">trunk/SOURCE</span></font><font color="#000000">, where
208also the PALM code is stored.</font><font color="#000000"> The compiled
209sources (object
210files) are
211stored&nbsp;on the remote computer in the default directory
212</font><font style="font-family: Courier New,Courier,monospace;" color="#000000">~/palm/current_version/MAKE_DEPOSITORY</font>_<span style="font-family: Courier New,Courier,monospace;">&lt;block_descriptor&gt;</span>, where<font color="#000000"> <span style="font-family: Courier New,Courier,monospace;">&lt;block_descriptor&gt;</span> is composed of the third (and fourth, if existing) column of the respective block in the configuration file (e.g. <span style="font-family: Courier New,Courier,monospace;">lcsgih_parallel</span> for HLRN).<span style="font-weight: bold;"></span></font><p style="line-height: 100%;"><font color="#000000">The
213pre-compilation for the remote host (here the SGI-ICE system of HLRN)
215done by</font><span style="font-family: monospace;"></span></p><div style="margin-left: 40px;"><span style="font-family: Courier New,Courier,monospace;">mbuild
216-h lcsgih &nbsp;</span></div><p style="line-height: 100%;"><span style="font-family: Courier New,Courier,monospace;">mbuild
217</span>will prompt some queries<font color="#000000">,
218which must all be
219answered "y" by the user. The compiling process </font><font color="#000000">will take some time.<span style="font-family: Courier New,Courier,monospace;"> </span></font><font style="font-family: Courier New,Courier,monospace;" color="#000000">mbuild</font><font color="#000000"><span style="font-family: Courier New,Courier,monospace;"> </span>transfers
220the respective compiler calls to the remote
221host where they are carried out interactively. You can follow the
222progress at the terminal window, where also error messages
223are displayed (hopefully not for this standard installation). By just
224entering </font></p><p style="line-height: 100%;">
225</p><blockquote style="line-height: 100%; font-family: Courier New,Courier,monospace;"><font color="#000000">mbuild</font></blockquote>
226<p style="line-height: 100%;"><font color="#000000">PALM
228be (consecutively) pre-compiled for all remote hosts listed in
229the configuration file. If you want to compile for the local host only,
230please enter</font></p><p style="line-height: 100%; margin-left: 40px;"><font color="#000000"><span style="font-family: Courier New,Courier,monospace;">mbuild
231-h lcmuk</span> </font>
232</p><p style="line-height: 100%;"></p><p style="line-height: 100%; font-weight: bold; text-decoration: underline;"><font color="#000000">Installation Verification</font></p><font color="#000000">As a last step,
233after the compilation has been finished, the PALM installation has to
234be verified. For this
235purpose a simple test run is carried out. This once again requires the <b>mrun
236</b>configuration file (described in </font><a href="chapter_3.2.html"><font color="#000080">chapter
2373.2</font></a><font color="#000000">), as well
238as the </font><a href=""><font color="#000080">parameter
239file</font></a><font color="#000000">
240(described in </font><a href="chapter_4.4.1.html"><font color="#000080">chapter
2414.4.1</font></a>)<font color="#000000">. The
242parameter file must be
243copied from the PALM working copy by<br>
244</font><div style="margin-left: 40px;"><span style="font-family: monospace;"></span><font style="font-family: Courier New,Courier,monospace;" color="#000000">mkdir -p JOBS/example_cbl/INPUT<br>cp
245trunk/INSTALL/example_cbl_p3d&nbsp;JOBS/example_cbl/INPUT/example_cbl_p3d</font><font color="#000000"><span style="font-family: Courier New,Courier,monospace;"></span></font></div>
246<p style="line-height: 100%;"><font color="#000000">The
247test run can
248now be started by executing the command </font>
249</p><pre style="margin-left: 1cm; margin-right: 1cm; margin-bottom: 0.5cm; line-height: 100%; font-family: Courier New,Courier,monospace;"><font color="#000000">mrun -d example_cbl -h lcsgih -K parallel -X 8 -T 8 -t 500 -q testq -r “d3# pr#”</font></pre><font color="#000000">This specific run
250will be carried out on 8 PEs and is allowed to use up to 500 seconds
251CPU time. After pressing &lt;return&gt;, the most important
252settings of
253the job are displayed at the terminal window
254and the user is prompted for o.k. (“</font><font style="font-family: Courier New,Courier,monospace;" color="#000000">y</font><font color="#000000">”).
255Next, a message of the queuing system like “<i>Request</i>
257<i>Submitted to queue… by…” </i>should
258be displayed. Now the job is
259queued and either started immediately or at a later time, depending on
261current workload of the remote host. Provided that it is executed
262immediately and that all things work as designed, the job protocol of
263this run will appear under the file name<span style="font-family: Courier New,Courier,monospace;"> </span></font><font style="font-family: Courier New,Courier,monospace;" color="#000000">~/job_queue/lcsgih_example</font><font color="#000000"><span style="font-family: Courier New,Courier,monospace;"> </span>no
264more than a few minutes later. The content of this
265file should be carefully examined for any error messages.</font><p style="line-height: 100%;">
266</p><p style="line-height: 100%;">Beside the job
267protocol and according to
268the configuration file and arguments given for <b>mrun</b>
269options<span style="font-family: Courier New,Courier,monospace;">
270-d </span>and<span style="font-family: Courier New,Courier,monospace;"> -r</span><tt>,</tt>further
271files should be found in
273directories</p><div style="margin-left: 40px; font-family: Courier New,Courier,monospace;">~/palm/current_version/JOBS/example_cbl/MONITORING</div><p style="line-height: 100%;">and</p>
274<p style="line-height: 100%;"><span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
275</span><span style="font-family: Courier New,Courier,monospace;">~/palm/current_version/JOBS/example_cbl/OUTPUT</span><span style="font-family: monospace;"></span><br>
276</p><p style="line-height: 100%;">Please compare the
277contents of file</p>
278<p style="line-height: 100%;"><span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
279</span><span style="font-family: Courier New,Courier,monospace;">~/palm/current_version/JOBS/example_cbl/MONITORING/lcsgih_example_rc</span><br>
280</p><p style="line-height: 100%;">with those of the
281example result file which can be found under<span style="font-family: Courier New,Courier,monospace;">
282trunk/INSTALL/example_cbl_rc</span>., e.g. by using the<span style="font-family: Courier New,Courier,monospace;"><span style="font-family: Times New Roman,Times,serif;"> standard</span>
283diff </span>command:</p><p style="line-height: 100%; margin-left: 40px; font-family: Courier New,Courier,monospace;">diff
285trunk/INSTALL/example_cbl_rc</p><p style="line-height: 100%;">where
286it is assumed that your working directory is<span style="font-family: Courier New,Courier,monospace;">
287~/palm/current_version</span>.</p><span style="font-weight: bold;">You should not find any
288difference between these two files</span>, except of the run date
289and time displayed at the top of the file header. <font color="#000000">If
290the file contents are identical, the installation is successfully
291completed.<br><br></font><p style="line-height: 100%;"></p><p style="line-height: 100%; font-weight: bold; text-decoration: underline;"><font color="#000000"><a name="configuration_for_other_machines"></a>Configuration
292for other machines</font></p><font color="#000000">Starting
293from version 3.2a, beside the default hosts (HLRN, etc.), PALM can also
294be installed and run on other Linux-Cluster-, IBM-AIX, or
295NEC-SX-systems. To configure PALM for a non-default host only requires
296to add some lines to the configuration file<span style="font-family: Courier New,Courier,monospace;">
298you have to define the host identifier (a string of arbitrary length)
299under which your local host shall be identified by adding a line<br><br></font><div style="margin-left: 40px;"><span style="font-family: Courier New,Courier,monospace;">%host_identifier
300&nbsp;&lt;hostname&gt; &nbsp;&lt;host
301identifier&gt;</span><br></div><br>to the
302configuration file (best to do this in the section where the other
303default host identifiers are defined). Here<span style="font-family: Courier New,Courier,monospace;">
304&lt;hostname&gt; </span>must be the name of your local
305host as provided by the unix-command "<span style="font-family: Courier New,Courier,monospace;">hostname</span>".
306The first characters of<span style="font-family: Courier New,Courier,monospace;">
307&lt;host identifier&gt; </span>have to be "<span style="font-family: Courier New,Courier,monospace;">lc</span>",
308if your system is (part of) a linux-cluster, "<span style="font-family: Courier New,Courier,monospace;">ibm</span>",
309or "<span style="font-family: Courier New,Courier,monospace;">nec</span>"
310in case of an IBM-AIX- or NEC-SX-system, respectively. For example, if
311you want to install on a linux-cluster, the line may read as<br><br><div style="margin-left: 40px;">%host_identifier &nbsp;foo
313the second step, you have to give all informations neccessary to
314compile and run PALM on your local host by adding an additional section
315to the configuration file:<br><br><div style="margin-left: 40px; font-family: Courier New,Courier,monospace;">%remote_username&nbsp;&nbsp;
316&lt;1&gt;&nbsp; &nbsp; &nbsp; &lt;host
317identifier&gt; parallel<br>%tmp_user_catalog&nbsp;
318&lt;2&gt; &nbsp;&nbsp;&nbsp;&nbsp; &lt;host
319identifier&gt; parallel<br>%compiler_name&nbsp;&nbsp;&nbsp;&nbsp;
320&lt;3&gt; &nbsp;&nbsp;&nbsp;&nbsp; &lt;host
321identifier&gt; parallel<br>%compiler_name_ser
322&lt;4&gt; &nbsp;&nbsp;&nbsp;&nbsp; &lt;host
323identifier&gt; parallel<br>%cpp_options&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
324&lt;5&gt; &nbsp; &nbsp; &nbsp;&lt;host
326&lt;6&gt; &nbsp;&nbsp;&nbsp;&nbsp; &lt;host
327identifier&gt; parallel<br>%netcdf_lib&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
328&lt;7&gt; &nbsp;&nbsp;&nbsp;&nbsp; &lt;host
329identifier&gt; parallel<br>%fopts&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
330&lt;8&gt; &nbsp;&nbsp;&nbsp; &nbsp;&lt;host
331identifier&gt; parallel<br>%lopts&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
332&nbsp;&lt;9&gt; &nbsp; &nbsp;
333&nbsp;&lt;host identifier&gt; parallel<br></div><br>The
334section consists of four columns each separated by one or more blanks.
335The first column gives the name of the respective environment variable
336used by <span style="font-weight: bold;">mrun</span>
337and <span style="font-weight: bold;">mbuild</span>,
338while the second column defines its value. The third column has to be
339the host identifier as defined above, and the last column in each line
340must contain the string "<span style="font-family: Courier New,Courier,monospace;">parallel</span>".
341Otherwise, the respective line(s) will be interpreted as belonging to
342the setup for compiling and running a serial (non-parallel) version of
343PALM.<br><br>All brackets have to be replaced by the
344appropriate settings for your local host:<br><ul><li><span style="font-family: Courier New,Courier,monospace;">&lt;1&gt;
345</span>is the username on your LOCAL host</li><li><span style="font-family: Courier New,Courier,monospace;">&lt;2&gt;
346</span>is the temporary directory in which PALM runs will be
347carried out</li><li><span style="font-family: Courier New,Courier,monospace;">&lt;3&gt;
348</span>is the compiler name which generates parallel code</li><li><span style="font-family: Courier New,Courier,monospace;">&lt;4&gt;
349</span>is the compiler name for generating serial code</li><li><span style="font-family: Courier New,Courier,monospace;">&lt;5&gt;
351the preprocessor options to be invoked. In most of the cases, it will
352be neccessary to adjust the MPI data types to double precision by
353giving <span style="font-family: Courier New,Courier,monospace;">-DMPI_REAL=MPI_DOUBLE_PRECISION
354-DMPI_2REAL=MPI_2DOUBLE_PRECISION</span>. To switch on the NetCDF
355support, you also have to give <span style="font-family: Courier New,Courier,monospace;">-D__netcdf</span>
356and <span style="font-family: Courier New,Courier,monospace;">-D__netcdf4</span>
357(if you like to have NetCDF4/HDF5 data format; this requires a NetCDF4 library!).</li><li><span style="font-family: Courier New,Courier,monospace;">&lt;6&gt;
358</span>is the compiler option for specifying the include path to
359search for the NetCDF module/include files</li><li><span style="font-family: Courier New,Courier,monospace;">&lt;7&gt;
360</span>are the linker options to search for the NetCDF library</li><li><span style="font-family: Courier New,Courier,monospace;">&lt;8&gt;
361</span>are the general compiler options to be used. You should
362allways switch on double precision (e.g. <span style="font-family: Courier New,Courier,monospace;">-r8</span>)
363and code optimization (e.g. <span style="font-family: Courier New,Courier,monospace;">-O2</span>).</li><li><span style="font-family: Courier New,Courier,monospace;">&lt;9&gt;
364</span>are the linker options</li><li><span style="font-family: Courier New,Courier,monospace;">&lt;host
365identifier&gt; </span>is the host identifier as defined
366before</li></ul><br>A typical example may be:<br><div style="margin-left: 40px; font-family: Courier New,Courier,monospace;">%remote_username&nbsp;&nbsp;
367raasch &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
368&nbsp; &nbsp; &nbsp; &nbsp;
369&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
370&nbsp; &nbsp;lc_bar parallel<br>%tmp_user_catalog&nbsp;
377-DMPI_REAL=MPI_DOUBLE_PRECISION:-DMPI_2REAL=MPI_2DOUBLE_PRECISION:-D__netcdf&nbsp; lc_bar parallel<br>%netcdf_inc&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
379lc_bar parallel<br>%netcdf_lib&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
381lc_bar parallel<br>%fopts&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
382-axW:-cpp:-openmp:-r8:-nbs &nbsp; &nbsp; &nbsp;
384&nbsp;&nbsp;&nbsp; lc_bar parallel<br>%lopts&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
386parallel<br></div><br>Currently (version 3.7a),
387depending on the MPI
388version which is running on your local host, the options for the
389execution command (which may be <span style="font-family: Courier New,Courier,monospace;">mpirun</span>
390or <span style="font-family: Courier New,Courier,monospace;">mpiexec</span>)
391may have to be adjusted manually in the <span style="font-weight: bold;">mrun</span>-script. A future version
392will allow to give the respective settings in the configuration file.
393<p style="line-height: 100%;">If you have any problems
394with the PALM
395installation, the members of the PALM working group are pleased to
396help you.<br>
398<p style="line-height: 100%;"><br>
399<span style="font-weight: bold; text-decoration: underline;"><a name="simple_installation_method"></a>Simple installation method</span><br>
401<p style="line-height: 100%;">The simple installation method is using the scripts <span style="font-weight: bold;">palm_simple_install</span> and <span style="font-weight: bold;">palm_simple_run</span> for installing and running PALM.<br>
403<span style="font-weight: bold; text-decoration: underline;">Package
405<p style="line-height: 100%;"><span style="font-weight: bold;">First step:</span> Create a directory<span style="font-style: italic;"></span>:</p>
406<div style="margin-left: 40px; font-family: Courier New,Courier,monospace;">mkdir -p ~/palm/current_version/</div>
407<p style="line-height: 100%;">You can freely choose the directory name, but if you intend to switch to the <span style="font-style: italic;">advanced method</span> of running PALM later, you should use<span style="font-family: Courier New,Courier,monospace;"> ~/palm/current_version</span>. This directory <big><span style="font-family: monospace;"></span></big>will be called working directory from now on. </p>
409<p style="line-height: 100%;"><font color="#000000"><span style="font-weight: bold;">S</span><b>econd
411Check out a working copy of the recent PALM version from the svn-repository</font><font color="#000000">. Replace<span style="font-family: Courier New,Courier,monospace;"> &lt;your username&gt; </span>by your valid repository username, and<span style="font-family: Courier New,Courier,monospace;"> &lt;#&gt; </span>by any of the available
413releases, e.g. "<span style="font-style: italic;">3.7a</span>"
414(new releases will be announced to members of the PALM mailing list).</font></p>
415<div style="margin-left: 40px;"><span style="font-family: Courier New,Courier,monospace;">cd
416~/palm/current_version</span><br style="font-family: Courier New,Courier,monospace;"><span style="font-family: Courier New,Courier,monospace;">svn
417checkout --username &lt;your username&gt;
418svn://;#&gt; trunk</span><br></div>
419<p style="line-height: 100%;"><font color="#000000">You
420will be prompted for your password. After completion, a subdirectory</font><font style="font-family: Courier New,Courier,monospace;" color="#000000"> trunk <span style="font-family: Times New Roman,Times,serif;">will appear </span></font><font color="#000000">in your working directory. It contains a number of further
421subdirectories, which contain e.g. the PALM source code (</font><font style="font-family: Courier New,Courier,monospace;" color="#000000">SOURCE</font><font color="#000000">)
422and the scripts for running PALM (</font><font style="font-family: Courier New,Courier,monospace;" color="#000000">SCRIPTS</font><font color="#000000">). For checking out the most recent PALM version (developer version), see the <span style="font-style: italic;">advanced installation method</span> described above.<br>
424<p style="line-height: 100%;">Please never touch any file in
425your working copy of PALM, unless you really know what you
426are doing.</p>
429<p style="line-height: 100%;"><font color="#000000"><span style="font-weight: bold; text-decoration: underline;">Configuration and compilation<br>
431<p style="line-height: 100%;"><font color="#000000"><span style="font-weight: bold;">Third step:</span> To
432use the PALM scripts, the <span style="font-family: Courier New,Courier,monospace;">PATH</span>-variable
433has to be extended and the
434environment variable<span style="font-family: Courier New,Courier,monospace;">
435PALM_BIN </span>has to be set. For convenience, setting should be done
436in the respective profile of the users default shell (e.g. in<span style="font-family: Courier New,Courier,monospace;"> .profile</span>,
437if<span style="font-family: Courier New,Courier,monospace;">
438ksh </span>is used):</font></p>
439<p style="line-height: 100%; margin-left: 40px;"><font color="#000000"><span style="font-family: Courier New,Courier,monospace;">export
440PALM_BIN=</span></font><font style="font-family: Courier New,Courier,monospace;" color="#000000">$HOME/palm/current_version/trunk/SCRIPTS<br>
441</font><font style="font-family: Courier New,Courier,monospace;" color="#000000">export
442PATH=$PALM_BIN:$PATH</font><font color="#000000"><span style="font-family: Courier New,Courier,monospace;"><br>
444<p style="line-height: 100%;"><font color="#000000">You
445may have to login again in order to activate the profile settings.<br>
447<p style="line-height: 100%;"><font color="#000000"><span style="font-weight: bold;">Fourth step:</span> Call the installation script:<br>
449<p style="line-height: 100%; margin-left: 40px;"><font style="font-family: Courier New,Courier,monospace;" color="#000000">palm_simple_install -i</font><font color="#000000"><span style="font-family: Courier New,Courier,monospace;"><br>
452<p style="line-height: 100%;"><font color="#000000">The script copies the PALM source code into a new subdirectory <span style="font-family: Courier New,Courier,monospace;">MAKE_DEPOSITORY_simple</span>. This directory also will contain a <span style="font-family: Courier New,Courier,monospace;">Makefile</span> and an include file <span style="font-family: Courier New,Courier,monospace;"></span>
453to be used for compiling the code in the next step. The include file
454contains compiler name, compiler options, library path for NetCDF, etc.
455<span style="font-weight: bold;">Please adjust these settings as required by your system, before you proceed with the next step.</span> The default settings in <span style="font-family: Courier New,Courier,monospace;"></span>
456are for the Intel-FORTRAN compiler in the IMUK environment. You may
457find default settings for other compilers and environments in <span style="font-family: Courier New,Courier,monospace;">.../trunk/INSTALL/</span> See for files<span style="font-family: Courier New,Courier,monospace;">*</span>.<br>
459<p style="line-height: 100%; margin-left: 40px;"><span style="font-family: Courier New,Courier,monospace;">cd MAKE_DEPOSITORY_simple<br>
460</span><font color="#000000"><span style="font-family: Courier New,Courier,monospace;">make<br>
461cd ..<br>
465<p style="line-height: 100%;">In order to shorten compilation time, you can run make in parallel, e.g.<span style="font-family: Courier New,Courier,monospace;"> make -j 4 </span>runs 4 compile threads simultaneously.<br>
467<span style="font-weight: bold;">Fifth step:</span> Carry out a test
468run in order to check the installation. The test run (as every PALM
469run) requires a parameter file for steering PALM, which is in
470FORTRAN-NAMELIST format. This file has been already generated by the
471installation script <span style="font-family: Courier New,Courier,monospace;">palm_simple_install</span> under <span style="font-family: Courier New,Courier,monospace;">JOBS/example_cbl/INPUT/example_cbl_p3d</span><span style="font-family: Courier New,Courier,monospace;"></span>. PALM is started with script <span style="font-family: Courier New,Courier,monospace;">palm_simple_run</span>. <span style="font-weight: bold;">Before</span> the first run, it may be necessary to change the MPI-execution command (<span style="font-family: Courier New,Courier,monospace;">mpiexec</span>, <span style="font-family: Courier New,Courier,monospace;">mpirun</span>, etc.) and options in this script, depending on the MPI-library that you are using. The script can be found in directory <span style="font-family: Courier New,Courier,monospace;">.../trunk/SCRIPTS</span>.
472Default settings in this script are for the SGI-mpt-library installed
473on HLRN. You will find the execution command almost at the end of this
474script. After having adjusted the MPI-execution command, start the run
477<p style="line-height: 100%; margin-left: 40px;"><span style="font-family: Courier New,Courier,monospace;">palm_simple_run -p 4 -n 4 -c example_cbl</span><font color="#000000"><span style="font-family: Courier New,Courier,monospace;"><br>
482<p style="line-height: 100%;">where option <span style="font-family: Courier New,Courier,monospace;">-p</span> gives the total number of MPI tasks, <span style="font-family: Courier New,Courier,monospace;">-n</span> gives the number of MPI tasks per node, and <span style="font-family: Courier New,Courier,monospace;">-c</span> gives the parameter file to be used.<br>
483After the run has finished, all OUTPUT files can be found in directory <span style="font-family: Courier New,Courier,monospace;">OUTPUT....</span> Names and contents of PALM output files are described in <a href="chapter_3.4.html">chapter 3.4</a>.
484The directory name is composed of the parameter file name, the number
485of cores that have been used, and the current data and time. For every
486run a unique directory is created.<br>
488<p style="line-height: 100%;"><span style="font-weight: bold;">Sixth step:</span> To verify the results of this example run, compare it with the default result:<br>
489<span style="font-weight: bold;"></span></p>
490<p style="line-height: 100%; margin-left: 40px;"><span style="font-family: Courier New,Courier,monospace;">diff&nbsp; OUTPUT..../RUN_CONTROL&nbsp;&nbsp; trunk/INSTALL/example_cbl_rc</span><font color="#000000"><span style="font-family: Courier New,Courier,monospace;"><br>
496<span style="font-weight: bold;">You should not find any
497difference between these two files</span>, except of the run date
498and time displayed at the top of the file header, and, maybe, the number of cores that have been used. <font color="#000000">If
499the file contents are identical, the installation is successfully
500completed.</font><hr><p style="line-height: 100%;"><font color="#000080"><font color="#000080"><a href="chapter_4.6.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 style="border: 2px solid ; width: 32px; height: 32px;" alt="up" src="up.gif" name="Grafik2"></font></a><a href="chapter_5.1.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
501change:&nbsp;</i> $Id: chapter_5.0.html 287 2009-04-09
50208:59:36Z raasch $</p>
Note: See TracBrowser for help on using the repository browser.