Standardize Doxygen: remove obvious @param, clean verbose headers, consistent style

Author: sbryngelson

src/common/include/1dHardcodedIC.fpp

@@ -13,21 +13,21 @@
         ! magnetic field
         q_prim_vf(B_idx%end - 1)%sf(i, 0, 0) = 0.1_wp*sin(2._wp*pi*x_cc(i))
         q_prim_vf(B_idx%end)%sf(i, 0, 0) = 0.1_wp*cos(2._wp*pi*x_cc(i))
-    case (170)
+    case (170)  ! 1D profile from external data (e.g. Cantera, SDtoolbox)
         ! This hardcoded case can be used to start a simulation with initial conditions given from a known 1D profile (e.g. Cantera,
         ! SDtoolbox)
         @: HardcodedReadValues()
-    case (180)
+    case (180)  ! Shu-Osher problem
         ! This is patch is hard-coded for test suite optimization used in the 1D_shuoser cases: "patch_icpp(2)%alpha_rho(1)": "1 +
         ! 0.2*sin(5*x)"
         if (patch_id == 2) then
             q_prim_vf(contxb + 0)%sf(i, 0, 0) = 1 + 0.2*sin(5*x_cc(i))
         end if
-    case (181)
+    case (181)  ! Titarev-Torro problem
         ! This is patch is hard-coded for test suite optimization used in the 1D_titarevtorro cases: "patch_icpp(2)%alpha_rho(1)":
         ! "1 + 0.1*sin(20*x*pi)"
         q_prim_vf(contxb + 0)%sf(i, 0, 0) = 1 + 0.1*sin(20*x_cc(i)*pi)
-    case (182)
+    case (182)  ! Multi-component diffusion
         ! This patch is a hard-coded for test suite optimization (multiple component diffusion)
         x_mid_diffu = 0.05_wp/2.0_wp
         width_sq = (2.5_wp*10.0_wp**(-3.0_wp))**2

src/common/include/2dHardcodedIC.fpp

@@ -18,7 +18,7 @@
 
 #:def Hardcoded2D()
     select case (patch_icpp(patch_id)%hcid)  ! 2D_hardcoded_ic example case
-    case (200)
+    case (200)  ! Two-fluid cubic interface
         if (y_cc(j) <= (-x_cc(i)**3 + 1)**(1._wp/3._wp)) then
             ! Volume Fractions
             q_prim_vf(advxb)%sf(i, j, 0) = eps
@@ -263,10 +263,10 @@
             q_prim_vf(B_idx%beg + 1)%sf(i, j, 0) = (5._wp/sqrt(4._wp*pi))*sinA + (5._wp/sqrt(4._wp*pi))*cosA
         end if
         ! v^z and B^z remain zero by default
-    case (270)
+    case (270)  ! 2D extrusion of 1D profile from external data
         ! This hardcoded case extrudes a 1D profile to initialize a 2D simulation domain
         @: HardcodedReadValues()
-    case (280)
+    case (280)  ! Isentropic vortex
         ! This is patch is hard-coded for test suite optimization used in the 2D_isentropicvortex case: This analytic patch uses
         ! geometry 2
         if (patch_id == 1) then
@@ -283,7 +283,7 @@
                       & 0) = 0.0 - (x_cc(i) - patch_icpp(1)%x_centroid)*(5.0/(2.0*pi))*exp(1.0*(1.0 - (x_cc(i) - patch_icpp(1) &
                       & %x_centroid)**2.0 - (y_cc(j) - patch_icpp(1)%y_centroid)**2.0))
         end if
-    case (281)
+    case (281)  ! Acoustic pulse
         ! This is patch is hard-coded for test suite optimization used in the 2D_acoustic_pulse case: This analytic patch uses
         ! geometry 2
         if (patch_id == 2) then
@@ -292,7 +292,7 @@
             q_prim_vf(contxb + 0)%sf(i, j, &
                       & 0) = 1*(1 - 0.5*(1.4 - 1)*(0.4)**2*exp(0.5*(1 - sqrt(x_cc(i)**2 + y_cc(j)**2))))**(1/(1.4 - 1))
         end if
