| 1 | | = '''This page is under construction! ''' = |
| 2 | | \\\\\\ |
| 3 | | |
| 4 | | = The PALM configuration file |
| 5 | | |
| 6 | | Running PALM with the {{{palmrun}}} script or compiling PALM with {{{palmbuild}}} requires a configuration file in the working directory from where the scripts are called. The configuration file contains information about |
| 7 | | |
| 8 | | * the compiler and compiler options to be used |
| 9 | | * paths to required libraries (e.g. MPI, netCDF, or fftw) |
| 10 | | * preprocessor directives to switch on/off special features of PALM |
| 11 | | * paths to be used for storing PALM's input and output files |
| 12 | | * paths where user-interface routines and job protocol files can be found |
| 13 | | * the execute command to be used for starting the PALM executable |
| 14 | | * settings of other UNIX environment variable |
| 15 | | * batch job directives |
| | 1 | = The PALM configuration file = |
| | 2 | |
| | 3 | Running PALM with the {{{palmrun}}} script or compiling PALM with {{{palmbuild}}} requires a '''configuration file''' in the working directory from where the scripts are called. The configuration file contains information about |
| | 4 | |
| | 5 | * the compiler and compiler options to be used\\\\ |
| | 6 | * paths to required libraries (e.g. MPI, NetCDF, or fftw)\\\\ |
| | 7 | * pre-processor directives to switch on/off special features of PALM\\\\ |
| | 8 | * paths to be used for storing PALM's input and output files\\\\ |
| | 9 | * paths where user-interface routines and job protocol files can be found\\\\ |
| | 10 | * the execute command to be used for starting the PALM executable\\\\ |
| | 11 | * settings of other UNIX environment variable\\\\ |
| | 12 | * batch job directives\\\\ |
| 18 | | If PALM has been successfully installed by the automatic installer, the installer creates a configuration file named {{{.palm.config.default}}} in the working directory of the user (which by default is assumed to be {{{$HOME/palm/current_version}}}). This file should contain all relevant information to run PALM on the respective computer. |
| 19 | | |
| 20 | | The installer may fail for various reasons, e.g. because of mismatches in the user's system configuration. Problems may appear if the user has installed more than one FORTRAN compiler, and/or if the netCDF libraries have been generated with a different compiler than is used for compiling PALM. Furthermore, the automatic installer cannot be used on many larger computer systems where software (compilers, libraries) is managed via the {{{module}}} environment, or if you like to run batch jobs an a remote host. In all these cases, the user has to setup the configuration file manually. |
| 21 | | |
| 22 | | |
| 23 | | == How to generate a configuration file manually |
| | 15 | If PALM has been successfully installed by the automatic installer, the installer creates a configuration file named {{{.palm.config.default}}} in the working directory of the user, by default {{{$HOME/palm/current_version}}}. This file should contain all relevant information to run PALM on the respective computer in [wiki:doc/app/palmrun#interactive interactive mode]. If you encounter any problems, please check the [wiki:doc/install/automatic automatic installer] or [wiki:Help/FAQ FAQ] page. If you don't find a solution there, contact us via the [/newticket ticket system].\\ |
| | 16 | |
| | 17 | For [wiki:doc/app/palmrun#batch batch jobs] and in [wiki:doc/app/palmrun#batch_remote remote mode], the user has to modify the configuration file manually. |
| | 18 | |
| | 19 | |
| | 20 | == How to generate a configuration file manually == |
| 31 | | === Configuration file format |
| 32 | | |
| 33 | | The configuration file is an ASCII file which may be opened with any editor. The format of the file is simple. Lines need to start either with {{{#}}}, {{{%}}}, {{{IC:}}}, {{{OC:}}}, {{{EC:}}}, {{{BD:}}}, or {{{BDT:}}}. Empty line are allowed too. |
| 34 | | |
| 35 | | * lines starting with a {{{#}}} in the first column are comment lines |
| | 28 | === Configuration file format === |
| | 29 | |
| | 30 | The configuration file is an ASCII file which may be opened with any editor. Lines need to start with either\\ |
| | 31 | {{{#}}}, {{{%}}}, {{{IC:}}}, {{{OC:}}}, {{{EC:}}}, {{{BD:}}}, or {{{BDT:}}}. Empty lines are allowed. |
| | 32 | |
| | 33 | * {{{#}}} starts comment lines |
| 49 | | which means that {{{subfolder1}}} has the value {{{/work/abcd/efgh}}}. You can also use any variables that are already defined within the {{{palmrun}}}/{{{palmbuild}}} scripts. The most important one is {{{jobname}}}, which value is given with {{{palmrun}}} option {{{-r}}}, and which defines the so-called ''jobname''. This variable is mentioned here because it is used in the default configuration files for naming I/O files and to better sort I/O files from different PALM runs in an organized folder structure. Beside the value replacement using the UNIX shell syntax (i.e. {{{$abcd}}} gives the value of variable {{{abcd}}}), another way to insert values of environment variables is to write them in double curly brackets, i.e. {{{ {{abcd}} }}} will be replaced by the value of {{{abce}}}. This way of variable replacement is required for some special variables and in the job directives. |
| 50 | | |
| 51 | | * lines starting with {{{IC:}}} define any unix commands that are executed by {{{palmrun}}} just before the PALM code is started. A typical input command might be |
| | 47 | which means that {{{subfolder1}}} has the value {{{/work/abcd/efgh}}}. You can also use any variables that are already defined within the {{{palmrun}}}/{{{palmbuild}}} scripts. The most important one is {{{run_identifier}}}, given by {{{palmrun}}} option {{{-r}}}, and which defines the so-called ''run identifier''. This variable is mentioned here because it is used in the default configuration files for naming I/O files and to better sort I/O files from different PALM runs in an organized folder structure. Beside the value replacement using the UNIX shell syntax (i.e. {{{$abcd}}} gives the value of variable {{{abcd}}}), another way to insert values of environment variables is to write them in double curly brackets, i.e. {{{ {{abcd}} }}} will be replaced by the value of {{{abce}}}. This way of variable replacement is required for some special variables and in the job directives. |
| | 48 | |
| | 49 | * {{{IC:}}} defines any unix commands that are executed by {{{palmrun}}} just before the PALM code is started. A typical input command might be |
| 57 | | * lines starting with {{{OC:}}} define unix commands that are executed by {{{palmrun}}} just after the PALM code has stopped. For example, you may inform yourself about termination of the program by sending an email: |
| 58 | | {{{ |
| 59 | | OC:echo "PALM simulation $jobname has finished" | mailx username@email-address |
| 60 | | }}} |
| 61 | | |
| 62 | | * lines starting with {{{EC:}}} define unix commands that shall be executed in case that the PALM code or the {{{palmrun}}} script terminated because of any kind of error. You can restrict execution of error commands to specific kinds of error, e.g. errors that appear during PALM execution: |
| | 55 | * {{{OC:}}} defines unix commands that are executed by {{{palmrun}}} just after the PALM code has stopped. For example, you may inform yourself about termination of the program by sending an email: |
| | 56 | {{{ |
| | 57 | OC:echo "PALM simulation $run_identifier has finished" | mail username@email-address |
| | 58 | }}} |
| | 59 | |
| | 60 | * {{{EC:}}} defines unix commands that shall be executed in case that the PALM code or the {{{palmrun}}} script terminated because of any kind of error. You can restrict execution of error commands to specific kinds of error, e.g. errors that appear during PALM execution: |
| 66 | | See the {{{palmrun}}} source code for other specific locations that are used in this script. |
| 67 | | |
| 68 | | * lines starting with {{{BD:}}} define directives that are required for batch jobs, i.e. if PALM shall be run in batch mode. Explanations for batch directives are given further below. |
| 69 | | |
| 70 | | * lines starting with {{{BDT:}}} define directives for an additional batch job that is required in case of running PALM in batch mode on a remote host. This additional job transfers the job protocol file of the main PALM job back to the local host. |
| 71 | | |
| 72 | | |
| 73 | | === Environment variables and their meaning |
| | 64 | Search the {{{palmrun}}} script (.../trunk/SCRIPTS) for other specific locations that are used in this script. |
| | 65 | |
| | 66 | * {{{BD:}}} defines directives that are required for batch jobs, i.e. if PALM shall be run in batch mode. Explanations for batch directives are given further below. |
| | 67 | |
| | 68 | * {{{BDT:}}} defines directives for an additional batch job that is required in case of running PALM in batch mode on a remote host. This additional job transfers the job's log file of the main PALM job back to the local host. |
| | 69 | |
| | 70 | |
| | 71 | === Environment variables and their meaning === |
| 81 | 79 | || compiler_name || Name of the FORTRAN compiler to be used to create the PALM executable. Typically, this is the name of a wrapper script like ''mpif90'' or e.g. ''ftn'' on Cray machines, which automatically invokes the required MPI library and MPI include file. If you don't have a wrapper script, you may need to explicitly give compiler options (see {{{compiler_options}}}) to provide paths to the library / include file. If you like to run PALM without MPI (serial mode, or OpenMP parallelization), you should not use a wrapper script and give the original compiler name instead. |
| 82 | 80 | || compiler_name_ser || FORTRAN compiler name to create non-MPI executables. This name is required, because {{{palmbuild}}} generates several helper programs for pre-/post-processing, which run in serial mode on just one code. Here you give the original compiler name, like ''ifort'', ''pgfortran'', ''gfortran'', or ''xlf95''. |
| 88 | 86 | || hostfile || Name of the hostfile that is used by MPI to determine the nodes on which the MPI processes are started. \\\\ {{{palmrun}}} automatically generates the hostfile if you set {{{auto}}}. All MPI processes will then be started on the node on which {{{palmrun}}} is executed. The real name of the hostfile will then be set to {{{hostfile}}} (instead of {{{auto}}}) and, depending on your local MPI implementation, you may have to give this name in the {{{execute_command}}}. MPI implementations on large computer centers often do not require to explicitly specify a hostfile (in such a case you can remove this line from the configuration file), or the batch systems provides a hostfile which name you may access via environment variables (e.g. {{{$PBS_NODEFILE}}}) and which needs to be given in the {{{execute_command}}}. Please see your local system / batch system documentation about the hostfile policy on your system. |
| 89 | 87 | || linker_options || Compiler options to be used to link the PALM executable. Typically, these are paths to libraries used by PALM, e.g. NetCDF, FFTW, MPI, etc. You may repeat the options that you have given with {{{compiler_options}}} here. See your local system documentation / software manuals for required path settings. Requirements differ from system to system and also depend on the respective libraries that you are using. See [wiki:doc/app/recommended_compiler_options] for specific path settings that we, the PALM group, are using on our computers. Be aware, that these settings probably will not work on your computer system. |
