The
following table
describes the available interfaces for user-defined code in the model,
the
names and possible arguments of the subroutines involved as well as
actions which can be accomplished in these subroutines.
Call location | Subroutine name and argument | Possible actions |
--- | MODULE user | All user-defined variables which are used outside the respective local scopes of the user-defined subroutines have to be declared here. |
End of parin.f90 | Declaration of
user-defined parameters in the NAMELIST
group &userpar.
These
parameters can be read from the local file PARIN
and be used for steering the user-defined code (see chapter
4.0). The user-defined parameter region
is already pre-defined in &userpar
and must not be changed. Additional NAMELIST groups may be declared if
desired. |
|
End of header.f90 |
Output of the values of the user-defined parameters to the local files HEADER and RUN_CONTROL. This output should be made anyway in order to subsequently check the parameter values used for the respective run. The number of the output unit is passed as an argument and must be used in each WRITE statement (e.g.: “WRITE ( io,…”)). By default, this subroutine only creates output if a user-defined NAMELIST is found in file PARIN (in this case the variable user_defined_namelist_found is set .TRUE. in user_parin). The names of any user-defined subdomains are displayed by default (see statistic_regions). | |
End of init_3d_model.f90 | Here, user-defined initialization actions which should be accomplished before the start of the 3D-model can be implemented (e.g. inhomogenous change of the surface temperature, the roughness length, or similar). At this point, all default parameter initializations of the model (chapter 4.1) have already been carried out at all. One of the most important actions here is the definition
of
user-defined subdomains for statistic analysis and output (see statistic_regions
and chapter
3.5.3) and of additional time series quantities (see comment
line example in the file). See also user_init_3d_model. | |
DEFAULT case of SELECT CASE( TRIM(topography) ) command in the middle of init_grid.f90 | user_init_grid | Execution of user-defined grid initializing actions. Here, the user can define the two-dimensional index array nzb_local that is used to set up a non-flat topography. This requires definition of at least one new topography mode in the SELECT CASE( TRIM(topography) ) command in user_init_grid. Note that the topography modes 'flat' and 'single_building' are not allowed here since these are the standard cases used in the calling routine init_grid. CPU time for user_init_grid is considered in the local file CPU_MEASURES within the category “initialisation”. |
In the middle of init_3d_model.f90 | user_init_3d_ model | Initialization of the 3d-model. Allows the complete initialization of the 3d model. The user is responsible to set at least all those quantities which are normally set within init_3d_model. |
In the middle of init_particles.f90 | With this routine e.g. size and color of particles, which have been released initially from a source, can be specified. Like the calling routine init_particles, this routine is only called if particle advection is switched on (see package parameter dt_prel). | |
End of advec_particles.f90 | Here the particles can be assigned new attributes (diameter, color etc.) after each time step. Like the calling routine advec_particles, this routine is only called if particle advection is switched on (see package parameter dt_prel). | |
Before the plot of particles and
cross-sections in | With this routine,
color tables can be adjusted which
should
be used for output with the dvrp software. Individuell color tables for
particles and cross-sections are possible. For this purpose the two
arrays interval_values_dvrp
and interval_h_dvrp
(declared in the module dvrp_variables)
have to be preset with appropriate values. The number of color table
entries must be assigned to the variable of dvrp_colourtable_entries.
The value of the subroutine argument mode defines,
whether the color
table is valid for particles or for cross-sections (i.e. mode
can have the values “particles”
or “slicer”). | |
Beginning and end of the time
integration loop
of |
or user_actions( i, j, location ) | In this routine user actions can be implemented which are to be executed either at each time step or at certain times (defined by the user). Since in each case the routine is called at the beginning and at the end of a time step as well as after each prognostic equation it must be defined at which place (and/or at which places) the respective actions are supposed to be executed. For this purpose an appropriate CASE structure is already inserted in this routine. The location of the calling routine is passed to this routine via the argument location. For example, if called at the beginning of a time step, location = 'before_timestep' and if called at the end, location = 'after_timestep'. Calculation of user-defined output quantities should be carried out at location = 'after_integration'. Important: if the cache-optimized version of prognostic_equation.f90 is used (this is the default for IBM-Regatta-Systems), the loop variables i and j must be passed as arguments for all calls within prognostic_equations. CPU time for user_actions
appears within the category “user_actions” in the
local file CPU_MEASURES.
If the cache-optimized version of prognostic_equation.f90
is used, this time measurement only considers the CPU time which was
needed outside of the prognostic equations. Time needed for calls
within prognostic_equations is considered within the category "all
prog.equations". Important: this subroutine is written as a FORTRAN module, which uses so-called function overloading. It can be called in two ways: with one argument (location) and with three arguments (i, j, location). The three argument version is used in the cache-optimized version of prognostic_equations. Depending on the number of given arguments the subroutine internally calls user_actions or user_actions_ij. So the user must insert the actions (code extensions) desired for the respective prognostic equation either in the CASE structure of user_actions, or/and in the CASE structure of user_actions_ij! |
flow_statistics.f90
before the summation of array hom
(horizontal averages) | Horizontal averages of vertical profiles of user-defined quantities can be computed here. Also, additional time series quantities can be calculated. They have to be defined before in routine user_init. The routine is called once for each defined statistic region (see statistic_region). The routine contains some simple examples (as comment lines) in order to demonstrate how to use it.
|
|
End of check_parameters.f90 where output quantities are checked | user_check_data_ output( variable, unit ) | Here the unit(s) of
user-defined output quantities (see data_output_user)
have to be set. Input parameter variable
contains the string identifier of the respective variable. For those
variables not recognized by the user, the parameter unit is set to
"illegal", which tells the calling routine that the output variable is
not defined and leads to a program abort. See chapter 3.5.4 about creating user-defined output quantities. |
netcdf.f90 (4 times) where the vertical grid coordinates for cross sections and volume data are defined | user_define_ netcdf_grid( variable, found, grid_x, grid_y, grid_z ) | Set the grid on which
user-defined output quantities (see data_output_user)
are defined. Input parameter variable
contains the string identifier of the respective variable. Allowed
values are 'x'
and 'xu'
for grid_x,
'y' and 'yv' for grid_y, and 'zu' and 'zw' for grid_z. The
output parameter found
has to be set .TRUE.
by the user, otherwise an error message will appear in the job protocol
for the respective output quantity. Example: If an output quantity is defined at the center of the grid boxes, the following settings have to be used: grid_x = 'x' grid_y = 'y' grid_z = 'zu' found = .TRUE. For defining an output quantity at the grid points where the u-velocity-component is defined, please use grid_x = 'xu' grid_y = 'y' grid_z = 'zu' found = .TRUE. See chapter 3.5.4 about creating user-defined output quantities. |
Middle of data_output_2d.f90 | user_data_ output_2d( av, variable, found, grid, local_pf ) | Resorts user-defined quantities
(to be output as cross-section data; see data_output_user)
with indices (k,j,i) to a temporary array local_pf with
indices (i,j,k) and sets the grid
on which they are defined. Depending on the value of input parameter av resorting is
done for instantaneous (av=0) or time averaged
data (av=1). Input parameter
variable
contains the string identifier of the respective variable. Allowed
values for grid
are 'zu'
and 'zw'.
The output parameter found
has to be set .TRUE.
by the user, otherwise an error message will appear in the job protocol
for the respective output quantity. See chapter 3.5.4 about creating user-defined output quantities. |
data_output_3d.f90 at the end of the CASE structure | user_data_ output_3d( av, variable, found, local_pf, nz_do ) | Resorts user-defined quantities
(to be output as volume data; see data_output_user)
with indices (k,j,i) to a temporary array local_pf with
indices (i,j,k) and sets the grid
on which they are defined. Depending on the value of input parameter av resorting is
done for instantaneous (av=0) or time averaged
data (av=1). Input parameter
variable
contains the string identifier of the respective variable. The input
parameter nz_do
defines the upper limit of vertical grid index k of the output array
(see nz_do3d).
The output parameter found
has to be set .TRUE.
by the user, otherwise an error message will appear in the job protocol
for the respective output quantity. See chapter 3.5.4 about creating user-defined output quantities. |
End of average_3d_data.f90, middle and end of sum_up_3d_data.f90 | user_3d_data_ averaging( mode, variable ) | Sum up and time-average of
user-defined output quantities (see data_output_user)
as well as allocation of the arrays necessary for storing the
respective averages. Input parameter variable
contains the string identifier of the respective variable. Depending on
the requested action, input parameter mode has the
value 'allocate',
'sum', or 'average'. See chapter 3.5.4 about creating user-defined output quantities. |
End of palm.f90 | User-defined
actions which are to be executed at the end
of a
model run. When user_last_actions
is called all model actions are already completed, but the files opened
by the model are not closed yet and possibly terminating actions for
these files (see subroutine of close_files)
are also not carried
out yet. |
Last change: $Id: chapter_3.5.1.html 62 2007-03-13 02:52:40Z heinze $