-    case (282)
+    case (282)  ! Zero-circulation vortex
         ! This is patch is hard-coded for test suite optimization used in the 2D_zero_circ_vortex case: This analytic patch uses
         ! geometry 2
         if (patch_id == 2) then

src/common/include/3dHardcodedIC.fpp

@@ -165,10 +165,10 @@
         end if
 
         q_prim_vf(E_idx)%sf(i, j, k) = p_th*rcut*xcut + p_am
-    case (370)
+    case (370)  ! 3D extrusion of 2D profile from external data
         ! This hardcoded case extrudes a 2D profile to initialize a 3D simulation domain
         @: HardcodedReadValues()
-    case (380)
+    case (380)  ! Taylor-Green vortex
         ! This is patch is hard-coded for test suite optimization used in the 3D_TaylorGreenVortex case: This analytic patch used
         ! geometry 9
         Mach = 0.1

src/common/include/ExtrusionHardcodedIC.fpp

@@ -1,4 +1,4 @@
-!> @brief Allocate memory and read initial condition data for IC extrusion.
+!> Allocate memory and read initial condition data for IC extrusion.
 !>
 !> @details
 !> This macro handles the complete initialization process for IC extrusion by:

src/common/include/macros.fpp

@@ -14,7 +14,7 @@
 
 ! Caution: This macro requires the use of a binding script to set CUDA_VISIBLE_DEVICES, such that we have one GPU device per MPI
 ! rank. That's because for both cudaMemAdvise (preferred location) and cudaMemPrefetchAsync we use location = device_id = 0. For an
-! example see misc/nvidia_uvm/bind.sh.
+! example see misc/nvidia_uvm/bind.sh. NVIDIA unified memory page placement hint
 #:def PREFER_GPU(*args)
 #ifdef MFC_SIMULATION
 #ifdef __NVCOMPILER_GPU_UNIFIED_MEM
@@ -55,6 +55,7 @@
 #endif
 #:enddef
 
+! Allocate and create GPU device memory
 #:def ALLOCATE(*args)
     @:LOG({'@:ALLOCATE(${re.sub(' +', ' ', ', '.join(args))}$)'})
     #:set allocated_variables = ', '.join(args)
@@ -74,13 +75,15 @@
     $:GPU_ENTER_DATA(create='[' + joined + ']')
 #:enddef ALLOCATE
 
+! Free GPU device memory and deallocate
 #:def DEALLOCATE(*args)
     @:LOG({'@:DEALLOCATE(${re.sub(' +', ' ', ', '.join(args))}$)'})
     #:set allocated_variables = ', '.join(args)
     $:GPU_EXIT_DATA(delete=('[' + allocated_variables + ']'))
     deallocate (${allocated_variables}$)
 #:enddef DEALLOCATE
 
+! Cray-specific GPU pointer setup for vector fields
 #:def ACC_SETUP_VFs(*args)
 #ifdef _CRAYFTN
     block
@@ -104,6 +107,7 @@
 #endif
 #:enddef
 
+! Cray-specific GPU pointer setup for scalar fields
 #:def ACC_SETUP_SFs(*args)
 #ifdef _CRAYFTN
     block
@@ -119,6 +123,7 @@
 #endif
 #:enddef
 
+! Cray-specific GPU pointer setup for acoustic source spatials
 #:def ACC_SETUP_source_spatials(*args)
 #ifdef _CRAYFTN
     block

src/common/m_boundary_common.fpp

@@ -39,7 +39,7 @@ module m_boundary_common
 
 contains
 
-    !> @brief Allocates and sets up boundary condition buffer arrays for all coordinate directions.
+    !> Allocate and set up boundary condition buffer arrays for all coordinate directions.
     impure subroutine s_initialize_boundary_common_module()
 
         integer :: i, j
@@ -70,8 +70,7 @@ contains
 
     end subroutine s_initialize_boundary_common_module
 
