Index: palm/trunk/SOURCE/random_generator_parallel.f90
===================================================================
--- palm/trunk/SOURCE/random_generator_parallel.f90	(revision 1401)
+++ palm/trunk/SOURCE/random_generator_parallel.f90	(revision 1682)
@@ -1,4 +1,3 @@
-MODULE random_generator_parallel
-
+!> @file random_generator_parallel.f90
 !------------------------------------------------------------------------------!
 ! This file is part of PALM.
@@ -20,5 +19,5 @@
 ! Current revisions:
 ! -----------------
-! 
+! Code annotations made doxygen readable 
 ! 
 ! Former revisions:
@@ -32,17 +31,19 @@
 ! Description:
 ! ------------
-! This module contains and supports the random number generating routine ran_parallel.
-! ran_parallel returns a uniform random deviate between 0.0 and 1.0 
-! (exclusive of the end point values).
-! Additionally it provides the generator with five integer for use as initial state space.
-! The first tree integers (iran, jran, kran) are maintained as non negative values, 
-! while the last two (mran, nran) have 32-bit nonzero values. 
-! Also provided by this module is support for initializing or reinitializing 
-! the state space to a desired standard sequence number, hashing the initial 
-! values to random values, and allocating and deallocating the internal workspace
-! Random number generator, produces numbers equally distributed in interval
-!
-! This routine is taken from the "numerical recipies vol. 2"
-!------------------------------------------------------------------------------!
+!> This module contains and supports the random number generating routine ran_parallel.
+!> ran_parallel returns a uniform random deviate between 0.0 and 1.0 
+!> (exclusive of the end point values).
+!> Additionally it provides the generator with five integer for use as initial state space.
+!> The first tree integers (iran, jran, kran) are maintained as non negative values, 
+!> while the last two (mran, nran) have 32-bit nonzero values. 
+!> Also provided by this module is support for initializing or reinitializing 
+!> the state space to a desired standard sequence number, hashing the initial 
+!> values to random values, and allocating and deallocating the internal workspace
+!> Random number generator, produces numbers equally distributed in interval
+!>
+!> This routine is taken from the "numerical recipies vol. 2"
+!------------------------------------------------------------------------------!
+MODULE random_generator_parallel
+ 
 
    USE kinds
@@ -54,30 +55,30 @@
           id_random_array, seq_random_array
    
-   INTEGER(isp), SAVE :: lenran=0             !: 
-   INTEGER(isp), SAVE :: seq=0                !: 
-   INTEGER(isp), SAVE :: iran0                !: 
-   INTEGER(isp), SAVE :: jran0                !: 
-   INTEGER(isp), SAVE :: kran0                !: 
-   INTEGER(isp), SAVE :: mran0                !: 
-   INTEGER(isp), SAVE :: nran0                !: 
-   INTEGER(isp), SAVE :: rans                 !: 
-   
-   INTEGER(isp), DIMENSION(:, :), POINTER, SAVE :: ranseeds   !: 
-   
-   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: iran   !: 
-   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: jran   !: 
-   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: kran   !: 
-   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: mran   !: 
-   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: nran   !: 
-   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: ranv   !: 
+   INTEGER(isp), SAVE :: lenran=0             !< 
+   INTEGER(isp), SAVE :: seq=0                !< 
+   INTEGER(isp), SAVE :: iran0                !< 
+   INTEGER(isp), SAVE :: jran0                !< 
+   INTEGER(isp), SAVE :: kran0                !< 
+   INTEGER(isp), SAVE :: mran0                !< 
+   INTEGER(isp), SAVE :: nran0                !< 
+   INTEGER(isp), SAVE :: rans                 !< 
+   
+   INTEGER(isp), DIMENSION(:, :), POINTER, SAVE :: ranseeds   !< 
+   
+   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: iran   !< 
+   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: jran   !< 
+   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: kran   !< 
+   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: mran   !< 
+   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: nran   !< 
+   INTEGER(isp), DIMENSION(:), POINTER, SAVE :: ranv   !< 
    
    
     
