Document GPU macros and constants; remove generic use-statement comments

Author: sbryngelson

src/common/include/parallel_macros.fpp

@@ -2,6 +2,7 @@
 #:include 'omp_macros.fpp'
 #:include 'acc_macros.fpp'
 
+! GPU parallel region (scalar reductions, maxval/minval)
 #:def GPU_PARALLEL(code, private=None, default='present', firstprivate=None, reduction=None, reductionOp=None, &
     & copy=None, copyin=None, copyinReadOnly=None, copyout=None, create=None, &
     & no_create=None, present=None, deviceptr=None, attach=None, extraAccArgs=None, extraOmpArgs=None)
@@ -20,6 +21,7 @@
 #endif
 #:enddef
 
+! GPU parallel loop over threads (most common GPU macro)
 #:def GPU_PARALLEL_LOOP(collapse=None, private=None, parallelism='[gang, vector]', &
     & default='present', firstprivate=None, reduction=None, reductionOp=None, &
     & copy=None, copyin=None, copyinReadOnly=None, copyout=None, create=None, &
@@ -39,6 +41,7 @@
 #endif
 #:enddef
 
+! Required closing for GPU_PARALLEL_LOOP
 #:def END_GPU_PARALLEL_LOOP()
     #:set acc_end_directive = '!$acc end parallel loop'
     #:set omp_end_directive = END_OMP_PARALLEL_LOOP()
@@ -50,6 +53,7 @@
 #endif
 #:enddef
 
+! Mark routine for device compilation
 #:def GPU_ROUTINE(function_name=None, parallelism=None, nohost=False, cray_inline=False, cray_noinline=False, extraAccArgs=None, &
                   & extraOmpArgs=None)
     #:assert isinstance(cray_inline, bool)
@@ -106,6 +110,7 @@
     #:endif
 #:enddef
 
+! Declare device-resident data
 #:def GPU_DECLARE(copy=None, copyin=None, copyinReadOnly=None, copyout=None, create=None, present=None, deviceptr=None, &
                   & link=None, extraAccArgs=None, extraOmpArgs=None)
     #:set acc_code = ACC_DECLARE(copy=copy, copyin=copyin, copyinReadOnly=copyinReadOnly, copyout=copyout, create=create, &
@@ -123,6 +128,7 @@
 #endif
 #:enddef
 
+! Inner loop within a GPU parallel region
 #:def GPU_LOOP(collapse=None, parallelism=None, data_dependency=None, reduction=None, reductionOp=None, private=None, &
                & extraAccArgs=None, extraOmpArgs=None)
     #:set acc_code = ACC_LOOP(collapse=collapse, parallelism=parallelism, data_dependency=data_dependency, reduction=reduction, &
@@ -137,6 +143,7 @@
 #endif
 #:enddef
 
+! Scoped GPU data region
 #:def GPU_DATA(code, copy=None, copyin=None, copyinReadOnly=None, copyout=None, create=None, no_create=None, present=None, &
                & deviceptr=None, attach=None, default=None, extraAccArgs=None, extraOmpArgs=None)
     #:set acc_code = ACC_DATA(code=code, copy=copy, copyin=copyin, copyinReadOnly=copyinReadOnly, copyout=copyout, create=create, &
@@ -155,6 +162,7 @@
 #endif
 #:enddef
 
+! Host code with device pointers (for MPI with GPU buffers)
 #:def GPU_HOST_DATA(code, use_device_addr=None, use_device_ptr=None, extraAccArgs=None, extraOmpArgs=None)
     #:if use_device_addr is not None and use_device_ptr is not None
         #:set use_device_addr_end_index = len(use_device_addr) - 1
@@ -183,6 +191,7 @@
 #endif
 #:enddef
 
+! Allocate device memory (unscoped)
 #:def GPU_ENTER_DATA(copyin=None, copyinReadOnly=None, create=None, attach=None, extraAccArgs=None, extraOmpArgs=None)
     #:set acc_code = ACC_ENTER_DATA(copyin=copyin, copyinReadOnly=copyinReadOnly, create=create, attach=attach, &
                                     & extraAccArgs=extraAccArgs)
@@ -196,6 +205,7 @@
 #endif
 #:enddef
 
+! Free device memory
 #:def GPU_EXIT_DATA(copyout=None, delete=None, detach=None, extraAccArgs=None, extraOmpArgs=None)
     #:set acc_code = ACC_EXIT_DATA(copyout=copyout, delete=delete, detach=detach, extraAccArgs=extraAccArgs)
     #:set omp_code = OMP_EXIT_DATA(copyout=copyout, delete=delete, detach=detach, extraOmpArgs=extraOmpArgs)
@@ -207,6 +217,7 @@
 #endif
 #:enddef
 
+! Atomic operation on device
 #:def GPU_ATOMIC(atomic, extraAccArgs=None, extraOmpArgs=None)
     #:set acc_code = ACC_ATOMIC(atomic=atomic, extraAccArgs=extraAccArgs)
     #:set omp_code = OMP_ATOMIC(atomic=atomic, extraOmpArgs=extraOmpArgs)
