Index: palm/trunk/SOURCE/poismg.f90
===================================================================
--- palm/trunk/SOURCE/poismg.f90	(revision 1354)
+++ palm/trunk/SOURCE/poismg.f90	(revision 1682)
@@ -1,4 +1,3 @@
- SUBROUTINE poismg( r )
-
+!> @file poismg.f90
 !--------------------------------------------------------------------------------!
 ! This file is part of PALM.
@@ -18,10 +17,7 @@
 !--------------------------------------------------------------------------------!
 !
-! Attention: Loop unrolling and cache optimization in SOR-Red/Black method
-!            still does not give the expected speedup! Further work required.
-!
 ! Current revisions:
 ! -----------------
-! 
+! Code annotations made doxygen readable 
 ! 
 ! Former revisions:
@@ -116,10 +112,17 @@
 ! Description:
 ! ------------
-! Solves the Poisson equation for the perturbation pressure with a multigrid
-! V- or W-Cycle scheme.
-!
-! This multigrid method was originally developed for PALM by Joerg Uhlenbrock,
-! September 2000 - July 2001.
+!> Solves the Poisson equation for the perturbation pressure with a multigrid
+!> V- or W-Cycle scheme.
+!>
+!> This multigrid method was originally developed for PALM by Joerg Uhlenbrock,
+!> September 2000 - July 2001.
+!> 
+!> @attention Loop unrolling and cache optimization in SOR-Red/Black method
+!>            still does not give the expected speedup! 
+!>
+!> @todo Further work required.
 !------------------------------------------------------------------------------!
+ SUBROUTINE poismg( r )
+ 
 
     USE arrays_3d,                                                             &
@@ -144,11 +147,11 @@
     IMPLICIT NONE
 
-    REAL(wp) ::  maxerror          !:
-    REAL(wp) ::  maximum_mgcycles  !:
-    REAL(wp) ::  residual_norm     !:
-
-    REAL(wp), DIMENSION(nzb:nzt+1,nys-1:nyn+1,nxl-1:nxr+1) ::  r  !:
-
-    REAL(wp), DIMENSION(:,:,:), ALLOCATABLE ::  p3  !:
+    REAL(wp) ::  maxerror          !<
+    REAL(wp) ::  maximum_mgcycles  !<
+    REAL(wp) ::  residual_norm     !<
+
+    REAL(wp), DIMENSION(nzb:nzt+1,nys-1:nyn+1,nxl-1:nxr+1) ::  r  !<
+
+    REAL(wp), DIMENSION(:,:,:), ALLOCATABLE ::  p3  !<
 
 
@@ -240,12 +243,11 @@
 
 
-
- SUBROUTINE resid( f_mg, p_mg, r )
-
 !------------------------------------------------------------------------------!
 ! Description:
 ! ------------
-! Computes the residual of the perturbation pressure.
+!> Computes the residual of the perturbation pressure.
 !------------------------------------------------------------------------------!
+ SUBROUTINE resid( f_mg, p_mg, r )
+
 
     USE arrays_3d,                                                             &
@@ -277,11 +279,11 @@
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                     nys_mg(grid_level)-1:nyn_mg(grid_level)+1,                 &
-                    nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  f_mg  !:
+                    nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  f_mg  !<
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                     nys_mg(grid_level)-1:nyn_mg(grid_level)+1,                 &
-                    nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  p_mg  !:
+                    nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  p_mg  !<
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                     nys_mg(grid_level)-1:nyn_mg(grid_level)+1,                 &
-                    nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  r     !:
+                    nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  r     !<
 
 !
@@ -377,13 +379,12 @@
 
 
-
- SUBROUTINE restrict( f_mg, r )
-
 !------------------------------------------------------------------------------!
 ! Description:
 ! ------------
-! Interpolates the residual on the next coarser grid with "full weighting"
-! scheme
+!> Interpolates the residual on the next coarser grid with "full weighting"
+!> scheme.
 !------------------------------------------------------------------------------!
+ SUBROUTINE restrict( f_mg, r )
+
 
     USE control_parameters,                                                    &
@@ -402,37 +403,37 @@
     IMPLICIT NONE
 