-    !> The purpose of this procedure is to populate the buffers of the primitive variables, depending on the selected boundary
-    !! conditions.
+    !> Populate the buffers of the primitive variables based on the selected boundary conditions.
     impure subroutine s_populate_variables_buffers(bc_type, q_prim_vf, pb_in, mv_in)
 
         type(scalar_field), dimension(sys_size), intent(inout)                                                   :: q_prim_vf
@@ -272,7 +271,7 @@ contains
 
     end subroutine s_populate_variables_buffers
 
-    !> @brief Fills ghost cells by copying the nearest boundary cell value along the specified direction.
+    !> Fill ghost cells by copying the nearest boundary cell value along the specified direction.
     subroutine s_ghost_cell_extrapolation(q_prim_vf, bc_dir, bc_loc, k, l)
 
         $:GPU_ROUTINE(function_name='s_ghost_cell_extrapolation', parallelism='[seq]', cray_inline=True)
@@ -327,8 +326,7 @@ contains
 
     end subroutine s_ghost_cell_extrapolation
 
-    !> @brief Applies reflective (symmetry) boundary conditions by mirroring primitive variables and flipping the normal velocity
-    !! component.
+    !> Apply reflective (symmetry) boundary conditions by mirroring primitive variables and flipping the normal velocity component.
     subroutine s_symmetry(q_prim_vf, bc_dir, bc_loc, k, l, pb_in, mv_in)
 
         $:GPU_ROUTINE(parallelism='[seq]')
@@ -551,7 +549,7 @@ contains
 
     end subroutine s_symmetry
 
-    !> @brief Applies periodic boundary conditions by copying values from the opposite domain boundary.
+    !> Apply periodic boundary conditions by copying values from the opposite domain boundary.
     subroutine s_periodic(q_prim_vf, bc_dir, bc_loc, k, l, pb_in, mv_in)
 
         $:GPU_ROUTINE(parallelism='[seq]')
@@ -673,8 +671,7 @@ contains
 
     end subroutine s_periodic
 
-    !> @brief Applies axis boundary conditions for cylindrical coordinates by reflecting values across the axis with azimuthal phase
-    !! shift.
+    !> Apply axis boundary conditions for cylindrical coordinates by reflecting values across the axis with azimuthal phase shift.
     subroutine s_axis(q_prim_vf, pb_in, mv_in, k, l)
 
         $:GPU_ROUTINE(parallelism='[seq]')
@@ -724,7 +721,7 @@ contains
 
     end subroutine s_axis
 
-    !> @brief Applies slip wall boundary conditions by extrapolating scalars and reflecting the wall-normal velocity component.
+    !> Apply slip wall boundary conditions by extrapolating scalars and reflecting the wall-normal velocity component.
     subroutine s_slip_wall(q_prim_vf, bc_dir, bc_loc, k, l)
 
         $:GPU_ROUTINE(function_name='s_slip_wall',parallelism='[seq]', cray_inline=True)
@@ -803,7 +800,7 @@ contains
 
     end subroutine s_slip_wall
 
-    !> @brief Applies no-slip wall boundary conditions by reflecting and negating all velocity components at the wall.
+    !> Apply no-slip wall boundary conditions by reflecting and negating all velocity components at the wall.
     subroutine s_no_slip_wall(q_prim_vf, bc_dir, bc_loc, k, l)
 
         $:GPU_ROUTINE(function_name='s_no_slip_wall',parallelism='[seq]', cray_inline=True)
@@ -907,7 +904,7 @@ contains
 
     end subroutine s_no_slip_wall
 
-    !> @brief Applies Dirichlet boundary conditions by prescribing ghost cell values from stored boundary buffers.
+    !> Apply Dirichlet boundary conditions by prescribing ghost cell values from stored boundary buffers.
     subroutine s_dirichlet(q_prim_vf, bc_dir, bc_loc, k, l)
 
         $:GPU_ROUTINE(function_name='s_dirichlet',parallelism='[seq]', cray_inline=True)
