5.0 Installation of the model

This chapter describes the installation of PALM on a Linux workstation (local host) and a suitable remote computer, on which the model runs are to be carried out. The local host is used to start batch jobs with mrun and to analyze the results which are produced by the model on the remote host and send back to the local host. Alternatively, mrun can also be used to start PALM on the local host in interactive mode or as a batch job.

Requirements

The installation and operation of PALM requires at mimimum (on both, the local and the remote host, unless stated otherwise):

  1. The AT&T Korn-shell (ksh) must be available under /bin/ksh. Most of the current Linux distributions are using the public domain Korn-shell (pdksh). The PALM scripts mrun and mbuild do not work with the pdksh! Please replace it by the AT&T ksh. If the AT&T ksh path is different from /bin/ksh, please modify the first lines in mrun and mbuild, respectively.
  2. The NetCDF-library with version number not earlier than 3.6.0-p1 (for NetCDF, see under www.unidata.ucar.edu).
  3. A FORTRAN90/95 compiler.
  4. The Message Passing Interface (MPI), at least on the remote host, if the parallel version of PALM shall be used.
  5. On the local host, the revision control system subversion (see subversion.tigris.org). This is already included in many Linux distributions (e.g. SuSe). subversion requires port 3690 to be open for tcp/udp. If there are firewall restrictions concerning this port, the PALM code cannot be accessed. The user needs a permit to access the PALM repository. For getting a permit please contact the PALM group (raasch@muk.uni-hannover.de) and define a username under which you like to access the repository. You will then receive a password which allows the access under this name.
  6. A job queueing system must be available on the remote host. Currently, mrun can handle LoadLeveler (IBM-AIX) and NQS/PBS (Linux-Clusters, NEC-SX).
  7. ssh/scp-connections to and from the remote host must not be blocked by a firewall.
Currently, mrun is configured to be used on a limited number of selected machines. These are IBM-Regatta at computing center HLRN in Hannover (ibmh), Berlin (ibmb), at KISTI, Korea (ibms), at Yonsei University, Seoul (ibms), on NEC-SX6/8 systems at DKRZ, Hamburg (nech) and RIAM, Kyushu University, Fukuoka (neck), as well as on the Linux cluster of IMUK (lcmuk) and Tokyo Institute of Technology (lctit). The strings given in brackets are the systems names under which mrun indentifies the different hosts. mrun should also work on other systems, but this requires some modifications in the scripts mrun, mbuild, and subjob. Future PALM versions will allow to configure the scripts for different kinds of systems by just using a configuration file.

The examples given in this chapter refer to an installation of PALM on an IMUK Linux workstation and the IBM-Regatta system of the HLRN used as remote host. They are just called local and remote host from now on.

The installation process requires a valid account on the local and on the remote host as well.
 

Package Installation

In the first installation step a set of directories must be created both on the local and on the remote host. These directories are:

~/job_queue
~/palm
~/palm/current_version
~/palm/current_version/JOBS

The names of these directories are freely selectable (except ~/job_queue), however new users should use them as suggested, since many examples in this documentation as well as all example files are assuming these settings. The directory ~/palm/current_version on the local host will be called the working directory from now on.

In the second step a working copy of the recent version of the PALM software package, including the source code, scripts, documentation, etc.  must be copied to the working directory (local host!) by executing the following commands. Replace <your username> by the name that you choosed to access the repository, and <#> by any of the available PALM releases, e.g. "3.1c" (new releases will be anounced by email to the PALM mailing list).

cd ~/palm/current_version
svn checkout --username <your username> svn://130.75.105.45/palm/tags/release-<#> trunk

You will then be prompted for your password. After finishing, the subdirectory trunk should appear in your working directory. It contains a number of further subdirectories which contain e.g. the PALM source code (SOURCE) and the scripts for running PALM (SCRIPTS).

Alternatively, executing

svn checkout --username <your username> svn://130.75.105.45/palm/tags/release-<#> abcde

will place your working copy in a directory named abcde instead of a directory named trunk. But keep in mind that you will have to adjust several paths given below, if you do not use the default directory trunk.

Please never touch any file in your working copy of PALM, unless you know exactly what you are doing.

You can also get a copy of the most recent code by executing

svn checkout --username <your username> svn://130.75.105.45/palm/trunk trunk
However, this version may contain bugs and new features may not be documented. In future PALM releases, repository access to this most recent version will probably be restricted to the PALM developers.

Package Configuration

