= '''This page is under construction! ''' =
\\\\\\

= The PALM configuration file

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

 * the compiler and compiler options to be used
 * paths to required libraries (e.g. MPI, netCDF, or fftw)
 * preprocessor directives to switch on/off special features of PALM
 * paths to be used for storing PALM's input and output files
 * paths where user-interface routines and job protocol files can be found
 * the execute command to be used for starting the PALM executable
 * settings of other UNIX environment variable
 * batch job directives
 * unix commands to be executed before / after the PALM code is started, or that should be carried out in case of errors that appeared during the run

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.

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.


== How to generate a configuration file manually

As a first step, copy the default template of the configuration file (which is part of the PALM download) to your working directory:
{{{
  cd $HOME/palm/current_version
  cp trunk/SCRIPTS/.palm.config.default .
}}}

The configuration file is an ASCII file which you can open with any editor. The format of the file is simple:

* lines starting with a {{{#}}} in the first column are comment lines
{{{
# this is a comment line
}}}
* lines starting with a {{{%}}} in the first column are defining unix environment varibales used in {{{palmrun}}} and {{{palmbuild}}}.
{{{
%var value of var
}}}
means that a variable named {{{var}}} is created which is given the value {{{value of var}}}. There must be at least one blank between the variable name and its value. The value may contain an arbitrary number of blanks. The value can contain already defined variables:
{{{
%default_folder  /work/abcd
%subfolder1  $default_folder/efgh
}}} 
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 {{{-d}}}, 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.