Programming user-defined code extensions usually requires exact knowledge of the internal structure of PALM. Appropriate explanations in chapter 2.0 and the technical documentation are usually not sufficient and must be supplemented by a rigorous study of the model's source code. Programming experiences with FORTRAN95 and if necessary experiences with the parallelization tool MPI are absolutely necessary!
Changes of the standard model code by the user should be avoided whenever possible and are reserved to the developer-group of PALM. The corrections, revisions and extensions of the model accomplished by this group are published in the technical/numerical documentation and the accordingly updated source files are accessible to the users (see chapter 5.1).
However, the user frequently may feel the need to make extensions of the model code for his/her own simulations. For this purpose, a set of interfaces is available, which can be used to add user-defined code to the model. This chapter describes the programming of such user-defined code extensions.
The integration of user-defined code occurs in the form of subroutine calls, which are made at a set of places in the model code, by default. These subroutines have pre-defined names, which must not be changed by the user. Their basic versions are a component of the standard model code and can be found in the source code files user_***.f90. The basic versions accomplish nearly no actions, thus they are pure templates, which can be extended by the user as required. Actions which are already accomplished in these basic versions by default should not be changed. Here is an example of such a basic version (file user_init.f90):
SUBROUTINE user_init
!------------------------------------------------------------------------------
!
!
! Description:
! -----------
! Execution of user-defined initializing actions
!------------------------------------------------------------------------------
!
USE control_parameters
USE user
IMPLICIT NONE
!
!-- Here the user defined initializing actions follow:
END SUBROUTINE user_init
The communication (handling of variables) with the model occurs via the global variables, which are defined within the individual FORTRAN - modules of PALM. The appropriate modules (they are all in the source code file modules.f90) must be declared by means of USE statements in the user-defined routines in order to be able to work with the variables contained in them. As in the example, this is already done with the module control_parameters. This yields access to most of the existing parameters for steering the model. Furthermore, the module user appears in the example above. This is a user-defined module (it can be found in file user_module.f90) and can be used for communication between the user-defined routines. In this module own variables can be declared as desired. It is not used (and should not be used!) outside of the user code.
A very typical request of users is the calculation and output of quantities which are not part of PALM's standard output. Several routines in the basic user interface are already designed and prepared for calculating and output of such quantities (see 3.5.4).
As already mentioned, the contents of the files user_***.f90 can be used as a basis for extensions. However these files should not be manipulated directly. Instead, a copy should be used.
The following sections describe, which interfaces for user-defined code exist in the model, how user parameters can be defined for steering this code and how it is translated and linked to the model.
Last change: $Id: chapter_3.5.html 212 2008-11-11 09:09:24Z fricke $