= Interfaces for user-defined code =  
[[TracNav(doc/userint/toc)]]

'''Description:''' 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. The respective name of a source code files is the subroutine name followed by "{{{.f90}}}". Exception: the file containing the module {{{user}}} has the name {{{user_module.f90}}}.\\\\

||='''Call location'''  =||='''Subroutine name and argument(s)'''  =||='''Possible actions'''  =||
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
---
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user {{{MODULE user}}}]
}}}
{{{#!td
All user-defined variables which are used outside the respective local scopes of the user-defined subroutines have to be declared here.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
End of {{{parin.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_parin {{{user_parin}}}]
}}}
{{{#!td
Declaration of user-defined parameters in the {{{NAMELIST}}} group {{{&userpar}}}. These parameters can be read from the local file [../../iofiles#PARIN PARIN] and be used for steering the user-defined code (see [wiki:chapter_40 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. 
The CPU time needed for executing {{{user_parin}}} is included in the local file [../../iofiles#CPU_MEASURES CPU_MEASURES] within the category "initialisation".
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
End of {{{header.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_header {{{user_header( io )}}}]
}}}
{{{#!td
Output of the values of the user-defined parameters to the local files [../../iofiles#HEADER HEADER] and [../../iofiles#RUN_CONTROL 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 [../../iofiles#PARIN 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 [../../inipar#statistic_regions statistic_regions]).
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
End of {{{init_3d_model.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_init {{{user_init}}}]
}}}
{{{#!td
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 ([wiki:chapter_41 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 [../../inipar#statistic_regions statistic_regions] and [wiki:chapter_353 chapter 3.5.3]) and of additional time series quantities (see comment line example in the file). 
CPU time for user_init is considered in the local file [../../iofiles#CPU_MEASURES CPU_MEASURES] within the category "initialisation".\\
See also [#user_init_3d_model user_init_3d_model].
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
End of {{{read_3d_binary.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_read_restart_data {{{user_read_restart_data( }}}]\\{{{nxlc, nxlf, nxl_on_file,}}}\\{{{ nxrc, nxrf, nxr_on_file,}}}\\{{{ nync, nynf, nyn_on_file,}}}\\{{{ nysc, nysf, nys_on_file,}}}\\{{{ tmp_2d, tmp_3d )}}}
}}}
{{{#!td
Reading of user-defined 2d- and 3d-arrays from the restart file.\\
In case of restart runs, user-defined quantities may have to be read from the restart file generated by the previous run. These quantities must have been output by the user in the previous run using routine [#user_last_actions user_last_actions].\\\\
For usage, see example contained in {{{read_3d_binary.f90}}} and [#user_last_actions user_last_actions].
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
{{{DEFAULT}}} case of {{{SELECT CASE( TRIM(canopy_mode) )}}} command in the middle of  {{{init_3d_model.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_init_plant_canopy {{{user_init_plant_canopy}}}]
}}}
{{{#!td
User-defined initilisation of the plant canopy model.\\
Here, the user can define the two three-dimensional arrays {{{lad_s}}} and {{{cdc}}} that stand for the leaf area density and the canopy drag coefficient. By this, the user can configure a plant canopy. This requires definition of at least one new [../../inipar#canopy_mode canopy_mode] in the {{{SELECT CASE( TRIM(canopy_mode) )}}} command in {{{user_init_plant_canopy}}}. Note that the [../../inipar#canopy_mode canopy_mode]'' 'block' ''is not allowed here since it is the standard case used in the calling routine {{{init_3d_model}}}. 
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
{{{DEFAULT}}} case of {{{SELECT CASE( TRIM(topography) )}}} command in the middle of {{{init_grid.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_init_grid {{{user_init_grid}}}]
}}}
{{{#!td
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 [../../inipar#topography topography] mode in the {{{SELECT CASE( TRIM(topography) )}}} command and the definition of [../../inipar#topography_grid_convention topography_grid_convention] in {{{user_init_grid}}}. Note that the [../../inipar#topography topography] modes'' 'flat', 'single_building' ''and'' 'read_from_file' ''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 [../../iofiles#CPU_MEASURES CPU_MEASURES] within the category "initialisation".
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
End of {{{check_parameters}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_check_parameters {{{user_check_parameters}}}]
}}}
{{{#!td
Check {{{&userpar}}} control parameters and deduce further quantities.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
In the middle of {{{init_3d_model.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_init_3d_model {{{user_init_3d_model}}}]
}}}
{{{#!td
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}}}.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
In the middle of {{{init_particles.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_init_particles {{{user_init_particles}}}]
}}}
{{{#!td
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 [../../parpar#dt_prel dt_prel]).
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
End of {{{advec_particles.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_particle_attributes {{{user_particle}}}]\\{{{_attributes}}}
}}}
{{{#!td
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 [../../parpar#dt_prel dt_prel])
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
Before the plot of particles and cross-sections in {{{dvrp_plot.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_dvrp_coltab {{{user_dvrp_coltab}}}]\\{{{( mode )}}}
}}}
{{{#!td
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''). 
This routine only becomes active if dvrp-graphics is switched on (see package parameter [../../dvrpar#dt_dvrp dt_dvrp]).
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
Beginning and end of the time integration loop of {{{time_integration.f90}}}\\as well as after each prognostic equation in
{{{prognostic_equations.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_actions {{{user_actions}}}]\\{{{( location )}}}\\\\or\\\\{{{user_actions}}}\\{{{( i, j, location )}}}
}}}
{{{#!td
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 [../../iofiles#CPU_MEASURES 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}}}!
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
SUBROUTINE {{{preprocess_spectra}}}\\in {{{calc_spectra.f90}}}\\and {{{data_output_spectra.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_spectra {{{user_spectra}}}]
}}}
{{{#!td
Computation of [../output#spectra user-defined] [../output#spectra spectra]. \\
The routine contains some simple examples (as comment lines) in order to demonstrate how to use it.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
{{{flow_statistics.f90}}} before the summation of array {{{hom}}} (horizontal averages)
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_statistics {{{user_statistics}}}]{{{( sr )}}}
}}}
{{{#!td
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 user_init]. The routine is called once for each defined  statistic_region (see [../../inipar#statistic_regions statistic_regions]).\\
The routine contains some simple examples (as comment lines) in order to demonstrate how to use it.\\\\
Profile sums have to be stored in the array {{{sums_l}}}. The profile identification number (second index of array {{{sums_l}}}) must be within the range [ {{{pr_palm+1}}} , {{{pr_palm+max_pr_user}}} ], where {{{pr_palm}}} is an internal parameter and  {{{max_pr_user}}} is the number of user-defined profiles as given by parameter [../../userpar#data_output_pr_user data_output_pr_user] in the respective {{{PALM}}} run. \\
These additional profiles are further processed (e.g. temporally averaged), like the standard profiles, in {{{flow_statistics}}}.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
Middle of {{{advec_particles.f90}}}, after particle reflection from walls.
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_advec_particles {{{user_advec_particles}}}]
}}}
{{{#!td
User-defined actions after the calculation of the new particle position.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
End of {{{check_parameters.f90}}} where 2d/3d output quantities are checked
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_check_data_output {{{user_check_data_output}}}]\\{{{( variable, unit )}}}
}}}
{{{#!td
Here the physical {{{unit}}}(s) of user-defined 2d/3d output quantities (see [../../userpar#data_output_user 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 [[../output|User-defined output quantities]] about creating user-defined output quantities.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
End of {{{check_parameters.f90}}} where vertical profile output quantities are checked
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_check_data_output_pr {{{user_check_data_output}}}\\{{{_pr}}}]{{{(variable,}}}\\{{{var_count, unit )}}}
}}}
{{{#!td
Here the physical {{{unit}}}(s) and vertical grid (u- or w-grid) of user-defined vertical profile output quantities (see [../../userpar#data_output_pr_user data_output_pr_user]) have to be set. Input parameter {{{variable}}} contains the string identifier of the respective variable. Parameter {{{var_count}}} contains the internal profile number and must not be changed by the user. 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 [[../output|User-defined output quantities]] about creating user-defined output quantities.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
{{{netcdf.f90}}} (4 times) where the vertical grid coordinates for cross sections and volume data are defined
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_define_netcdf_grid {{{user_define_netcdf_grid}}}] \\{{{( variable, found,}}}\\{{{grid_x, grid_y,}}}\\{{{grid_z )}}}
}}}
{{{#!td
Set the grid on which user-defined output quantities (see [../../userpar#data_output_user 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 [wiki:chapter_354 chapter 3.5.4] about creating user-defined output quantities.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
Middle of {{{data_output_2d.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_data_output_2d {{{user_data_output_2d}}}]\\{{{( av, variable,}}}\\{{{found, grid,}}}\\{{{local_pf )}}}
}}}
{{{#!td
Resorts user-defined quantities (to be output as cross-section data; see [../../userpar#data_output_user 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 [[../output|User-defined output quantities]] about creating user-defined output quantities.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
{{{data_output_3d.f90}}} at the end of the {{{CASE}}} structure
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_data_output_3d {{{user_data_output_3d}}}]\\{{{( av, variable, found,}}}\\{{{local_pf, nz_do )}}}
}}}
{{{#!td
Resorts user-defined quantities (to be output as volume data; see [../../userpar#data_output_user 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 [../../d3par#)nz_do3d 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 [[../output|User-defined output quantities]] about creating user-defined output quantities.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
{{{data_output_mask.f90}}} at the end of the {{{CASE}}} structure
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_data_output_mask {{{user_data_output_mask}}}]\\{{{( av, variable, found,}}}\\{{{local_pf)}}}
}}}
{{{#!td
Resorts user-defined quantities (to be output as masked data; see [../../userpar#data_output_masks_user data_output_masks_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 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 [[../output|User-defined output quantities]] about creating user-defined output quantities.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
End of {{{average_3d_data.f90}}}, middle and end of {{{sum_up_3d_data.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_3d_data_averaging {{{user_3d_data_averaging}}}]\\{{{( mode, variable )}}}
}}}
{{{#!td
Sum up and time-average of user-defined output quantities (see [../../userpar#data_output_user 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 [[../output|User-defined output quantities]] about creating user-defined output quantities. 
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
{{{DEFAULT}}} case of {{{SELECT CASE( output_variable )}}} command near the end of {{{data_output_dvrp.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_data_output_dvrp {{{user_data_output_dvrp}}}]\\{{{( output_variable, local_pf )}}}
}}}
{{{#!td
Resorts user-defined quantities (to be output as dvrp objects; see [../../userpar#data_output_user data_output_user]) and [../../dvrpar#mode_dvrp mode_dvrp]) with indices {{{(k,j,i)}}} to a temporary array {{{local_pf}}} with indices {{{(i,j,k)}}}. The array {{{local_pf}}} is then handed back to the calling subroutine {{{data_output_dvrp.f90}}}.\\
See [[../output|User-defined output quantities]] about creating user-defined output quantities.
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
End of {{{palm.f90}}}
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_last_actions {{{user_last_actions}}}]
}}}
{{{#!td
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. 
CPU time for {{{user_last_actions}}} appears in the local file [../../iofiles#CPU_MEASURES CPU_MEASURES] within the category "last actions" (the time necessary for {{{close_files}}} is included).
}}}
|----------------
{{{#!td style="vertical-align:top; text-align:left;width: 150px"
Not called in the default {{{PALM}}} code
}}}
{{{#!td style="vertical-align:top; text-align:left;style="width: 50px"
[=#user_additional_ {{{user_additional}}}]\\{{{_routines}}}
}}}
{{{#!td
This routine may contain additional routines defined by the user to be called from other user interface routines.
}}}