-   INTEGER(isp), DIMENSION(:,:), ALLOCATABLE   ::  id_random_array    !: 
-   INTEGER(isp), DIMENSION(:,:,:), ALLOCATABLE ::  seq_random_array   !: 
-   
-   REAL(wp), SAVE :: amm   !: 
-   
-   REAL(wp) :: random_dummy=0.0   !: 
+   INTEGER(isp), DIMENSION(:,:), ALLOCATABLE   ::  id_random_array    !< 
+   INTEGER(isp), DIMENSION(:,:,:), ALLOCATABLE ::  seq_random_array   !< 
+   
+   REAL(wp), SAVE :: amm   !< 
+   
+   REAL(wp) :: random_dummy=0.0   !< 
    
    INTERFACE random_number_parallel
@@ -106,10 +107,10 @@
 ! Description:
 ! ------------
-! Lagged Fibonacci generator combined with a Marsaglia shiftsequence. 
-! Returns as harvest a uniform random deviate between 0.0 and 1.0 (exclusive of the end point values). 
-! This generator has the same calling and initialization conventions as Fortran 90's random_number routine. 
-! Use random_seed_parallel to initialize or reinitialize to a particular sequence. 
-! The period of this generator is about 2.0 x 10^28, and it fully vectorizes.
-! Validity of the integer model assumed by this generator is tested at initialization.
+!> Lagged Fibonacci generator combined with a Marsaglia shiftsequence. 
+!> Returns as harvest a uniform random deviate between 0.0 and 1.0 (exclusive of the end point values). 
+!> This generator has the same calling and initialization conventions as Fortran 90's random_number routine. 
+!> Use random_seed_parallel to initialize or reinitialize to a particular sequence. 
+!> The period of this generator is about 2.0 x 10^28, and it fully vectorizes.
+!> Validity of the integer model assumed by this generator is tested at initialization.
 !------------------------------------------------------------------------------!
    SUBROUTINE ran0_s(harvest)
@@ -119,5 +120,5 @@
       IMPLICIT NONE
       
-      REAL(wp), INTENT(OUT) :: harvest   !: 
+      REAL(wp), INTENT(OUT) :: harvest   !< 
       
       IF  (lenran < 1) CALL ran_init(1)  !- Initialization routine in ran_state.
@@ -145,7 +146,7 @@
 ! Description:
 ! ------------
-! Initialize or reinitialize the random generator state space to vectors of size length. 
-! The saved variable seq is hashed (via calls to the module routine ran_hash) 
-! to create unique starting seeds, different for each vector component.
+!> Initialize or reinitialize the random generator state space to vectors of size length. 
+!> The saved variable seq is hashed (via calls to the module routine ran_hash) 
+!> to create unique starting seeds, different for each vector component.
 !------------------------------------------------------------------------------!
    SUBROUTINE ran_init( length )
@@ -155,13 +156,13 @@
       IMPLICIT NONE
       
-      INTEGER(isp), INTENT(IN) ::  length   !: 
-   
-      INTEGER(isp), PARAMETER:: hg=huge(1_isp)   !: 
-      INTEGER(isp), PARAMETER:: hgm=-hg          !: 
-      INTEGER(isp), PARAMETER:: hgng=hgm-1       !: 
-      
-      INTEGER(isp) ::  new   !: 
-      INTEGER(isp) ::  j     !: 
-      INTEGER(isp) ::  hgt   !: 
+      INTEGER(isp), INTENT(IN) ::  length   !< 
+   
+      INTEGER(isp), PARAMETER:: hg=huge(1_isp)   !< 
+      INTEGER(isp), PARAMETER:: hgm=-hg          !< 
+      INTEGER(isp), PARAMETER:: hgng=hgm-1       !< 
+      
+      INTEGER(isp) ::  new   !< 
+      INTEGER(isp) ::  j     !< 
+      INTEGER(isp) ::  hgt   !< 
       
       IF ( length < lenran ) RETURN !- Simply return if enough space is already allocated.