-    INTEGER(iwp) ::  i    !:
-    INTEGER(iwp) ::  ic   !:
-    INTEGER(iwp) ::  j    !:
-    INTEGER(iwp) ::  jc   !:
-    INTEGER(iwp) ::  k    !:
-    INTEGER(iwp) ::  kc   !:
-    INTEGER(iwp) ::  l    !:
-
-    REAL(wp) ::  rkjim    !:
-    REAL(wp) ::  rkjip    !:
-    REAL(wp) ::  rkjmi    !:
-    REAL(wp) ::  rkjmim   !:
-    REAL(wp) ::  rkjmip   !:
-    REAL(wp) ::  rkjpi    !:
-    REAL(wp) ::  rkjpim   !:
-    REAL(wp) ::  rkjpip   !:
-    REAL(wp) ::  rkmji    !:
-    REAL(wp) ::  rkmjim   !:
-    REAL(wp) ::  rkmjip   !:
-    REAL(wp) ::  rkmjmi   !:
-    REAL(wp) ::  rkmjmim  !:
-    REAL(wp) ::  rkmjmip  !:
-    REAL(wp) ::  rkmjpi   !:
-    REAL(wp) ::  rkmjpim  !:
-    REAL(wp) ::  rkmjpip  !:
+    INTEGER(iwp) ::  i    !<
+    INTEGER(iwp) ::  ic   !<
+    INTEGER(iwp) ::  j    !<
+    INTEGER(iwp) ::  jc   !<
+    INTEGER(iwp) ::  k    !<
+    INTEGER(iwp) ::  kc   !<
+    INTEGER(iwp) ::  l    !<
+
+    REAL(wp) ::  rkjim    !<
+    REAL(wp) ::  rkjip    !<
+    REAL(wp) ::  rkjmi    !<
+    REAL(wp) ::  rkjmim   !<
+    REAL(wp) ::  rkjmip   !<
+    REAL(wp) ::  rkjpi    !<
+    REAL(wp) ::  rkjpim   !<
+    REAL(wp) ::  rkjpip   !<
+    REAL(wp) ::  rkmji    !<
+    REAL(wp) ::  rkmjim   !<
+    REAL(wp) ::  rkmjip   !<
+    REAL(wp) ::  rkmjmi   !<
+    REAL(wp) ::  rkmjmim  !<
+    REAL(wp) ::  rkmjmip  !<
+    REAL(wp) ::  rkmjpi   !<
+    REAL(wp) ::  rkmjpim  !<
+    REAL(wp) ::  rkmjpip  !<
 
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                            &
                         nys_mg(grid_level)-1:nyn_mg(grid_level)+1,           &
-                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  f_mg  !:
+                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  f_mg  !<
 
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level+1)+1,                          &
                         nys_mg(grid_level+1)-1:nyn_mg(grid_level+1)+1,       &
-                        nxl_mg(grid_level+1)-1:nxr_mg(grid_level+1)+1) ::  r !:
+                        nxl_mg(grid_level+1)-1:nxr_mg(grid_level+1)+1) ::  r !<
 
 !
@@ -585,13 +586,12 @@
 
 
-
- SUBROUTINE prolong( p, temp )
-
 !------------------------------------------------------------------------------!
 ! Description:
 ! ------------
-! Interpolates the correction of the perturbation pressure 
-! to the next finer grid.
+!> Interpolates the correction of the perturbation pressure 
+!> to the next finer grid.
 !------------------------------------------------------------------------------!
+ SUBROUTINE prolong( p, temp )
+
 
     USE control_parameters,                                                    &
@@ -607,16 +607,16 @@
     IMPLICIT NONE
 
-    INTEGER(iwp) ::  i  !:
-    INTEGER(iwp) ::  j  !:
-    INTEGER(iwp) ::  k  !:
-    INTEGER(iwp) ::  l  !:
+    INTEGER(iwp) ::  i  !<
+    INTEGER(iwp) ::  j  !<
+    INTEGER(iwp) ::  k  !<
+    INTEGER(iwp) ::  l  !<
 
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level-1)+1,                           &
                         nys_mg(grid_level-1)-1:nyn_mg(grid_level-1)+1,        &
-                        nxl_mg(grid_level-1)-1:nxr_mg(grid_level-1)+1 ) ::  p  !:
+                        nxl_mg(grid_level-1)-1:nxr_mg(grid_level-1)+1 ) ::  p  !<
 
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                           &
                         nys_mg(grid_level)-1:nyn_mg(grid_level)+1,          &
-                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  temp  !:
+                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  temp  !<
 
 
@@ -692,12 +692,12 @@
 
 
- SUBROUTINE redblack( f_mg, p_mg )
-
 !------------------------------------------------------------------------------!
 ! Description:
 ! ------------
-! Relaxation method for the multigrid scheme. A Gauss-Seidel iteration with
-! 3D-Red-Black decomposition (GS-RB) is used.
+!> Relaxation method for the multigrid scheme. A Gauss-Seidel iteration with
+!> 3D-Red-Black decomposition (GS-RB) is used.
 !------------------------------------------------------------------------------!
+ SUBROUTINE redblack( f_mg, p_mg )
+
 
     USE arrays_3d,                                                             &
@@ -725,29 +725,29 @@
     IMPLICIT NONE
 
