Index: palm/trunk/TUTORIALS/cases/lsm_long/INPUT/lsm_long_p3d
===================================================================
--- palm/trunk/TUTORIALS/cases/lsm_long/INPUT/lsm_long_p3d	(revision 4098)
+++ palm/trunk/TUTORIALS/cases/lsm_long/INPUT/lsm_long_p3d	(revision 4222)
@@ -2,144 +2,164 @@
 !
 !-- grid parameters
-!------------------------------------------------------------------------------
-   nx                         = 19, 
-   ny                         = 19, 
-   nz                         = 50, 
+!-------------------------------------------------------------------------------
+    nx                         = 19, ! Number of gridboxes in x-direction (nx+1)
+    ny                         = 19, ! Number of gridboxes in y-direction (ny+1)
+    nz                         = 50, ! Number of gridboxes in z-direction (nz)
 
-   dx                         = 100.0, 
-   dy                         = 100.0, 
-   dz                         = 25.0, 
+    dx                         = 100.0, ! Size of single gridbox in x-direction
+    dy                         = 100.0, ! Size of single gridbox in y-direction
+    dz                         = 25.0, ! Size of single gridbox in z-direction
 
-   dz_stretch_level           = 100.0,
-   dz_max                     = 50
+    dz_stretch_level           = 100.0, ! Height (in m) where stretching starts
+    dz_max                     = 50.0,  ! maximum vertical grid size
 !
 !-- initialization
 !------------------------------------------------------------------------------
-   initializing_actions       = 'set_constant_profiles',
+    initializing_actions       = 'set_constant_profiles', ! initial conditions
 
-   ug_surface                 = 2.5, 
-   vg_surface                 = 0.0,
+    ug_surface                 = 2.5, ! u-comp of geostrophic wind at surface
+    vg_surface                 = 0.0, ! v-comp of geostrophic wind at surface
 
-   pt_surface                 = 293.0,
-   pt_vertical_gradient       =    0.0,  3.0,   0,
-   pt_vertical_gradient_level = 0.0,  800,  1600,
+    pt_surface                 = 293.0, ! initial surface potential temp
 
-   q_surface                  = 0.013, ! mixing ratio --> rel. hum. = ?
+    pt_vertical_gradient       = 0.0,
+                                 3.0,
+                                 0.0,     ! piecewise temp gradients
+    pt_vertical_gradient_level = 0.0,
+                                 800.0,
+                                 1600.0,  ! height level of temp gradients
+ 
+    q_surface                  = 0.013,   ! mixing ratio --> rel. hum. = ?
 
-   surface_pressure           = 1000.0,
+    surface_pressure           = 1000.0,  ! in hPa
 
-   day_of_year_init           = 172, ! June 21
-   time_utc_init              = 43200.0, ! 12:00 UTC
+    day_of_year_init           = 172,     ! June 21
+    time_utc_init              = 43200.0, ! 12:00 UTC
 !
 !-- physics
 !------------------------------------------------------------------------------
-   latitude                   = 53.37,
-   longitude                  = 9.73, ! Hannover
+    latitude                   = 53.37, ! geographical latitude
+    longitude                  = 9.73,  ! geographical longitude
 !
 !-- boundary conditions
 !------------------------------------------------------------------------------
-   constant_flux_layer        = .TRUE.,
+    constant_flux_layer        = .TRUE., ! use a constant flux layer at 
+                                         ! the bottom boundary
 
-
-   bc_pt_b                    = 'dirichlet', ! required when using LSM
-   bc_q_b                     = 'dirichlet', ! required when using LSM
-
-   rayleigh_damping_height    = 1600.0,
-   rayleigh_damping_factor    = 0.01,
+    bc_pt_b                    = 'dirichlet', ! required when using LSM
+    bc_q_b                     = 'dirichlet', ! required when using LSM
 !
 !-- mode
 !------------------------------------------------------------------------------
-   humidity                   = .TRUE., 
-   !precipitation              = .FALSE.,
+    humidity                   = .TRUE.,  ! use prognostic equation for humidity
 
-   reference_state            = 'horizontal_average',
+    reference_state            = 'horizontal_average', ! set reference state for
+                                                       ! buoyancy term
 !
 !-- numerics
 !------------------------------------------------------------------------------