@@ -244,5 +245,5 @@
 ! Description:
 ! ------------
-! User interface to release the workspace used by the random number routines.
+!> User interface to release the workspace used by the random number routines.
 !------------------------------------------------------------------------------!
    SUBROUTINE ran_deallocate
@@ -261,8 +262,8 @@
 ! Description:
 ! ------------
-! User interface for seeding the random number routines. 
-! Syntax is exactly like Fortran 90's random_seed routine, 
-! with one additional argument keyword: random_sequence, set to any integer 
-! value, causes an immediate new initialization, seeded by that integer.
+!> User interface for seeding the random number routines. 
+!> Syntax is exactly like Fortran 90's random_seed routine, 
+!> with one additional argument keyword: random_sequence, set to any integer 
+!> value, causes an immediate new initialization, seeded by that integer.
 !------------------------------------------------------------------------------!
    SUBROUTINE random_seed_parallel( random_sequence, state_size, put, get )
@@ -270,9 +271,9 @@
       IMPLICIT NONE
       
-      INTEGER(isp), OPTIONAL, INTENT(IN)  ::  random_sequence   !: 
-      INTEGER(isp), OPTIONAL, INTENT(OUT) ::  state_size        !: 
-      
-      INTEGER(isp), DIMENSION(:), OPTIONAL, INTENT(IN)  ::  put   !: 
-      INTEGER(isp), DIMENSION(:), OPTIONAL, INTENT(OUT) ::  get   !: 
+      INTEGER(isp), OPTIONAL, INTENT(IN)  ::  random_sequence   !< 
+      INTEGER(isp), OPTIONAL, INTENT(OUT) ::  state_size        !< 
+      
+      INTEGER(isp), DIMENSION(:), OPTIONAL, INTENT(IN)  ::  put   !< 
+      INTEGER(isp), DIMENSION(:), OPTIONAL, INTENT(OUT) ::  get   !< 
       
       IF  ( present(state_size) ) THEN
@@ -316,6 +317,6 @@
 ! Description:
 ! ------------
-! DES-like hashing of two 32-bit integers, using shifts, 
-! xor's, and adds to make the internal nonlinear function.
+!> DES-like hashing of two 32-bit integers, using shifts, 
+!> xor's, and adds to make the internal nonlinear function.
 !------------------------------------------------------------------------------!
    SUBROUTINE ran_hash_v( il, ir )
@@ -323,10 +324,10 @@
       IMPLICIT NONE
       
-      INTEGER(isp), DIMENSION(:), INTENT(INOUT) ::  il   !: 
-      INTEGER(isp), DIMENSION(:), INTENT(INOUT) ::  ir   !: 
-      
-      INTEGER(isp), DIMENSION(size(il)) ::  is   !: 
-      
-      INTEGER(isp) :: j   !: 
+      INTEGER(isp), DIMENSION(:), INTENT(INOUT) ::  il   !< 
+      INTEGER(isp), DIMENSION(:), INTENT(INOUT) ::  ir   !< 
+      
+      INTEGER(isp), DIMENSION(size(il)) ::  is   !< 
+      
+      INTEGER(isp) :: j   !< 
       
       DO j=1,4
@@ -345,10 +346,10 @@
 ! Description:
 ! ------------
-! User interface to process error-messages 
-! produced by the random_number_parallel module
+!> User interface to process error-messages 
+!> produced by the random_number_parallel module
 !------------------------------------------------------------------------------!
    SUBROUTINE ran_error(string)
    
-      CHARACTER(LEN=*), INTENT(IN) ::  string   !: 
+      CHARACTER(LEN=*), INTENT(IN) ::  string   !< 
       
       write (*,*) 'Error in module random_number_parallel: ',string
@@ -361,15 +362,15 @@
 ! Description:
 ! ------------
