Edits for Doxygen

Author: garrelt

clocks.f90

@@ -1,30 +1,59 @@
+!>
+!! \brief This module contains variables and routines for dealing with 
+!!   cpu and wall clocks
+!!
+!! This module uses calls to the Fortran 2003 internal routines cpu_time
+!! and system_clock. To get the time passed between two events, one has
+!! to call these twice, once at the start and once at the end. 
+!! To avoid overflowing the variable (which can happen for codes that run
+!! for many hours or days), this module provides "update" routines that
+!! update hour and minute counters. These should be called at regular
+!! intervals. The module also comes with its own reporting routines.
+!!
+!! General module
+!!
+!! Dependencies:
+!!   - file_admin module (for the unit of the log file where to write the report)
+!!   - my_mpi (for the value of rank, the MPI id of the current processor, reporting is only done for the rank 0 processor)
+!!
+!! Author: Garrelt Mellema
+!!
+!! Date: 2010-03-08
+!!
+!! Version: 1.0
+!!
+!<
+
 module clocks
 
-  use precision, only: dp
   use file_admin, only: logf
   use my_mpi, only: rank
 
   implicit none
 
   ! Start and end time for CPU report
-  real :: cputime1 !< Start time for CPU report
-  real :: cputime2 !< End time for CPU report
-  real(kind=dp) :: cpu_seconds=0.0
-  integer :: cpu_hours=0
-  integer :: cpu_minutes=0
+  real :: cputime1 !< Start time for call to CPU routine
+  real :: cputime2 !< End time for call to CPU routine
+
+  integer :: cpu_hours=0 !< accumulates the CPU hours
+  integer :: cpu_minutes=0 !< accumulates the CPU minutes
+  real :: cpu_seconds=0.0 !< accumulates the CPU seconds
 
   ! Wall clock time variables
-  integer :: cntr1 !< Start time wall clock
-  integer :: cntr2 !< End time wall clock
+  integer :: cntr1 !< Start time for call to wall clock routine
+  integer :: cntr2 !< End time for call to wall clock routine
+
   integer :: countspersec !< counts per second (for wall clock time)
-  real(kind=dp) :: clock_seconds=0.0
-  integer :: clock_hours=0
-  integer :: clock_minutes=0
+
+  integer :: clock_hours=0 !< accumulates the wall clock hours
+  integer :: clock_minutes=0 !< accumulates the wall clock minutes
+  real :: clock_seconds=0.0 !< accumulates the wall clock seconds
 
 contains
 
   !=======================================================================
 
+  !> Sets up all the clocks (initialization routine)
   subroutine setup_clocks
 
     call setup_cpuclock()
@@ -34,6 +63,7 @@ end subroutine setup_clocks
 
   !=======================================================================
 
+  !> Sets up cpu clock (initialization routine)
   subroutine setup_cpuclock
 
     ! Initialize cpu timer
@@ -43,6 +73,7 @@ end subroutine setup_cpuclock
 
   !=======================================================================
 
+  !> Sets up wall clock (initialization routine)
   subroutine setup_wallclock
 
     ! Initialize wall cock timer
@@ -52,6 +83,7 @@ end subroutine setup_wallclock
 
   !=======================================================================
 
+  !> Updates all the clocks
   subroutine update_clocks
 
     call update_cpuclock
@@ -61,6 +93,7 @@ end subroutine update_clocks
 
   !=======================================================================
 
+  !> Updates CPU clock
   subroutine update_cpuclock
 
     ! Find out intermediate CPU time (to avoid overflowing the counter)
@@ -76,6 +109,7 @@ end subroutine update_cpuclock
 
   !=======================================================================
 
+  !> Updates wall clock
   subroutine update_wallclock
 
     call system_clock(cntr2,countspersec)
@@ -90,6 +124,7 @@ end subroutine update_wallclock
 
   !=======================================================================
 
+  !> Reports all the clocks
   subroutine report_clocks
 
     call report_cpuclock
@@ -99,6 +134,7 @@ end subroutine report_clocks
 
   !=======================================================================
 
+  !> Reports CPU clock to log file (unit logf)
   subroutine report_cpuclock
 
     call update_cpuclock ()
@@ -111,6 +147,7 @@ end subroutine report_cpuclock
 
   !=======================================================================
 
+  !> Reports wall clock to log file (unit logf)
   subroutine report_wallclock
 
     call update_wallclock ()

cosmological_evolution.f90

