| 4 | | This page describes the installation of PALM on a Linux workstation (local host). There are two methods to install and run PALM. With the [#simple simple method], you can just run PALM interactively on the local computer. This method is using the scripts '''palm_simple_install''' and '''palm_simple_run'''. The [#simple simple method] has several restrictions, e.g. it does not allow to create batch jobs and restart runs. Also file handling and most other features of the [#advanced advanced method] are not available. This method is only recommended for users who like to do a quick test of PALM.\\\\ |
| 5 | | The [#advanced advanced method] is for running PALM in batch mode on a local or remote computer (batch jobs require a queueing system like NQS, PBS, or !LoadLeveler). The installation procedure is using the script '''mbuild'''. All jobs are started on the local host using the script '''mrun'''. If jobs are run on a remote host, the PALM output is automatically sent back to the local host. Alternatively, '''mrun''' can also be used to start PALM in interactive mode on the local host.\\\\ |
| 6 | | Only the [#advanced advanced method] gives full access to all PALM features.\\\\ |
| 7 | | Additionally an automatic PALM installation script is available [raw-attachment:palm_installer here] (beta).\\\\ |
| 8 | | |
| 9 | | == [=#requirements]Requirements == |
| | 4 | This page describes the installation of PALM on a Linux system. In this installation description we differentiate heavily between two perspectives on a computer. The first is the local computer (or local host), which is the computer that you are currently sitting at or are logged in via your terminal (ssh). The second is the remote computer (or remote host), which is any computer with a batch system, that you have ssh access to, but are not logged in at the moment. A typical remote computer is your favorite high performance computing (HPC) facility aka supercomputer. This perspective includes, that your remote (super)computer immediately becomes your local computer as soon as you log into it via ssh.\\\\ |
| | 5 | There are three methods to install and run PALM: |
| | 6 | |
| | 7 | - [#automatic An automatic installer]. |
| | 8 | - [#simple A simple manual installation method]. |
| | 9 | - [#advanced An advanced manual installation method]. |
| | 10 | |
| | 11 | With the automatic installer and the simple installation method, you can just run PALM interactively on the local computer. They do not allow to setup the creation of batch jobs and restart runs on any remote computer. This method is only recommended for users who like to do a quick test of PALM.\\\\ |
| | 12 | The advanced method gives full access to all PALM features. It should be chosen to setup PALMs ability to run in batch mode on a local or remote computer (batch jobs require a queueing system like NQS, PBS, or !LoadLeveler). Here it is possible to submit a job on the local host while instructing PALM to execute the job on your desired remote host. The PALM output is then automatically transfered back to the local computer. This method can of course also be used to work with PALM in interactive mode on the local computer. \\\\ |
| | 13 | |
| | 14 | == [=#requirements] Software Requirements == |
| 22 | | Currently, '''mrun''' is configured to be used on a limited number of selected machines. These are SGI-ICE systems at computing center HLRN in Hannover (''lcsgih''), Berlin (''lcsgib''), IBM-Regatta systems at Yonsei University (''ibmy''), and at DKRZ, Hamburg (''ibmh''), an NEC-SX8 system at RIAM, Kyushu University, Fukuoka (''necriam''), as well as on the Linux cluster of IMUK (''lcmuk''), Tokyo Institute of Technology (''lctit''), Kyoto computing center (''lckyoto''), and Cray-XE6 systems at the Bergen Center for Computational Science (''lcxe6'') and at the Finish Meteorological Institute (''lcxt5m''). The strings given in brackets are the systems names (host identifiers) under which '''mrun''' identifies the different hosts.\\\\ |
| | 27 | Regarding batch support PALM is currently configured to be used on a limited number of selected machines. These are SGI-ICE systems at computing center HLRN in Hannover (''lcsgih''), Berlin (''lcsgib''), IBM-Regatta systems at Yonsei University (''ibmy''), and at DKRZ, Hamburg (''ibmh''), an NEC-SX8 system at RIAM, Kyushu University, Fukuoka (''necriam''), as well as on the Linux cluster of IMUK (''lcmuk''), Tokyo Institute of Technology (''lctit''), Kyoto computing center (''lckyoto''), and Cray-XE6 systems at the Bergen Center for Computational Science (''lcxe6'') and at the Finish Meteorological Institute (''lcxt5m''). The strings given in brackets are the systems names (host identifiers) under which '''mrun''' identifies the different hosts.\\\\ |
| | 33 | == [=#automatic]Automatic installer == |
| | 34 | |
| | 35 | The easiest way to install PALM is our automatic PALM installation script (beta). Please do the following: |
| | 36 | |
| | 37 | 1. Make sure, you meet the requirements! |
| | 38 | 2. Download the automatic installation script [raw-attachment:palm_installer here]. |
| | 39 | 3. Open your terminal, go to your download directory and run the script by typing {{{bash palm_installer}}} |
| | 40 | |
| | 41 | The script will guide you through the installation process. As the installation script is still in beta, you may encounter problems. Please let us know, so we can further improve it. |
| | 42 | |
| | 43 | == [=#simple]Simple installation method == |
| | 44 | |
| | 45 | The simple installation method is using the scripts '''palm_simple_install''' and '''palm_simple_run''' for installing and running PALM.\\\\ |
| | 46 | |
| | 47 | === [=#package_installation_simple]Package installation === |
| | 48 | |
| | 49 | '''First step:''' Create a directory: |
| | 50 | {{{ |
| | 51 | mkdir -p ~/palm/current_version/ |
| | 52 | }}} |
| | 53 | You can freely choose the directory name, but if you intend to switch to the [#advanced advanced method] of running PALM later, you should use {{{~/palm/current_version}}}. This directory will be called working directory from now on. '''All commands listed below have to be run from this working directory unless otherwise specified.'''\\\\ |
| | 54 | '''Second step:''' Check out a working copy of the recent PALM version from the svn-repository. Replace {{{<your username>}}} by your valid repository username, and {{{<#>}}} by any of the available PALM releases, e.g. "''3.9''" (new releases will be announced to members of the PALM mailing list). |
| | 55 | {{{ |
| | 56 | cd ~/palm/current_version |
| | 57 | svn checkout --username <your username> http://130.75.105.7/svn/palm/tags/release-<#> trunk |
| | 58 | }}} |
| | 59 | You will be prompted for your password. After completion, a subdirectory trunk will 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}}}). For checking out the most recent PALM version (developer version), see the [#advanced advanced installation method] described above.\\\\ |
| | 60 | Please never touch any file in your working copy of PALM, unless you really know what you are doing.\\\\ |
| | 61 | |
| | 62 | === [=#config_simple]Configuration and compilation === |
| | 63 | |
| | 64 | '''Third step:''' To use the PALM scripts, the {{{PATH}}}-variable has to be extended and the environment variable {{{PALM_BIN}}} has to be set. For convenience, setting should be done in the respective profile of the users default shell (e.g. in {{{.profile}}}, if {{{ksh}}} is used): |
| | 65 | {{{ |
| | 66 | export PALM_BIN=$HOME/palm/current_version/trunk/SCRIPTS |
| | 67 | export PATH=$PALM_BIN:$PATH |
| | 68 | }}} |
| | 69 | You may have to login again in order to activate the profile settings.\\\\ |
| | 70 | '''Fourth step:''' Call the installation script: |
| | 71 | {{{ |
| | 72 | palm_simple_install -i <compiler-option-set> |
| | 73 | }}} |
| | 74 | {{{<compiler-option-set>}}} has to re replaced by the name of a file containing compiler options and library paths appropriate for your system. You can find some tested and verified files with compiler-option sets in the [source:palm/trunk/INSTALL INSTALL directory] of the repository. Look for filenames starting with {{{MAKE.inc.}}} and replace {{{<compiler-option-set>}}} with one of these names. If no one of these sets satisfies your requirements, just choose anyone and modify it in a later step (see below). The script copies the PALM source code as well as the file with this set of compiler options into a new subdirectory {{{MAKE_DEPOSITORY_simple}}}. '''This command has to be run from your working directory (e.g. {{{~/palm/current_version}}}).''' |
| | 75 | |
| | 76 | This directory will then contain a {{{Makefile}}} and an include file {{{MAKE.inc}}} to be used for compiling the code in the next step. The include file contains compiler name, compiler options, library path for netCDF, etc. '''If necessary, please adjust these settings in file {{{MAKE.inc}}} as required by your system, before you proceed with the next step.''' You probably will have to adjust at least the paths to the netCDF- and MPI-library on your respective system (arguments of Options {{{-L}}} and {{{-I}}}). '''This, of course, requires that you have already installed netCDF and MPI on your system (see [#requirements requirements]).''' |
| | 77 | {{{ |
| | 78 | cd MAKE_DEPOSITORY_simple |
| | 79 | make |
| | 80 | cd .. |
| | 81 | }}} |
| | 82 | In order to speed up compilation time, you can run make in parallel, e.g. {{{make -j 4}}} runs 4 compile threads simultaneously.\\\\ |
| | 83 | '''Fifth step:''' Carry out a test run in order to check the installation. The test run (as every PALM run) requires a parameter file for steering PALM, which is in FORTRAN-NAMELIST format. This file has been already generated by the installation script '''palm_simple_install''' under {{{JOBS/example_cbl/INPUT/example_cbl_p3d}}}. PALM is started with script '''palm_simple_run'''. '''Before''' the first run, it may be necessary to change the MPI-execution command ({{{mpiexec}}}, {{{mpirun}}}, etc.) and options in this script, depending on the MPI-library that you are using. The script can be found in directory {{{.../trunk/SCRIPTS}}}. Default settings in this script are for the SGI-mpt-library installed on HLRN. You will find the execution command almost at the end of this script. After having adjusted the MPI-execution command, start the run with: |
| | 84 | {{{ |
| | 85 | palm_simple_run -p 4 -n 4 -c example_cbl -e <execution-command> |
| | 86 | }}} |
| | 87 | where option {{{-p}}} gives the total number of MPI tasks, {{{-n}}} gives the number of MPI tasks per node, {{{-c}}} gives the parameter file to be used, and {{{-e}}} defines the execution command to be used to run the PALM executable. '''Note that this command also has to be run from your working directory (e.g. {{{~/palm/current_version}}}).''' You can choose from a number of different execution commands (see at the end of the script [source:palm/trunk/SCRIPTS/palm_simple_run palm_simple_run]), but you will probably have to modify them or oven add your own command to the script, since the mpiexec syntax differs a lot among the different MPI libraries. Example: if you want to do a run on the SGI-ICE system of HLRN with the SGI-mpt-environment, you can just use {{{-e sgi-mpt}}}.\\ |
| | 88 | After the run has finished, all OUTPUT files can be found in directory {{{OUTPUT...}}}. Names and contents of PALM output files are described [../app/iofiles here]. The directory name is composed of the parameter file name, the number of cores that have been used, and the current data and time. For every run a unique directory is created.\\\\ |
| | 89 | '''Sixth step:''' To verify the results of this example run, compare it with the default result: |
| | 90 | {{{ |
| | 91 | diff OUTPUT..../RUN_CONTROL trunk/INSTALL/example_cbl_rc |
| | 92 | }}} |
| | 93 | '''You should not find any difference between these two files,''' except for the run date and time displayed at the top of the file header, and, maybe, the number of cores that have been used. If the file contents are identical, the installation is successfully completed. |
| | 94 | \\ |
| | 95 | \\ |
| | 96 | \\ |
| | 97 | |
| 201 | | == [=#simple]Simple installation method == |
| 202 | | |
| 203 | | The simple installation method is using the scripts '''palm_simple_install''' and '''palm_simple_run''' for installing and running PALM.\\\\ |
| 204 | | |
| 205 | | === [=#package_installation_simple]Package installation === |
| 206 | | |
| 207 | | '''First step:''' Create a directory: |
| 208 | | {{{ |
| 209 | | mkdir -p ~/palm/current_version/ |
| 210 | | }}} |
| 211 | | You can freely choose the directory name, but if you intend to switch to the [#advanced advanced method] of running PALM later, you should use {{{~/palm/current_version}}}. This directory will be called working directory from now on. '''All commands listed below have to be run from this working directory unless otherwise specified.'''\\\\ |
| 212 | | '''Second step:''' Check out a working copy of the recent PALM version from the svn-repository. Replace {{{<your username>}}} by your valid repository username, and {{{<#>}}} by any of the available PALM releases, e.g. "''3.9''" (new releases will be announced to members of the PALM mailing list). |
| 213 | | {{{ |
| 214 | | cd ~/palm/current_version |
| 215 | | svn checkout --username <your username> http://130.75.105.7/svn/palm/tags/release-<#> trunk |
| 216 | | }}} |
| 217 | | You will be prompted for your password. After completion, a subdirectory trunk will 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}}}). For checking out the most recent PALM version (developer version), see the [#advanced advanced installation method] described above.\\\\ |
| 218 | | Please never touch any file in your working copy of PALM, unless you really know what you are doing.\\\\ |
| 219 | | |
| 220 | | === [=#config_simple]Configuration and compilation === |
| 221 | | |
| 222 | | '''Third step:''' To use the PALM scripts, the {{{PATH}}}-variable has to be extended and the environment variable {{{PALM_BIN}}} has to be set. For convenience, setting should be done in the respective profile of the users default shell (e.g. in {{{.profile}}}, if {{{ksh}}} is used): |
| 223 | | {{{ |
| 224 | | export PALM_BIN=$HOME/palm/current_version/trunk/SCRIPTS |
| 225 | | export PATH=$PALM_BIN:$PATH |
| 226 | | }}} |
| 227 | | You may have to login again in order to activate the profile settings.\\\\ |
| 228 | | '''Fourth step:''' Call the installation script: |
| 229 | | {{{ |
| 230 | | palm_simple_install -i <compiler-option-set> |
| 231 | | }}} |
| 232 | | {{{<compiler-option-set>}}} has to re replaced by the name of a file containing compiler options and library paths appropriate for your system. You can find some tested and verified files with compiler-option sets in the [source:palm/trunk/INSTALL INSTALL directory] of the repository. Look for filenames starting with {{{MAKE.inc.}}} and replace {{{<compiler-option-set>}}} with one of these names. If no one of these sets satisfies your requirements, just choose anyone and modify it in a later step (see below). The script copies the PALM source code as well as the file with this set of compiler options into a new subdirectory {{{MAKE_DEPOSITORY_simple}}}. '''This command has to be run from your working directory (e.g. {{{~/palm/current_version}}}).''' |
| 233 | | |
| 234 | | This directory will then contain a {{{Makefile}}} and an include file {{{MAKE.inc}}} to be used for compiling the code in the next step. The include file contains compiler name, compiler options, library path for netCDF, etc. '''If necessary, please adjust these settings in file {{{MAKE.inc}}} as required by your system, before you proceed with the next step.''' You probably will have to adjust at least the paths to the netCDF- and MPI-library on your respective system (arguments of Options {{{-L}}} and {{{-I}}}). '''This, of course, requires that you have already installed netCDF and MPI on your system (see [#requirements requirements]).''' |
| 235 | | {{{ |
| 236 | | cd MAKE_DEPOSITORY_simple |
| 237 | | make |
| 238 | | cd .. |
| 239 | | }}} |
| 240 | | In order to speed up compilation time, you can run make in parallel, e.g. {{{make -j 4}}} runs 4 compile threads simultaneously.\\\\ |
| 241 | | '''Fifth step:''' Carry out a test run in order to check the installation. The test run (as every PALM run) requires a parameter file for steering PALM, which is in FORTRAN-NAMELIST format. This file has been already generated by the installation script '''palm_simple_install''' under {{{JOBS/example_cbl/INPUT/example_cbl_p3d}}}. PALM is started with script '''palm_simple_run'''. '''Before''' the first run, it may be necessary to change the MPI-execution command ({{{mpiexec}}}, {{{mpirun}}}, etc.) and options in this script, depending on the MPI-library that you are using. The script can be found in directory {{{.../trunk/SCRIPTS}}}. Default settings in this script are for the SGI-mpt-library installed on HLRN. You will find the execution command almost at the end of this script. After having adjusted the MPI-execution command, start the run with: |
| 242 | | {{{ |
| 243 | | palm_simple_run -p 4 -n 4 -c example_cbl -e <execution-command> |
| 244 | | }}} |
| 245 | | where option {{{-p}}} gives the total number of MPI tasks, {{{-n}}} gives the number of MPI tasks per node, {{{-c}}} gives the parameter file to be used, and {{{-e}}} defines the execution command to be used to run the PALM executable. '''Note that this command also has to be run from your working directory (e.g. {{{~/palm/current_version}}}).''' You can choose from a number of different execution commands (see at the end of the script [source:palm/trunk/SCRIPTS/palm_simple_run palm_simple_run]), but you will probably have to modify them or oven add your own command to the script, since the mpiexec syntax differs a lot among the different MPI libraries. Example: if you want to do a run on the SGI-ICE system of HLRN with the SGI-mpt-environment, you can just use {{{-e sgi-mpt}}}.\\ |
| 246 | | After the run has finished, all OUTPUT files can be found in directory {{{OUTPUT...}}}. Names and contents of PALM output files are described [../app/iofiles here]. The directory name is composed of the parameter file name, the number of cores that have been used, and the current data and time. For every run a unique directory is created.\\\\ |
| 247 | | '''Sixth step:''' To verify the results of this example run, compare it with the default result: |
| 248 | | {{{ |
| 249 | | diff OUTPUT..../RUN_CONTROL trunk/INSTALL/example_cbl_rc |
| 250 | | }}} |
| 251 | | '''You should not find any difference between these two files,''' except for the run date and time displayed at the top of the file header, and, maybe, the number of cores that have been used. If the file contents are identical, the installation is successfully completed. |
| 252 | | \\ |
| 253 | | \\ |
| 254 | | \\ |
| | 272 | |