@@ -970,7 +967,7 @@ contains
 
     end subroutine s_dirichlet
 
-    !> @brief Extrapolates QBMM bubble pressure and mass-vapor variables into ghost cells by copying boundary values.
+    !> Extrapolate QBMM bubble pressure and mass-vapor variables into ghost cells by copying boundary values.
     subroutine s_qbmm_extrapolation(bc_dir, bc_loc, k, l, pb_in, mv_in)
 
         $:GPU_ROUTINE(parallelism='[seq]')
@@ -1043,7 +1040,7 @@ contains
 
     end subroutine s_qbmm_extrapolation
 
-    !> @brief Populates ghost cell buffers for the color function and its divergence used in capillary surface tension.
+    !> Populate ghost cell buffers for the color function and its divergence used in capillary surface tension.
     impure subroutine s_populate_capillary_buffers(c_divs, bc_type)
 
         type(scalar_field), dimension(num_dims + 1), intent(inout)  :: c_divs
@@ -1178,7 +1175,7 @@ contains
 
     end subroutine s_populate_capillary_buffers
 
-    !> @brief Applies periodic boundary conditions to the color function and its divergence fields.
+    !> Apply periodic boundary conditions to the color function and its divergence fields.
     subroutine s_color_function_periodic(c_divs, bc_dir, bc_loc, k, l)
 
         $:GPU_ROUTINE(function_name='s_color_function_periodic', parallelism='[seq]', cray_inline=True)
@@ -1233,7 +1230,7 @@ contains
 
     end subroutine s_color_function_periodic
 
-    !> @brief Applies reflective boundary conditions to the color function and its divergence fields.
+    !> Apply reflective boundary conditions to the color function and its divergence fields.
     subroutine s_color_function_reflective(c_divs, bc_dir, bc_loc, k, l)
 
         $:GPU_ROUTINE(function_name='s_color_function_reflective', parallelism='[seq]', cray_inline=True)
@@ -1312,7 +1309,7 @@ contains
 
     end subroutine s_color_function_reflective
 
-    !> @brief Extrapolates the color function and its divergence into ghost cells by copying boundary values.
+    !> Extrapolate the color function and its divergence into ghost cells by copying boundary values.
     subroutine s_color_function_ghost_cell_extrapolation(c_divs, bc_dir, bc_loc, k, l)
 
         $:GPU_ROUTINE(function_name='s_color_function_ghost_cell_extrapolation', parallelism='[seq]', cray_inline=True)
@@ -1367,7 +1364,7 @@ contains
 
     end subroutine s_color_function_ghost_cell_extrapolation
 
-    !> @brief Populates ghost cell buffers for the Jacobian scalar field used in the IGR elliptic solver.
+    !> Populate ghost cell buffers for the Jacobian scalar field used in the IGR elliptic solver.
     impure subroutine s_populate_F_igr_buffers(bc_type, jac_sf)
 
         type(integer_field), dimension(1:num_dims, 1:2), intent(in) :: bc_type
@@ -1534,7 +1531,7 @@ contains
 
     end subroutine s_populate_F_igr_buffers
 
-    !> @brief Creates MPI derived datatypes for boundary condition type arrays and buffer arrays used in parallel I/O.
+    !> Create MPI derived datatypes for boundary condition type arrays and buffer arrays used in parallel I/O.
     impure subroutine s_create_mpi_types(bc_type)
 
         type(integer_field), dimension(1:num_dims, 1:2), intent(in) :: bc_type
@@ -1569,7 +1566,7 @@ contains
 
     end subroutine s_create_mpi_types
 
-    !> @brief Writes boundary condition type and buffer data to serial (unformatted) restart files.
+    !> Write boundary condition type and buffer data to serial (unformatted) restart files.
     subroutine s_write_serial_boundary_condition_files(q_prim_vf, bc_type, step_dirpath, old_grid_in)
 
         type(scalar_field), dimension(sys_size), intent(in)         :: q_prim_vf