@@ -8,8 +8,16 @@
 !! \b Date: 04-Mar-2006
 !!
 !! The density and lengths and volumes evolve due to the expansion
-!! of the Universe
+!! of the Universe. The cosmo_evol routines evolves the geometrical
+!! variables (r, dr, vol) and the material density variables (ndens)
+!! according to the current redshift (zfactor from the cosmology module).
 !!
+!! \b Programming \b note: this is probably a separate module from the cosmology
+!! module because of
+!! dependency problems. For the cosmo_evol routines, the grid and material
+!! variables have to be available, but for those the cosmology module has
+!! to be available. As cosmo_evol really belongs within the cosmology module
+!! a different solution would be desirable (GM, 20100308).
 
 module cosmological_evolution
 
@@ -19,7 +27,7 @@ module cosmological_evolution
   ! - cosmo_evol: cosmological evolution of space, density
 
   use precision, only: dp
-  use cosmology
+  use cosmology, only: zfactor
   use grid, only: r,dr,vol
   use material, only: ndens
 

cosmology.F90

@@ -1,26 +1,31 @@
 !>
 !! \brief This module contains data and routines for cosmological problems
 !!
-!! Module for Capreole / C2-Ray (f90)
+!! Module for Capreole / C2-Ray (F90)
 !!
 !! \b Author: Garrelt Mellema
 !!
-!! \b Date: 
+!! \b Date: 2010-03-08 (but older than that)
 !!
-!! This module keeps track of the current redshift
+!! This module initializes the cosmology and contains functions for changing
+!! redshift to time and vice versa. It also contains cosmological cooling
+!! routines. Note that it does not evolve the proper lengths, volumes and
+!! densities. This is done in the cosmological_evolution module.
+!!
+!! List of routines:
+!! - cosmology_init: initializes cosmological time and sets lengths
+!!            and volumes from comoving to proper scaling.
+!! - time2zred: convert time to redshift
+!! - zred2time: convert redshift to time
+!! - cosmo_cool: cosmological adiabatic cooling rate
+!! - compton_cool: Compton cooling wrt the CMB.
+!!
+!! This module keeps track of the current redshift (zred) and the flag
+!! for cosmological calculations (cosmological).
 !!
 
 module cosmology
 
-  ! This module contains routines having to do with the cosmological 
-  ! evolution
-  
-  ! - cosmology_init: initializes cosmological time and sets lengths
-  !            and volumes from comoving to proper scaling.
-  ! - time2zred: convert time to redshift
-  ! - zred2time: convert redshift to time
-  ! - cosmo_cool: cosmological adiabatic cooling rate
-  ! - compton_cool: Compton cooling wrt the CMB.
 
   use precision, only: dp
   use my_mpi
@@ -51,7 +56,7 @@ subroutine cosmology_init (cosmo_switch)
 
     use astroconstants, only: Mpc
 
-    logical, intent(in) :: cosmo_switch
+    logical, intent(in) :: cosmo_switch !< cosmological problem or not?
 
     real(kind=dp) :: zred0
 
@@ -83,7 +88,11 @@ subroutine cosmology_init (cosmo_switch)
 
        ! Initialize redshift
        zred_t0=zred0 ! keep initial redshift
-       zred=0.0 ! needs to be zero, so comoving will be changed to proper
+       ! zred is the master redshift variable, but 
+       ! needs to be zero so that grid and material variables will be
+       ! initialized as comoving (z=0) and then changed to proper 
+       ! (z=zred_t0).
+       zred=0.0 
 
     endif
 

radiation.F90

@@ -12,9 +12,22 @@
 !!
 !! \b Author: Garrelt Mellema
 !!
-!! \b Date:
+!! \b Date: 2010-Mar-08 (but older)
 !!
 !! \b Version: 1D version similar to the 3D version.
+!!
+!! <b>Programming note:</b> This version for the 1D code also sets and
+!! contains the source properties. In the 3Dm version there is a separate
+!! sourceprops module for that. It would be nice to be consistent and also
+!! have a source properties module for the 1D version. However, for the 1D
+!! version the effective temperature is a real input variable and the
+!! photo-ionization rates cannot be calculated before the this variable is
+!! set. This means that sourceprops would have to be called before rad_ini
+!! (unlike in the 3Dm version where it has to be called after). Also, both
+!! sourceprops and radiation would use the romberg integrator, so it should
+!! be clear who initializes it (unless the romberg module checks for this
+!! itself).
+!!
 
 module radiation