-   fft_method                 = 'temperton-algorithm', !'fftw', !
-/
+    fft_method                 = 'temperton-algorithm', ! build-in fft method
 
+    rayleigh_damping_height    = 1600.0, ! starting height for Rayleigh damping
+    rayleigh_damping_factor    = 0.01,   ! strength of Rayleigh damping
+
+/ ! end of initialization parameter namelist
+
+!-------------------------------------------------------------------------------
+!-- RUNTIME PARAMETER NAMELIST
+!   Documentation: https://palm.muk.uni-hannover.de/trac/wiki/doc/app/d3par
+!-------------------------------------------------------------------------------
 &runtime_parameters
 !
 !-- run steering
+!-------------------------------------------------------------------------------
+    end_time                   = 216000.0, ! simulation time of the 3D model
+                                           ! (2.5 days)
+
+    create_disturbances        = .T.,    ! randomly perturbate horiz. velocity
+    dt_disturb                 = 120.0,  ! interval for random perturbations
+    disturbance_energy_limit   = 0.0001, ! upper limit for perturbation energy
+!
+!-- data output
 !------------------------------------------------------------------------------
-   end_time                   = 216000.0, ! 2.5 days
+    netcdf_data_format         = 2, ! use NetCDF3
 
-   create_disturbances        = .T.,
-   dt_disturb                 = 120.0, 
-   disturbance_energy_limit   = 0.0001,
-!
-!-- general output setting
-!------------------------------------------------------------------------------
-   netcdf_data_format         = 2, ! NetCDF3
-   dt_run_control             = 900.0,
-   dt_data_output             = 21600.0, ! 6 hours
-   dt_data_output_av          = 3600.0,
-   averaging_interval         = 1800.0,
-!
-!-- profile output setting
-!------------------------------------------------------------------------------
-   data_output_pr             = '#u', '#v', '#theta', '#q', '#thetav', 
-                                '#km', '#kh', '#l', 
-                                'w', 'e', 'e*', 'p', 
-                                'w"u"', 'w*u*', 'w"v"', 'w*v*',
-                                'w"theta"', 'w*theta*', 'w"thetav"', 'w*thetav*', 
-                                'w"q"', 'w*q*', 'w*e*',
-                                'theta*2', 'q*2', 'u*2', 'v*2', 'w*2',
-                                '#t_soil', '#m_soil',
-!
-!-- 2D and 3D output setting
-!------------------------------------------------------------------------------
-   section_xy                 = 0, ! surface variables only 
+    dt_run_control             = 900.0,   ! output interval for run control
+    dt_data_output             = 21600.0, ! output interval for general data
+    dt_data_output_av          = 3600.0,  ! output interval for averaged data
 
-   data_output                = 'theta', 'thetav', 'q', 'u', 'v', 
-                                'theta_av', 'thetav_av', 'q_av', 'u_av', 'v_av', 
+    averaging_interval         = 1800.0,  ! averaging interval general data
 
-                                't_soil',  't_soil_av', 
-                                'm_soil',  'm_soil_av',
+    data_output_pr             = '#u', '#v', '#theta', '#q', '#thetav', 
+                                 '#km', '#kh', '#l', 
+                                 'w', 'e', 'e*', 'p', 
+                                 'w"u"', 'w*u*', 'w"v"', 'w*v*',
+                                 'w"theta"', 'w*theta*', 'w"thetav"',
+                                 'w*thetav*', 
+                                 'w"q"', 'w*q*', 'w*e*',
+                                 'theta*2', 'q*2', 'u*2', 'v*2', 'w*2',
+                                 '#t_soil', '#m_soil',  ! Profile 
+                                                        ! output
 
-                                'us*_xy',   'us*_xy_av', 
-                                't*_xy',   't*_xy_av', 
-                                'r_a*_xy', 'r_a*_xy_av',
-                                'r_s*_xy', 'r_s*_xy_av',
-                                'tsurf*_xy', 'tsurf*_xy_av'
+    section_xy                 = 0, ! surface variables only 
 
-                                'ghf*_xy', 'ghf*_xy_av', 
-                                'shf*_xy', 'shf*_xy_av', 
+    data_output                = 'theta',         'theta_av',
+                                 'thetav',        'thetav_av',
+                                 'q',             'q_av',
+                                 'u',             'u_av',
+                                 'v',             'v_av',
 