@@ -218,6 +229,7 @@
 #endif
 #:enddef
 
+! End atomic capture block
 #:def END_GPU_ATOMIC_CAPTURE()
     #:set acc_end_directive = '!$acc end atomic'
     #:set omp_end_directive = '!$omp end atomic'
@@ -228,6 +240,7 @@
 #endif
 #:enddef
 
+! Copy data between host and device
 #:def GPU_UPDATE(host=None, device=None, extraAccArgs=None, extraOmpArgs=None)
     #:set acc_code = ACC_UPDATE(host=host, device=device, extraAccArgs=extraAccArgs)
     #:set omp_code = OMP_UPDATE(host=host, device=device, extraOmpArgs=extraOmpArgs)
@@ -239,6 +252,7 @@
 #endif
 #:enddef
 
+! Synchronization barrier
 #:def GPU_WAIT(extraAccArgs=None, extraOmpArgs=None)
     #:set acc_code = ACC_WAIT(extraAccArgs=extraAccArgs)
     #:set omp_code = OMP_WAIT(extraOmpArgs=extraOmpArgs)
@@ -250,6 +264,7 @@
 #endif
 #:enddef
 
+! Import GPU library module (openacc or omp_lib)
 #:def USE_GPU_MODULE()
 #if defined(MFC_OpenACC)
     use openacc
@@ -258,24 +273,28 @@
 #endif
 #:enddef
 
+! Emit code only for AMD compiler
 #:def DEF_AMD(code)
     #:if MFC_COMPILER == AMD_COMPILER_ID
         $:code
     #:endif
 #:enddef
 
+! Emit code for non-Cray compilers
 #:def UNDEF_CCE(code)
     #:if MFC_COMPILER != CCE_COMPILER_ID
         $:code
     #:endif
 #:enddef
 
+! Emit code only for Cray compiler
 #:def DEF_CCE(code)
     #:if MFC_COMPILER == CCE_COMPILER_ID
         $:code
     #:endif
 #:enddef
 
+! Emit code for non-NVIDIA compilers
 #:def UNDEF_NVIDIA(code)
     #:if MFC_COMPILER != NVIDIA_COMPILER_ID and MFC_COMPILER != PGI_COMPILER_ID
         $:code

src/common/m_boundary_common.fpp

@@ -8,8 +8,8 @@
 
 module m_boundary_common
 
-    use m_derived_types     !< Definitions of the derived types
-    use m_global_parameters !< Definitions of the global parameters
+    use m_derived_types
+    use m_global_parameters
     use m_mpi_proxy
     use m_constants
     use m_delay_file_access

src/common/m_checker_common.fpp

@@ -8,9 +8,9 @@
 !> @brief Shared input validation checks for grid dimensions and AMD GPU compiler limits
 module m_checker_common
 
-    use m_global_parameters !< Definitions of the global parameters
-    use m_mpi_proxy         !< Message passing interface (MPI) module proxy
-    use m_helper_basic      !< Functions to compare floating point numbers
+    use m_global_parameters
+    use m_mpi_proxy
+    use m_helper_basic
     use m_helper
 
     implicit none

src/common/m_constants.fpp

@@ -23,11 +23,11 @@ module m_constants
     integer, parameter  :: fourier_rings = 5                  !< Fourier filter ring limit
     integer, parameter  :: num_fluids_max = 10                !< Maximum number of fluids in the simulation
     integer, parameter  :: num_probes_max = 10                !< Maximum number of flow probes in the simulation
-    integer, parameter  :: num_patches_max = 1000
-    integer, parameter  :: num_bc_patches_max = 10
+    integer, parameter  :: num_patches_max = 1000             !< Maximum number of IC patches
+    integer, parameter  :: num_bc_patches_max = 10            !< Maximum number of boundary condition patches
     integer, parameter  :: max_2d_fourier_modes = 10          !< Max Fourier mode index for 2D modal patch (geometry 13)
     integer, parameter  :: max_sph_harm_degree = 5            !< Max degree L for 3D spherical harmonic patch (geometry 14)
-    integer, parameter  :: pathlen_max = 400
+    integer, parameter  :: pathlen_max = 400                  !< Maximum path length for STL/OBJ model files
     integer, parameter  :: nnode = 4                          !< Number of QBMM nodes
     integer, parameter  :: dflt_num_igr_iters = 2             !< number of iterations for IGR elliptic solve
     integer, parameter  :: dflt_num_igr_warm_start_iters = 50 !< default number of iterations for IGR elliptic solve
@@ -68,24 +68,25 @@ module m_constants
     integer, parameter  :: dflt_adap_dt_max_iters = 100 !< Default max iteration for adaptive step size
     ! Constants of the algorithm described by Heirer, E. Hairer, S. P.Norsett, G. Wanner, Solving Ordinary Differential Equations I,
     ! Chapter II.4 to choose the initial time step size for the adaptive time stepping routine