-! Reallocates the generators state space "ranseeds" to vectors of size length. 
+!> Reallocates the generators state space "ranseeds" to vectors of size length. 
 !------------------------------------------------------------------------------!
    FUNCTION reallocate_iv( p, n )
    
-      INTEGER(isp), DIMENSION(:), POINTER ::  p               !: 
-      INTEGER(isp), DIMENSION(:), POINTER ::  reallocate_iv   !: 
-      
-      INTEGER(isp), INTENT(IN) ::  n   !: 
-      
-      INTEGER(isp) ::  nold   !: 
-      INTEGER(isp) ::  ierr   !: 
+      INTEGER(isp), DIMENSION(:), POINTER ::  p               !< 
+      INTEGER(isp), DIMENSION(:), POINTER ::  reallocate_iv   !< 
+      
+      INTEGER(isp), INTENT(IN) ::  n   !< 
+      
+      INTEGER(isp) ::  nold   !< 
+      INTEGER(isp) ::  ierr   !< 
       
       ALLOCATE(reallocate_iv(n),stat=ierr)
@@ -390,13 +391,13 @@
    FUNCTION reallocate_im( p, n, m )
    
-      INTEGER(isp), DIMENSION(:,:), POINTER ::  p               !: 
-      INTEGER(isp), DIMENSION(:,:), POINTER ::  reallocate_im   !: 
-      
-      INTEGER(isp), INTENT(IN) ::  m   !: 
-      INTEGER(isp), INTENT(IN) ::  n   !: 
-      
-      INTEGER(isp) ::  mold   !: 
-      INTEGER(isp) ::  nold   !: 
-      INTEGER(isp) ::  ierr   !: 
+      INTEGER(isp), DIMENSION(:,:), POINTER ::  p               !< 
+      INTEGER(isp), DIMENSION(:,:), POINTER ::  reallocate_im   !< 
+      
+      INTEGER(isp), INTENT(IN) ::  m   !< 
+      INTEGER(isp), INTENT(IN) ::  n   !< 
+      
+      INTEGER(isp) ::  mold   !< 
+      INTEGER(isp) ::  nold   !< 
+      INTEGER(isp) ::  ierr   !< 
       
       ALLOCATE(reallocate_im(n,m),stat=ierr)
@@ -420,20 +421,20 @@
 ! Description:
 ! ------------
-! Reallocates the generators state space "ranseeds" to vectors of size length. 
+!> Reallocates the generators state space "ranseeds" to vectors of size length. 
 !------------------------------------------------------------------------------!
    FUNCTION arth_i(first,increment,n)
    
-      INTEGER(isp), INTENT(IN) ::  first       !: 
-      INTEGER(isp), INTENT(IN) ::  increment   !: 
-      INTEGER(isp), INTENT(IN) ::  n           !: 
-      
-      INTEGER(isp), DIMENSION(n) ::  arth_i    !: 
-      
-      INTEGER(isp) ::  k      !: 
-      INTEGER(isp) ::  k2     !: 
-      INTEGER(isp) ::  temp   !: 
-      
-      INTEGER(isp), PARAMETER ::  npar_arth=16   !: 
-      INTEGER(isp), PARAMETER ::  npar2_arth=8   !: 
+      INTEGER(isp), INTENT(IN) ::  first       !< 
+      INTEGER(isp), INTENT(IN) ::  increment   !< 
+      INTEGER(isp), INTENT(IN) ::  n           !< 
+      
+      INTEGER(isp), DIMENSION(n) ::  arth_i    !< 
+      
+      INTEGER(isp) ::  k      !< 
+      INTEGER(isp) ::  k2     !< 
+      INTEGER(isp) ::  temp   !< 
+      
+      INTEGER(isp), PARAMETER ::  npar_arth=16   !< 
+      INTEGER(isp), PARAMETER ::  npar2_arth=8   !< 
       
       IF (n > 0) arth_i(1) = first
