Model operation

The compilation and execution of PALM is controlled via a Unix shell scripts named mbuild and mrun, using bash/ksh syntax. mbuild compiles the default code using the Unix make mechanism. Compiler options, including C-preprocessor directives and required library paths (e.g., for netCDF or FFT), are given in a configuration file (default name .mrun.config). The configuration file allows for setting different compilers and options in separate blocks. The compiled source code (object files) is stored in a so-called depository folder(one folder for each option block). mrun takes care of the compilation (main program and user interface files only) and job submission/execution of PALM, including the handling of I/O files. The mrun command has a number of options to control the program execution. The execution is also controlled by the configuration file, which provides machine- and user-specific settings such as compiler options and library paths (see above), and I/O file locations. Basically, mrun performs the following tasks in sequential order:

Since each job runs in a unique temporary directory (see task 1), several jobs can run at the same time without interfering each other. The I/O files are handled (tasks 3 and 6) via so-called file connection statements, which allow to manage these files in a flexible way and to keep them in a well organized folder structure. A typical file connection statement for an input file reads

where the first column gives the local filename in the temporary working directory that must correspond to the filename in the OPEN statement in the PALM source code. The second column provides a file attribute (where in means that it is an input file), and the third column is the activating string that defines whether this file connection statement is carried out in the respective job. The fourth column gives the folder name where the permanent (input) file is provided by the user. Finally, the sixth column gives the suffix of the permanent file.

The full name of the permanent file results from the folder name, the suffix, and the value of the mrun option -d, which defines the so-called basename of all files handled by mrun, e.g., the mrun call

defines the filename to be

and which will be copied to PARIN in the temporary working directory (task 2) due to the setting of the activation string with the option -r. Besides, it is possible to organize jobs using the string $fname in the folder name column of the connection statement:

Here, the value of $fname is given by the -d option during the mrun call (here example_cbl) and all job files can be stored accordingly.

The mrun script never replaces or overwrites existing files. New so-called cycle numbers are created instead. For example, the file example_cbl_d3d (3-D data) has been created within a first model run. Then a second call of mrun and subsequent model execution will create a new file, named example_cbl_d3d.1, etc.

While some I/O operates on single files only (e.g., output of cpu measurements), other data (e.g. restart data) I/O is done by each core separately. In such cases, filenames provided by the file connection statements are interpreted as directory names. Each core then opens a file, named _###### in the respective directory, where the hashes stand for a six digit integer, declaring the rank of the MPI process in the MPI communicator in PALM.

Each simulation setup can be complemented by a separate set of user interface routines that replace the template files in the default code at compile time (see task 2). In this way, PALM executables will be dynamically created for each setup, based on the same default code, but with unique user code extensions. This also has the advantage, that it is generally possible to update the PALM version without the need of adapting own user-defined code. User interface routines for different setups can be stored in different folders, which are accessed by mrun using the basename mechanism as for I/O file described above.

At the beginning of task 4, various checks are performed on the parameter files and the provided user interface. Therewith, illegal model settings are trapped and reported to the user with a unique error message identifier. Moreover, several runtime and netCDF errors are captured by PALM in this way. A comprehensive online database provides additional information on each error message identifier (see online documentation PALM error messages).

Furthermore, mrun can be used to generate batch jobs on local and remote hosts, and it also controls the automatic generation of restart jobs/job chains. For convenience, an optional graphical user interface has been developed as a wrapper for mrun, called mrunGUI, providing an intuitive access to the mrun script (see Fig. 16).

Figure 16: Screenshot of the mrunGUI program.