-    real(wp), parameter :: threshold_first_guess = 1.e-5_wp
-    real(wp), parameter :: threshold_second_guess = 1.e-15_wp
-    real(wp), parameter :: scale_first_guess = 1.e-3_wp
-    real(wp), parameter :: scale_guess = 1.e-2_wp
-    real(wp), parameter :: small_guess = 1.e-6_wp
+    real(wp), parameter :: threshold_first_guess = 1.e-5_wp   !< Threshold for initial step size estimate
+    real(wp), parameter :: threshold_second_guess = 1.e-15_wp !< Threshold for refined step size estimate
+    real(wp), parameter :: scale_first_guess = 1.e-3_wp       !< Scale factor for initial step size
+    real(wp), parameter :: scale_guess = 1.e-2_wp             !< Scale factor for step size adjustment
+    real(wp), parameter :: small_guess = 1.e-6_wp             !< Minimum initial step size
 
     ! Relativity
+    !> Max Newton-Raphson iterations for relativistic primitive recovery
     integer, parameter :: relativity_cons_to_prim_max_iter = 100
 
-    ! Pseudo-random number generator
-    integer, parameter  :: modulus = 2**30 - 1
-    integer, parameter  :: multiplier = 1664525
-    integer, parameter  :: increment = 1013904223
-    integer, parameter  :: amplifier = 3**13
-    real(wp), parameter :: decimal_trim = 1.e5_wp
+    ! Linear congruential pseudo-random number generator parameters
+    integer, parameter  :: modulus = 2**30 - 1    !< PRNG modulus
+    integer, parameter  :: multiplier = 1664525   !< PRNG multiplier
+    integer, parameter  :: increment = 1013904223 !< PRNG increment
+    integer, parameter  :: amplifier = 3**13      !< PRNG amplifier for mixing
+    real(wp), parameter :: decimal_trim = 1.e5_wp !< PRNG decimal truncation factor
 
     ! System constants
-    integer, parameter :: CASE_FILE_ERROR_CODE = 22
+    integer, parameter :: CASE_FILE_ERROR_CODE = 22 !< Exit code for case file validation errors
 
     ! Boundary condition enumeration Abbreviations CHAR - Characteristic NR - Non-reflecting SUB - subsonic SUP - supersonic FF -
     ! Force-free CP - Constant pressure

src/common/m_derived_types.fpp

@@ -7,7 +7,7 @@
 !> @brief Shared derived types for field data, patch geometry, bubble dynamics, and MPI I/O structures
 module m_derived_types
 
-    use m_constants !< Constants
+    use m_constants
     use m_precision_select
     use m_thermochem, only: num_species
 

src/common/m_helper.fpp

@@ -8,9 +8,9 @@
 !> @brief Utility routines for bubble model setup, coordinate transforms, array sampling, and special functions
 module m_helper
 
-    use m_derived_types     !< Definitions of the derived types
-    use m_global_parameters !< Definitions of the global parameters
-    use ieee_arithmetic     !< For checking NaN
+    use m_derived_types
+    use m_global_parameters
+    use ieee_arithmetic !< For checking NaN
     implicit none
 
     private;

src/common/m_helper_basic.fpp

@@ -7,7 +7,7 @@
 !> @brief Basic floating-point utilities: approximate equality, default detection, and coordinate bounds
 module m_helper_basic
 
-    use m_derived_types !< Definitions of the derived types
+    use m_derived_types
     implicit none
 
     private;

src/common/m_mpi_common.fpp

@@ -12,8 +12,8 @@ module m_mpi_common
     use mpi !< Message passing interface (MPI) module
 #endif
 
-    use m_derived_types     !< Definitions of the derived types
-    use m_global_parameters !< Definitions of the global parameters
+    use m_derived_types
+    use m_global_parameters
     use m_helper
     use ieee_arithmetic
     use m_nvtx

src/common/m_phase_change.fpp

@@ -9,12 +9,12 @@
 module m_phase_change
 
 #ifndef MFC_POST_PROCESS
-    use m_derived_types        !< Definitions of the derived types
-    use m_global_parameters    !< Definitions of the global parameters
-    use m_mpi_proxy            !< Message passing interface (MPI) module proxy
-    use m_variables_conversion !< State variables type conversion procedures
+    use m_derived_types
+    use m_global_parameters
+    use m_mpi_proxy
+    use m_variables_conversion
     use ieee_arithmetic
-    use m_helper_basic         !< Functions to compare floating point numbers
+    use m_helper_basic
     implicit none
 
     private;

src/common/m_variables_conversion.fpp

@@ -8,10 +8,10 @@
 !> @brief Conservative-to-primitive variable conversion, mixture property evaluation, and pressure computation
 module m_variables_conversion
 
-    use m_derived_types     !< Definitions of the derived types
-    use m_global_parameters !< Definitions of the global parameters
-    use m_mpi_proxy         !< Message passing interface (MPI) module proxy
-    use m_helper_basic      !< Functions to compare floating point numbers
+    use m_derived_types
+    use m_global_parameters
+    use m_mpi_proxy
+    use m_helper_basic
     use m_helper
     use m_thermochem, only: num_species, get_temperature, get_pressure, gas_constant, get_mixture_molecular_weight, &
         & get_mixture_energy_mass