doxygen marked code: subset 2 (#657)

doxygen: add marked-up wm* multi files

model/src/wmfinlmd.F90

@@ -1,5 +1,16 @@
+!> @file
+!> @brief Contains module WMFINLMD.
+!> 
+!> @author H. L. Tolman @date 04-Feb-2014
+!> 
+
 #include "w3macros.h"
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Finalization of the multi-grid wave model.
+!> 
+!> @author H. L. Tolman @date 04-Feb-2014
+!>
       MODULE WMFINLMD
 !/
 !/                  +-----------------------------------+
@@ -55,6 +66,11 @@ MODULE WMFINLMD
 !/
       CONTAINS
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Initialize multi-grid version of WAVEWATCH III.
+!>
+!> @author H. L. Tolman  @date 28-Jan-2014
+!>        
       SUBROUTINE WMFINL
 !/
 !/                  +-----------------------------------+

model/src/wmgridmd.F90

@@ -1,5 +1,21 @@
+!> @file
+!> @brief Contains module WMGRIDMD.
+!> 
+!> @author H. L. Tolman
+!> @author W. E. Rogers
+!> @date 10-Dec-2014
+!>
+
 #include "w3macros.h"
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Routines to determine and process grid dependencies in the 
+!>  multi-grid wave model.
+!> 
+!> @author H. L. Tolman
+!> @author W. E. Rogers
+!> @date 10-Dec-2014
+!>
       MODULE WMGRIDMD
 !/
 !/                  +-----------------------------------+
@@ -116,10 +132,22 @@ MODULE WMGRIDMD
 !/
 !/ Module private variable for checking error returns
 !/
-      INTEGER, PRIVATE        :: ISTAT
+      INTEGER, PRIVATE        :: ISTAT  !< ISTAT Checking error returns.
 !/
       CONTAINS
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Determine relations to lower ranked grids for each grid.
+!>
+!> @details On the fly, the opposite relations are also saved.
+!>  Map active boundary points to lower ranked grids.        
+!>
+!> @param[out] FLRBPI Array with flags for external file use.
+!>
+!> @author H. L. Tolman
+!> @author W. E. Rogers
+!> @date 06-Jun-2018
+!>        
       SUBROUTINE WMGLOW ( FLRBPI )
 !/
 !/                  +-----------------------------------+
@@ -1058,6 +1086,16 @@ SUBROUTINE WMGLOW ( FLRBPI )
       END SUBROUTINE WMGLOW
 
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Determine relation to higher ranked grids for each grid.
+!>
+!> @details Base map set in WMGLOW, supplemental data computed here.
+!>  Map averaging information for higher ranked grid to lower ranked grid.
+!>
+!> @author H. L. Tolman
+!> @author W. E. Rogers
+!> @date 10-Dec-2014
+!>      
       SUBROUTINE WMGHGH
 !/
 !/                  +-----------------------------------+
@@ -3659,7 +3697,15 @@ SUBROUTINE WMGHGH
 !/
       END SUBROUTINE WMGHGH
 !/ ------------------------------------------------------------------- /
-      SUBROUTINE WMGEQL
+!>
+!> @brief Determine relations to same ranked grids for each grid.
+!>
+!> @details Cross mapping of grid points, determine boundary distance
+!>  data and interpolation weights.
+!>
+!> @author H. L. Tolman  @date 10-Dec-2014
+!>
+        SUBROUTINE WMGEQL
 !/
 !/                  +-----------------------------------+
 !/                  | WAVEWATCH III           NOAA/NCEP |
@@ -5081,6 +5127,14 @@ SUBROUTINE WMGEQL
 !/
       END SUBROUTINE WMGEQL
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Generate map with flags for need of spectral grid conversion 
+!>  between models.
+!>
+!> @details Test of parameters as introduced before in W3IOBC.
+!>
+!> @author H. L. Tolman  @date 10-Dec-2014
+!>
       SUBROUTINE WMRSPC
 !/
 !/                  +-----------------------------------+
@@ -5217,6 +5271,16 @@ SUBROUTINE WMRSPC
       END SUBROUTINE WMRSPC
 !/
 !!
+!>
+!> @brief Determine relations to same ranked SMC grids for each grid.
+!>
+!> @details Set boundary points update for regular grid in same ranked group.
+!>
+!>  Cross mapping of grid points, use nearest sea points and no
+!>  interpolation is required so far. 
+!>      
+!> @author J G Li  @date 12-Apr-2021
+!>      
       SUBROUTINE WMSMCEQL
 !!
 !!    Adapted from multi-grid sub WMGEQL for set up equal ranked SMC

model/src/wminiomd.F90

@@ -1,5 +1,16 @@
+!> @file
+!> @brief Contains module WMINIOMD.
+!> 
+!> @author H. L. Tolman  @date 28-Sep-2016
+!>
+
 #include "w3macros.h"
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Internal IO routines for the multi-grid model.
+!>
+!> @author H. L. Tolman  @date 28-Sep-2016
+!>
       MODULE WMINIOMD
 !/
 !/                  +-----------------------------------+
@@ -77,6 +88,19 @@ MODULE WMINIOMD
 !/
       CONTAINS
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Stage internal boundary data in the data structure BPSTGE.
+!>
+!> @details For the shared memory version, arrays are initialized and
+!>  the data are copied. For the distributed memory version, the data
+!>  are moved using a non-blocking send. In this case, the arrays
+!>  are dimensioned on the receiving side.
+!>
+!> @param[in] IMOD Model number of grid from which data is to
+!>                    be staged.
+!>
+!> @author H. L. Tolman  @date 06-Jun-2018
+!>        
       SUBROUTINE WMIOBS ( IMOD )
 !/
 !/                  +-----------------------------------+
@@ -450,6 +474,25 @@ SUBROUTINE WMIOBS ( IMOD )
 !/
       END SUBROUTINE WMIOBS
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Gather internal boundary data for a given model.
+!>
+!> @details For the shared memory version, data are gathered from
+!>  the data structure BPSTGE. For the distributed memory version,
+!>  the gathering of the data are finished first.
+!>
+!>  Gathering of data is triggered by the time stamp of the data
+!>  that is presently in the storage arrays.
+!>
+!>  This routine preempts the data flow normally executed by
+!>  W3IOBC and W3UBPT, and hence bypasses both routines in W3WAVE.
+!>
+!> @param[in] IMOD Model number of grid from which data is to
+!>                    be gathered.
+!> @param[out] DONE Flag for completion of operation (opt).
+!>
+!> @author H. L. Tolman  @date 29-May-2006
+!>      
       SUBROUTINE WMIOBG ( IMOD, DONE ) 
 !/
 !/                  +-----------------------------------+
@@ -1161,6 +1204,18 @@ SUBROUTINE WMIOBG ( IMOD, DONE )
 !/
       END SUBROUTINE WMIOBG
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Finalize staging of  internal boundary data in the data
+!>  structure BPSTGE (MPI only).
+!>
+!> @details Post appropriate 'wait' functions to assure that the
+!>  communication has finished.
+!>
+!> @param[in] IMOD Model number of grid from which data has
+!>                    been staged.
+!>
+!> @author H. L. Tolman  @date 29-May-2006
+!>      
       SUBROUTINE WMIOBF ( IMOD )
 !/
 !/                  +-----------------------------------+
@@ -1322,6 +1377,17 @@ SUBROUTINE WMIOBF ( IMOD )
 !/
       END SUBROUTINE WMIOBF
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Stage internal high-to-low data in the data structure HGSTGE.
+!>
+!> @details Directly fill staging arrays in shared memory version, or post
+!>  the corresponding sends in distributed memory version.
+!>
+!> @param[in] IMOD Model number of grid from which data is to
+!>                    be staged.
+!>
+!> @author H. L. Tolman  @date 28-Sep-2016
+!>      
       SUBROUTINE WMIOHS ( IMOD )
 !/
 !/                  +-----------------------------------+
@@ -1647,6 +1713,21 @@ SUBROUTINE WMIOHS ( IMOD )
 !/
       END SUBROUTINE WMIOHS
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Gather internal high-to-low data for a given model.
+!>
+!> @details For distributed memory version first receive all staged data.
+!>  After staged data is present, average, convert as necessary,
+!>  and store in basic spectral arrays.
+!>
+!>  Using storage array HGSTAGE and time stamps.
+!>      
+!> @param[in] IMOD Model number of grid from which data is to
+!>                    be gathered.
+!> @param[out] DONE Flag for completion of operation (opt).
+!>
+!> @author H. L. Tolman  @date 20-Dec-2006
+!>      
       SUBROUTINE WMIOHG ( IMOD, DONE ) 
 !/
 !/                  +-----------------------------------+
@@ -1667,7 +1748,7 @@ SUBROUTINE WMIOHG ( IMOD, DONE )
 !
 !     For distributed memory version first receive all staged data.
 !     After staged data is present, average, convert as necessary,
-!     and store in basic spatral arrays.
+!     and store in basic spectral arrays.
 !
 !  2. Method :
 !
@@ -2236,6 +2317,18 @@ SUBROUTINE WMIOHG ( IMOD, DONE )
 !/
       END SUBROUTINE WMIOHG
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Finalize staging of internal high-to-low data in the data
+!>  structure HGSTGE (MPI only).
+!>
+!> @details Post appropriate 'wait' functions to assure that the
+!>  communication has finished.
+!>
+!> @param[in] IMOD Model number of grid from which data has
+!>                    been staged.
+!>
+!> @author H. L. Tolman  @date 16-Jan-2006
+!>      
       SUBROUTINE WMIOHF ( IMOD )
 !/
 !/                  +-----------------------------------+
@@ -2393,6 +2486,17 @@ SUBROUTINE WMIOHF ( IMOD )
 !/
       END SUBROUTINE WMIOHF
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Stage internal same-rank data in the data structure EQSTGE.
+!>
+!> @details Directly fill staging arrays in shared memory version, or post
+!>  the corresponding sends in distributed memory version.
+!>
+!> @param[in] IMOD Model number of grid from which data is to
+!>                 be staged.
+!>
+!> @author H. L. Tolman  @date 28-Sep-2016
+!>      
       SUBROUTINE WMIOES ( IMOD )
 !/
 !/                  +-----------------------------------+
@@ -2705,6 +2809,21 @@ SUBROUTINE WMIOES ( IMOD )
 !/
       END SUBROUTINE WMIOES
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Gather internal same-rank data for a given model.
+!>
+!> @details For distributed memory version first receive all staged
+!>  data. After staged data is present, average, convert as necessary,
+!>  and store in basic spectral arrays.
+!>
+!>  Using storage array EQSTGE and time stamps.
+!>      
+!> @param[in] IMOD Model number of grid from which data is to
+!>                    be gathered.
+!> @param[out] DONE Flag for completion of operation (opt).
+!>
+!> @author H. L. Tolman  @date 22-Jan-2007
+!>      
       SUBROUTINE WMIOEG ( IMOD, DONE ) 
 !/
 !/                  +-----------------------------------+
@@ -2726,7 +2845,7 @@ SUBROUTINE WMIOEG ( IMOD, DONE )
 !
 !     For distributed memory version first receive all staged data.
 !     After staged data is present, average, convert as necessary,
-!     and store in basic spatral arrays.
+!     and store in basic spectral arrays.
 !
 !  2. Method :
 !
@@ -3272,6 +3391,18 @@ SUBROUTINE WMIOEG ( IMOD, DONE )
 !/
       END SUBROUTINE WMIOEG
 !/ ------------------------------------------------------------------- /
+!>
+!> @brief Finalize staging of internal same-rank data in the data
+!>  structure EQSTGE (MPI only).
+!>
+!> @details Post appropriate 'wait' functions to assure that the
+!>  communication has finished.
+!>
+!> @param[in] IMOD Model number of grid from which data has
+!>                 been staged.
+!>
+!> @author H. L. Tolman  @date 25-May-2006
+!>      
       SUBROUTINE WMIOEF ( IMOD )
 !/
 !/                  +-----------------------------------+