To use the PALM scripts, the PATH variable has to be extended and the environment variable PALM_BIN has to be set (on local and remote host) in the respective profile of the users default shell (e.g. in .profile, if ksh is used):

export PATH=$HOME/palm/current_version/trunk/SCRIPTS:$PATH
export PALM_BIN=$HOME/palm/current_version/trunk/SCRIPTS

You may habe to login again in order to activate these settings.

On the local and on the remote host, some small helper/utility programs have to be installed, which are e.g. later used by mrun or for PALM data postprocessing. The installation is done by mbuild. This script requires a configuration file .mrun.config, which will be also used by mrun in the following. A copy has to be put into the working directory under the name .mrun.config by

cp trunk/SCRIPTS/.mrun.config.default .mrun.config

Beside many other things, this file contains typical installation parameters like compiler name, compiler options, etc. for a set of different remote hosts. Please edit this file, uncomment lines like
#%remote_username  <replace by your ... username>   <remote-computer-shortcut>

by removing the first hash (#) character and replace the string "<replace by ...>" by your username on the respective host given in the <remote-computer-shortcut>. You only have to uncomment lines for those hosts on which you intend to use PALM.

After modifying the configuration file, the respective executables are generated by executing

mbuild -u -h lcmuk
mbuild -u -h ibmh

The second call also copies the PALM scripts like mrun and mbuild to the remote host.

Pre-Compilation of PALM Code


To avoid the re-compilation of the complete source code for each model run, PALM willl be pre-compiled once on the remote host by again using the script mbuild. Due to the use of FORTRAN modules in the source code, the subroutines must be compiled in a certain order. Therefore the so-called make mechanism is used (see the respective man-page of the Unix operating system), requiring a Makefile, in which the dependencies are described. This file is found in subdirectory trunk/SOURCE, where also the PALM code is stored. The compiled sources (object files) are stored on the remote computer in the default directory ~/palm/current_version/MAKE_DEPOSITORY.

The pre-compilation for the remote host (here the IBM-Regatta of HLRN) is done by

mbuild -h ibmh  

mbuild will prompt some queries, which must all be answered "y" by the user. The compiling process will take some time. mbuild transfers the respective compiler calls to the remote host where they are carried out interactively. You can follow the progress at the terminal window, where also error messages are displayed (hopefully not for this standard installation). By just entering

mbuild

PALM will be (consecutively) pre-compiled for all remote hosts listed in the configuration file. If you want to compile for the local host only, please enter

mbuild -h lcmuk

Installation Verification

As a last step, after the compilation has been finished, the PALM installation has to be verified. For this purpose a simple test run is carried out. This once again requires the mrun configuration file (described in chapter 3.2), as well as the parameter file (described in chapter 4.4). The parameter file must be copied from the PALM working copy by
mkdir -p JOBS/example/INPUT
cp trunk/INSTALL/example_p3d JOBS/example/INPUT/example_p3d

The test run can now be started by executing the command 

mrun -d example -h ibmh -K parallel -X 8 -T 8 -t 500 -q cdev -r “d3# pr#”
This specific run will be carried out on 8 PEs and is allowed to use up to 500 seconds CPU time. After pressing <return>, the most important settings of the job are displayed at the terminal window and the user is prompted for o.k. (“y”). Next, a message of the queuing system like “Request … Submitted to queue… by…” should be displayed. Now the job is queued and either started immediately or at a later time, depending on the current workload of the remote host. Provided that it is executed immediately and that all things work as designed, the job protocol of this run will appear under the file name ~/job_queue/ibmh_example no more than a few minutes later. The content of this file should be carefully examined for any error messages.

Beside the job protocol and according to the configuration file and arguments given for mrun options -d and -r,further files should be found in the directories

~/palm/current_version/JOBS/example/MONITORING

and

    ~/palm/current_version/JOBS/example/OUTPUT

Please compare the contents of file

    ~/palm/current_version/JOBS/example/MONITORING/ibmh_example_rc

with those of the example result file which can be found under trunk/INSTALL/example_rc., e.g. by using the standard diff command:

diff  JOBS/example/MONITORING/ibmh_example_rc trunk/INSTALL/example_rc

where it is assumed that your working directory is ~/palm/current_version.

You should not find any difference between these two files, except of the run date and time displayed at the top of the file header. If the file contents are identical, the installation is successfully completed.

If you have any problems with the PALM installation, the members of the PALM working group are pleased to help you.  

Last change:  02/03/07 (SR)