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 the rigorous study of the source code of the model. Programming experiences with FORTRAN95 and if necessary experiences with the parallelization tool MPI are absolutely neccessary!
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 they are all included in the source code file user_interface.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:
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 is located at the beginning of the file user_interface.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 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 file user_interface.f90 can be used as a basis for extensions. However the file should not be manipulated directly (it is anyway write protected by default), but it should be copied to another file. User write permits for this new file must be declared by means of the unix command chmod.
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 62 2007-03-13 02:52:40Z letzel $