-    INTEGER(iwp) :: color    !:
-    INTEGER(iwp) :: i        !:
-    INTEGER(iwp) :: ic       !:
-    INTEGER(iwp) :: j        !:
-    INTEGER(iwp) :: jc       !:
-    INTEGER(iwp) :: jj       !:
-    INTEGER(iwp) :: k        !:
-    INTEGER(iwp) :: l        !:
-    INTEGER(iwp) :: n        !:
-
-    LOGICAL :: unroll        !:
-
-    REAL(wp) ::  wall_left   !:
-    REAL(wp) ::  wall_north  !:
-    REAL(wp) ::  wall_right  !:
-    REAL(wp) ::  wall_south  !:
-    REAL(wp) ::  wall_total  !:
-    REAL(wp) ::  wall_top    !:
+    INTEGER(iwp) :: color    !<
+    INTEGER(iwp) :: i        !<
+    INTEGER(iwp) :: ic       !<
+    INTEGER(iwp) :: j        !<
+    INTEGER(iwp) :: jc       !<
+    INTEGER(iwp) :: jj       !<
+    INTEGER(iwp) :: k        !<
+    INTEGER(iwp) :: l        !<
+    INTEGER(iwp) :: n        !<
+
+    LOGICAL :: unroll        !<
+
+    REAL(wp) ::  wall_left   !<
+    REAL(wp) ::  wall_north  !<
+    REAL(wp) ::  wall_right  !<
+    REAL(wp) ::  wall_south  !<
+    REAL(wp) ::  wall_total  !<
+    REAL(wp) ::  wall_top    !<
 
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                         nys_mg(grid_level)-1:nyn_mg(grid_level)+1,             &
-                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  f_mg  !:
+                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  f_mg  !<
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                         nys_mg(grid_level)-1:nyn_mg(grid_level)+1,             &
-                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  p_mg  !:
+                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  p_mg  !<
 
     l = grid_level
@@ -1144,4 +1144,9 @@
 
 
+!------------------------------------------------------------------------------!
+! Description:
+! ------------
+!> Gather subdomain data from all PEs.
+!------------------------------------------------------------------------------!
  SUBROUTINE mg_gather( f2, f2_sub )
 
@@ -1161,23 +1166,23 @@
     IMPLICIT NONE
 
-    INTEGER(iwp) ::  i       !:
-    INTEGER(iwp) ::  il      !:
-    INTEGER(iwp) ::  ir      !:
-    INTEGER(iwp) ::  j       !:
-    INTEGER(iwp) ::  jn      !:
-    INTEGER(iwp) ::  js      !:
-    INTEGER(iwp) ::  k       !:
-    INTEGER(iwp) ::  nwords  !:
+    INTEGER(iwp) ::  i       !<
+    INTEGER(iwp) ::  il      !<
+    INTEGER(iwp) ::  ir      !<
+    INTEGER(iwp) ::  j       !<
+    INTEGER(iwp) ::  jn      !<
+    INTEGER(iwp) ::  js      !<
+    INTEGER(iwp) ::  k       !<
+    INTEGER(iwp) ::  nwords  !<
 
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                     nys_mg(grid_level)-1:nyn_mg(grid_level)+1,                 &
-                    nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  f2    !:
+                    nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  f2    !<
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                     nys_mg(grid_level)-1:nyn_mg(grid_level)+1,                 &
-                    nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  f2_l  !:
+                    nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) ::  f2_l  !<
 
     REAL(wp), DIMENSION(nzb:mg_loc_ind(5,myid)+1,                              &
                         mg_loc_ind(3,myid)-1:mg_loc_ind(4,myid)+1,             &
-                        mg_loc_ind(1,myid)-1:mg_loc_ind(2,myid)+1) ::  f2_sub  !:
+                        mg_loc_ind(1,myid)-1:mg_loc_ind(2,myid)+1) ::  f2_sub  !<
 
 
@@ -1223,8 +1228,11 @@
 
 
+!------------------------------------------------------------------------------!
+! Description:
+! ------------
+!> @todo It may be possible to improve the speed of this routine by using
+!>       non-blocking communication
+!------------------------------------------------------------------------------!
  SUBROUTINE mg_scatter( p2, p2_sub )
-!
-!-- TODO: It may be possible to improve the speed of this routine by using
-!-- non-blocking communication
 
     USE control_parameters,                                                    &
@@ -1243,13 +1251,13 @@
     IMPLICIT NONE
 
-    INTEGER(iwp) ::  nwords  !:
+    INTEGER(iwp) ::  nwords  !<
 
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level-1)+1,                            &
                         nys_mg(grid_level-1)-1:nyn_mg(grid_level-1)+1,         &