-                                'qsws_liq*_xy',  'qsws_liq*_xy_av',
-                                'qsws_soil*_xy', 'qsws_soil*_xy_av',
-                                'qsws_veg*_xy',  'qsws_veg*_xy_av',
+                                 't_soil',        't_soil_av', 
+                                 'm_soil',        'm_soil_av',
 
-                                'c_liq*_xy',  'c_liq*_xy_av',
-                                'c_soil*_xy', 'c_soil*_xy_av',
-                                'c_veg*_xy',  'c_veg*_xy_av',
-/
+                                 'us*_xy',        'us*_xy_av', 
+                                 't*_xy',         't*_xy_av', 
+                                 'r_a*_xy',       'r_a*_xy_av',
+                                 'r_s*_xy',       'r_s*_xy_av',
+                                 'tsurf*_xy',     'tsurf*_xy_av'
 
+                                 'ghf*_xy',       'ghf*_xy_av', 
+                                 'shf*_xy',       'shf*_xy_av', 
+
+                                 'qsws_liq*_xy',  'qsws_liq*_xy_av',
+                                 'qsws_soil*_xy', 'qsws_soil*_xy_av',
+                                 'qsws_veg*_xy',  'qsws_veg*_xy_av',
+
+                                 'c_liq*_xy',     'c_liq*_xy_av',
+                                 'c_soil*_xy',    'c_soil*_xy_av',
+                                 'c_veg*_xy',     'c_veg*_xy_av', ! 2d and/ 
+                                                                  ! or 3d 
+                                                                  ! output
+/ ! end of runtime parameter namelist
+
+!-------------------------------------------------------------------------------
+!-- LAND-SURFACE PARAMETER NAMELIST
+!   Documentation: https://palm.muk.uni-hannover.de/trac/wiki/doc/app/lsmpar
+!-------------------------------------------------------------------------------
 &land_surface_parameters
-!
-!-- soil setup
-!------------------------------------------------------------------------------
-   soil_type                  = 3,
-   soil_temperature           = 293.0, 293.0, 293.0, 293.0, 
-                                293.0, 293.0, 293.0, 293.0,
-   deep_soil_temperature      = 293.0,
-   soil_moisture              = 0.35,  0.35,  0.35,  0.35,  
-                                0.35,  0.35,  0.35,  0.35, 
-!
-!-- boundary conditions
-!------------------------------------------------------------------------------
-   surface_type               = 'vegetation',
-   vegetation_type            = 3, 
-   vegetation_coverage        = 0.95,
-   c_surface                  = 0.0,
-   conserve_water_content     = .T.,
-/
+    soil_type                  = 3,  ! type to be used in soil model
+    soil_moisture              = 0.35,  0.35,  0.35,  0.35, ! moisture at every
+                                 0.35,  0.35,  0.35,  0.35, ! soil level
+    soil_temperature           = 293.0, 293.0, 293.0, 293.0, ! temperature at
+                                 293.0, 293.0, 293.0, 293.0, ! every soil level
+    deep_soil_temperature      = 293.0,  ! temperature of deep soil
 
+    surface_type               = 'vegetation',  ! surface classification
+    vegetation_type            = 3, ! vegetation to be used in surface model
+
+    vegetation_coverage        = 0.95, ! part of surface covered by vegetation
+                                       ! (0 - 1)
+    c_surface                  = 0.0,  ! surface heat capacity
+    conserve_water_content     = .T.,  ! closed (T) or open (F) lower boundary
+
+/ ! end of land-surface parameter namelist
+
+!-------------------------------------------------------------------------------
+!-- RADIATION PARAMETER NAMELIST
+!   Documentation: https://palm.muk.uni-hannover.de/trac/wiki/doc/app/radpar
+!-------------------------------------------------------------------------------
 &radiation_parameters
-!
-!-- general setup
-!------------------------------------------------------------------------------
-   radiation_scheme           = 'clear-sky',
-   dt_radiation               = 60.0, 
-/
+    radiation_scheme           = 'clear-sky', ! Radiation scheme to be used
+    dt_radiation               = 60.0, ! Time step of the radiation model
+
+/ ! end of radiation parameter namelist
