Merge branch 'NOAA-EMC:develop' into failed_nearest_point_fix

CMakeLists.txt

@@ -13,7 +13,7 @@ project(
 
 get_directory_property(hasParent PARENT_DIRECTORY)
 if(hasParent)
-  # Unset flags that come from Parent (ie UFS or other coupled build) 
+  # Unset flags that come from Parent (ie UFS or other coupled build)
   # for potential (-r8/-r4) conflict
   set(CMAKE_Fortran_FLAGS "")
   set(CMAKE_C_FLAGS "")
@@ -22,8 +22,9 @@ endif()
 
 set(MULTI_ESMF OFF CACHE BOOL "Build ww3_multi_esmf library")
 set(NETCDF ON CACHE BOOL "Build NetCDF programs (requires NetCDF)")
-set(ENDIAN "BIG" CACHE STRING "Endianness of unformatted output files. Valid values are 'BIG', 'LITTLE', 'NATIVE'.") 
+set(ENDIAN "BIG" CACHE STRING "Endianness of unformatted output files. Valid values are 'BIG', 'LITTLE', 'NATIVE'.")
 set(EXCLUDE_FIND "" CACHE STRING "Don't try and search for these libraries (assumd to be handled by the compiler/wrapper)")
+set(ENABLE_DOCS OFF CACHE BOOL "Enable building of doxygen generated documentation")
 
 # make sure all "exclude_find" entries are lower case
 list(TRANSFORM EXCLUDE_FIND TOLOWER)
@@ -59,6 +60,13 @@ endif()
 
 add_subdirectory(model)
 
+# Turn on doxygen documentation
+if (ENABLE_DOCS)
+  list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/docs/cmake")
+  include(EnableDoxygen)
+  add_subdirectory(docs)
+endif()
+
 # Turn on unit testing.
 #include(CTest)
 #if(BUILD_TESTING)

README.md

@@ -1,23 +1,25 @@
 # The WAVEWATCH III Framework
 
-WAVEWATCH III<sup>&reg;</sup>  is a community wave modeling framework that includes the 
+WAVEWATCH III<sup>&reg;</sup>  is a community wave modeling framework that includes the
 latest scientific advancements in the field of wind-wave modeling and dynamics.
 
 ## General Features
 
-WAVEWATCH III<sup>&reg;</sup> solves the random phase spectral action density 
-balance equation for wavenumber-direction spectra. The model includes options 
-for shallow-water (surf zone) applications, as well as wetting and drying of 
-grid points. Propagation of a wave spectrum can be solved using regular 
-(rectilinear or curvilinear) and unstructured (triangular) grids. See 
-[About WW3](https://github.com/NOAA-EMC/WW3/wiki/About-WW3) for a 
-detailed description of WAVEWATCH III<sup>&reg;</sup> .
+WAVEWATCH III<sup>&reg;</sup> solves the random phase spectral action density
+balance equation for wavenumber-direction spectra. The model includes options
+for shallow-water (surf zone) applications, as well as wetting and drying of
+grid points. Propagation of a wave spectrum can be solved using regular
+(rectilinear or curvilinear) and unstructured (triangular) grids. See
+[About WW3](https://github.com/NOAA-EMC/WW3/wiki/About-WW3) for a
+detailed description of WAVEWATCH III<sup>&reg;</sup>. For a web-based
+view of the WAVEWATCH III<sup>&reg;</sup> source code
+refer to the [WW3 doxygen documentation](https://noaa-emc.github.io/WW3).
 
 ## Installation
 
-The WAVEWATCH III<sup>&reg;</sup>  framework package has two parts that need to be combined so 
-all runs smoothly: the GitHub repo itself, and a binary data file bundle that 
-needs to be obtained from our ftp site. Steps to successfully acquire and install 
+The WAVEWATCH III<sup>&reg;</sup>  framework package has two parts that need to be combined so
+all runs smoothly: the GitHub repo itself, and a binary data file bundle that
+needs to be obtained from our ftp site. Steps to successfully acquire and install
 the framework are outlined in our [Quick Start](https://github.com/NOAA-EMC/WW3/wiki/Quick-Start)
 guide.
 
@@ -35,4 +37,3 @@ endorsement, recommendation or favoring by the Department of Commerce. The
 Department of Commerce seal and logo, or the seal and logo of a DOC bureau,
 shall not be used in any manner to imply endorsement of any commercial product
 or activity by DOC or the United States Government.
-

docs/CMakeLists.txt

@@ -0,0 +1 @@
+EnableDoxygen(docs)

docs/Doxyfile.in

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = docs
+OUTPUT_DIRECTORY       = @doc_output@
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -829,7 +829,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = model/src
+INPUT                  = @src_input@
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -2285,7 +2285,7 @@ CLASS_DIAGRAMS         = NO
 # DIA_PATH tag allows you to specify the directory where the dia binary resides.
 # If left empty dia is assumed to be found in the default search path.
 
-DIA_PATH               = 
+DIA_PATH               =
 
 # If set to YES the inheritance and collaboration graphs will hide inheritance
 # and usage relations if the target is undocumented or is not a class.

docs/cmake/EnableDoxygen.cmake

@@ -0,0 +1,27 @@
+# Doxygen documentation- Matt Masarik 24-Jul-2024.
+function(EnableDoxygen outdir)
+  find_package(Doxygen REQUIRED)
+    if (NOT DOXYGEN_FOUND)
+      add_custom_target(enable_docs
+          COMMAND false
+          COMMENT "Doxygen not found")
+      return()
+    endif()
+
+    set(src_input "${CMAKE_SOURCE_DIR}/model/src")
+    set(doc_output "${CMAKE_BINARY_DIR}/${outdir}")
+    file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/${outdir}/html)
+    CONFIGURE_FILE(${CMAKE_SOURCE_DIR}/docs/Doxyfile.in
+        ${CMAKE_BINARY_DIR}/${outdir}/Doxyfile @ONLY)
+    set(DOXYGEN_GENERATE_HTML YES)
+    set(DOXYGEN_QUIET YES)
+    add_custom_target(enable_docs
+        COMMAND
+          ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/${outdir}/Doxyfile
+        WORKING_DIRECTORY
+          ${CMAKE_BINARY_DIR}/${outdir}
+        COMMENT
+          "Generate Doxygen HTML documentation")
+    message("-- Doxygen HTML index page: "
+        ${CMAKE_BINARY_DIR}/${outdir}/html/index.html)
+endfunction()

model/src/w3gridmd.F90

@@ -845,7 +845,7 @@ MODULE W3GRIDMD
 #ifdef W3_ST4
   INTEGER                 :: SWELLFPAR, SDSISO, SDSBRFDF, SINTABLE,&
                              TAUWBUG
-  REAL 		   :: SDSBCHOICE
+  REAL                    :: SDSBCHOICE                     
   REAL                    :: ZWND, ALPHA0, Z0MAX, BETAMAX, SINTHP,&
        ZALP, Z0RAT, TAUWSHELTER, SWELLF,    &
        SWELLF2,SWELLF3,SWELLF4, SWELLF5,    &

model/src/w3initmd.F90

@@ -658,7 +658,6 @@ SUBROUTINE W3INIT ( IMOD, IsMulti, FEXT, MDS, MTRACE, ODAT, FLGRD,  FLGR2, FLGD,
       STOP
     ENDIF
 #endif
-
     !
     ! 1.c Open files without unpacking MDS ,,,
     !
@@ -1240,7 +1239,11 @@ SUBROUTINE W3INIT ( IMOD, IsMulti, FEXT, MDS, MTRACE, ODAT, FLGRD,  FLGR2, FLGD,
     !
     ! 4.d Preprocessing for point output.
     !
-    IF ( FLOUT(2) ) CALL W3IOPP ( NPT, XPT, YPT, PNAMES, IMOD )
+#ifdef W3_MPI    
+    IF ( FLOUT(2) ) CALL W3IOPP ( NPT, XPT, YPT, PNAMES, IMOD, MPI_COMM_WAVE )
+#else 
+    IF ( FLOUT(2) ) CALL W3IOPP ( NPT, XPT, YPT, PNAMES, IMOD, 1 )
+#endif 
 #ifdef W3_PDLIB
     CALL DEALLOCATE_PDLIB_GLOBAL(IMOD)
 #endif