-                        nxl_mg(grid_level-1)-1:nxr_mg(grid_level-1)+1) ::  p2  !:
+                        nxl_mg(grid_level-1)-1:nxr_mg(grid_level-1)+1) ::  p2  !<
 
     REAL(wp), DIMENSION(nzb:mg_loc_ind(5,myid)+1,                              &
                         mg_loc_ind(3,myid)-1:mg_loc_ind(4,myid)+1,             &
-                        mg_loc_ind(1,myid)-1:mg_loc_ind(2,myid)+1) ::  p2_sub  !:
+                        mg_loc_ind(1,myid)-1:mg_loc_ind(2,myid)+1) ::  p2_sub  !<
 
 !
@@ -1269,17 +1277,15 @@
 
 
-
- RECURSIVE SUBROUTINE next_mg_level( f_mg, p_mg, p3, r )
-
 !------------------------------------------------------------------------------!
 ! Description:
 ! ------------
-! This is where the multigrid technique takes place. V- and W- Cycle are
-! implemented and steered by the parameter "gamma". Parameter "nue" determines
-! the convergence of the multigrid iterative solution. There are nue times
-! RB-GS iterations. It should be set to "1" or "2", considering the time effort
-! one would like to invest. Last choice shows a very good converging factor,
-! but leads to an increase in computing time.
+!> This is where the multigrid technique takes place. V- and W- Cycle are
+!> implemented and steered by the parameter "gamma". Parameter "nue" determines
+!> the convergence of the multigrid iterative solution. There are nue times
+!> RB-GS iterations. It should be set to "1" or "2", considering the time effort
+!> one would like to invest. Last choice shows a very good converging factor,
+!> but leads to an increase in computing time.
 !------------------------------------------------------------------------------!
+ RECURSIVE SUBROUTINE next_mg_level( f_mg, p_mg, p3, r )
 
     USE control_parameters,                                                    &
@@ -1301,35 +1307,35 @@
     IMPLICIT NONE
 
-    INTEGER(iwp) ::  i            !:
-    INTEGER(iwp) ::  j            !:
-    INTEGER(iwp) ::  k            !:
-    INTEGER(iwp) ::  nxl_mg_save  !:
-    INTEGER(iwp) ::  nxr_mg_save  !:
-    INTEGER(iwp) ::  nyn_mg_save  !:
-    INTEGER(iwp) ::  nys_mg_save  !:
-    INTEGER(iwp) ::  nzt_mg_save  !:
+    INTEGER(iwp) ::  i            !<
+    INTEGER(iwp) ::  j            !<
+    INTEGER(iwp) ::  k            !<
+    INTEGER(iwp) ::  nxl_mg_save  !<
+    INTEGER(iwp) ::  nxr_mg_save  !<
+    INTEGER(iwp) ::  nyn_mg_save  !<
+    INTEGER(iwp) ::  nys_mg_save  !<
+    INTEGER(iwp) ::  nzt_mg_save  !<
 
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                         nys_mg(grid_level)-1:nyn_mg(grid_level)+1,             &
-                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) :: f_mg  !:
+                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) :: f_mg  !<
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                         nys_mg(grid_level)-1:nyn_mg(grid_level)+1,             &
-                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) :: p_mg  !:
+                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) :: p_mg  !<
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                         nys_mg(grid_level)-1:nyn_mg(grid_level)+1,             &
-                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) :: p3    !:
+                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) :: p3    !<
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level)+1,                              &
                         nys_mg(grid_level)-1:nyn_mg(grid_level)+1,             &
-                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) :: r     !:
+                        nxl_mg(grid_level)-1:nxr_mg(grid_level)+1) :: r     !<
 
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level-1)+1,                            &
                         nys_mg(grid_level-1)-1:nyn_mg(grid_level-1)+1,         &
-                        nxl_mg(grid_level-1)-1:nxr_mg(grid_level-1)+1) ::  f2  !:
+                        nxl_mg(grid_level-1)-1:nxr_mg(grid_level-1)+1) ::  f2  !<
     REAL(wp), DIMENSION(nzb:nzt_mg(grid_level-1)+1,                            &
                         nys_mg(grid_level-1)-1:nyn_mg(grid_level-1)+1,         &
-                        nxl_mg(grid_level-1)-1:nxr_mg(grid_level-1)+1) ::  p2  !:
-
-    REAL(wp), DIMENSION(:,:,:), ALLOCATABLE ::  f2_sub  !:
-    REAL(wp), DIMENSION(:,:,:), ALLOCATABLE ::  p2_sub  !:
+                        nxl_mg(grid_level-1)-1:nxr_mg(grid_level-1)+1) ::  p2  !<
+
+    REAL(wp), DIMENSION(:,:,:), ALLOCATABLE ::  f2_sub  !<
+    REAL(wp), DIMENSION(:,:,:), ALLOCATABLE ::  p2_sub  !<
 
 !