@@ -1608,7 +1605,7 @@ contains
 
     end subroutine s_write_serial_boundary_condition_files
 
-    !> @brief Writes boundary condition type and buffer data to per-rank parallel files using MPI I/O.
+    !> Write boundary condition type and buffer data to per-rank parallel files using MPI I/O.
     subroutine s_write_parallel_boundary_condition_files(q_prim_vf, bc_type)
 
         type(scalar_field), dimension(sys_size), intent(in)         :: q_prim_vf
@@ -1673,7 +1670,7 @@ contains
 
     end subroutine s_write_parallel_boundary_condition_files
 
-    !> @brief Reads boundary condition type and buffer data from serial (unformatted) restart files.
+    !> Read boundary condition type and buffer data from serial (unformatted) restart files.
     subroutine s_read_serial_boundary_condition_files(step_dirpath, bc_type)
 
         character(LEN=*), intent(in)                                   :: step_dirpath
@@ -1718,7 +1715,7 @@ contains
 
     end subroutine s_read_serial_boundary_condition_files
 
-    !> @brief Reads boundary condition type and buffer data from per-rank parallel files using MPI I/O.
+    !> Read boundary condition type and buffer data from per-rank parallel files using MPI I/O.
     subroutine s_read_parallel_boundary_condition_files(bc_type)
 
         type(integer_field), dimension(1:num_dims, 1:2), intent(inout) :: bc_type
@@ -1783,7 +1780,7 @@ contains
 
     end subroutine s_read_parallel_boundary_condition_files
 
-    !> @brief Packs primitive variable boundary slices into bc_buffers arrays for serialization.
+    !> Pack primitive variable boundary slices into bc_buffers arrays for serialization.
     subroutine s_pack_boundary_condition_buffers(q_prim_vf)
 
         type(scalar_field), dimension(sys_size), intent(in) :: q_prim_vf
@@ -1826,7 +1823,7 @@ contains
 
     end subroutine s_pack_boundary_condition_buffers
 
-    !> @brief Initializes the per-cell boundary condition type arrays with the global default BC values.
+    !> Initialize the per-cell boundary condition type arrays with the global default BC values.
     subroutine s_assign_default_bc_type(bc_type)
 
         type(integer_field), dimension(1:num_dims, 1:2), intent(in) :: bc_type
@@ -1852,8 +1849,8 @@ contains
 
     end subroutine s_assign_default_bc_type
 
-    !> The purpose of this subroutine is to populate the buffers of the grid variables, which are constituted of the cell- boundary
-    !! locations and cell-width distributions, based on the boundary conditions.
+    !> Populate the buffers of the grid variables, which are constituted of the cell-boundary locations and cell-width
+    !! distributions, based on the boundary conditions.
     subroutine s_populate_grid_variables_buffers
 
         integer :: i
@@ -2037,7 +2034,7 @@ contains
 
     end subroutine s_populate_grid_variables_buffers
 
-    !> @brief Deallocates boundary condition buffer arrays allocated during module initialization.
+    !> Deallocate boundary condition buffer arrays allocated during module initialization.
     subroutine s_finalize_boundary_common_module()
 
         if (bc_io) then

src/common/m_checker_common.fpp

@@ -32,7 +32,7 @@ contains
     end subroutine s_check_inputs_common
 
 #ifndef MFC_SIMULATION
-    !> @brief Verifies that the total number of grid cells meets the minimum required by the number of dimensions and MPI ranks.
+    !> Verify that the total number of grid cells meets the minimum required by the number of dimensions and MPI ranks.
     impure subroutine s_check_total_cells
 
         character(len=18) :: numStr  !< for int to string conversion
@@ -48,7 +48,7 @@ contains
     end subroutine s_check_total_cells
 #endif
 
-    !> @brief Checks that simulation parameters stay within AMD GPU compiler limits when case optimization is disabled.
+    !> Check that simulation parameters stay within AMD GPU compiler limits when case optimization is disabled.
     impure subroutine s_check_amd
 
         #:if not MFC_CASE_OPTIMIZATION