Enhancement: WRF Coupled CMake Build and Documentation (#797)

* Adding Coupled WRF CMake build instructions * Modifications for building src directory with WRF CMake build system * Update paths and instructions for newer WRF release
NCAR · Jan 7, 2025 · fb7c1ee · fb7c1ee
1 parent 2682cee
commit fb7c1ee
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 31 deletions.
diff --git a/docs/userguide/appendices.rest b/docs/userguide/appendices.rest
@@ -76,11 +76,14 @@ project directory.
 3. Git clone WRF-Hydro, WRF, and WPS into project directory created in step 2
 4. Copy the uncompressed WPS geographic data into the WPS directory.
 5. Copy the uncompressed coupled example case into the project directory.
-6. Your project directory structure should now look like the following:
+6. Your project directory structure will look like the following:
 
 .. code-block:: console
 
    project_directory/
+   ├──run/
+   │   ├──WPS/
+   │   └──WRF/
    ├──wrf_hydro_nwm_public*/
    │   └──src/
    ├──WRF*/
@@ -118,31 +121,36 @@ with the updated version you just downloaded
   rm -r hydro
   cp -r ../wrf_hydro*/src hydro
 
-3. Set environment variables for required dependencies (e.g. netCDF libraries - see the
-WRF documentation for specific requirements) and compile time options for the
-WRF-Hydro modeling system.
-Edit the provided template (WRF/hydro/template/setEnvar.sh) as desired, but be sure to
-set the variable WRF_HYDRO to 1 so that WRF compiles with hydro
+3.  Load appropriate modules on Derecho:
 
 .. code-block:: console
 
-  source WRF/hydro/template/setEnvar.sh
+  module load ncarenv gcc ncarcompilers cray-mpich craype
+
 
-4.  Load appropriate modules on Derecho:
+
+4a. Configure WRF: CMake (preferred method)
 
 .. code-block:: console
 
-  module load ncarenv gcc ncarcompilers cray-mpich craype
+      cd …/WRF/
+      # CMake option to turn on WRF-Hydro nudging `-DWRF_HYDRO_NUDGING=1`
+      ./configure_new -x -p gfortran/gcc -- -DWRF_CORE=ARW -DWRF_NESTING=BASIC -DENABLE_HYDRO=ON -DWRF_CASE=EM_REAL
+      ./compile_new
 
 
-5.  Follow the steps here:
-    https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compilation_tutorial.php#STEP5
-    under "Building Libraries" to build the appropriate WRF libraries
+4b. Configure WRF: Old Method
 
-6. Export paths necessary for WRF to find the right libraries
 
 .. code-block:: console
 
+  # Load environement variables
+  source WRF/hydro/template/setEnvar.sh
+
+  # Export paths necessary for WRF to find the right libraries, follow the link
+  # https://www2.mmm.ucar.edu/wrf/OnLineTutorial/compilation_tutorial.php#STEP2
+  # under "Building Libraries" to build the appropriate WRF libraries
+
   export DIR=path/to/WRF/Build_WRF/LIBRARIES
   export NETCDF_INC=$DIR/netcdf/include
   export NETCDF_LIB=$DIR/netcdf/lib
@@ -157,17 +165,19 @@ set the variable WRF_HYDRO to 1 so that WRF compiles with hydro
   export LDFLAGS=-L$DIR/grib2/lib
   setenv CPPFLAGS -I$DIR/grib2/include
 
-7. Configure WRF
-On Derecho, selection option 50 (Intel dmpar Cray XC) and 1 (basic nesting)
-.. code-block:: console
-
+  # Configure WRF
+  # On Derecho, selection option 50 (Intel dmpar Cray XC) and 1 (basic nesting)
   cd …/WRF/
   ./configure
+  ./compile >& compile.log
+
+
+
 
 
 **Compiling the WRF Preprocessing System (WPS)**
 
-Make sure that paths are set as in Step #6 from above
+Make sure that paths are set as in Step #5b from above
 
 1. Navigate to the WPS source code directory at WPS*
 
@@ -212,8 +222,8 @@ WRF-Hydro will run).
 
 .. code-block:: console
 
-  cp ../../WPS*/geogrid.exe .
-  cp ../../WPS*/GEOGRID.TBL .
+  cp ../../WPS*/install/bin/geogrid.exe .
+  cp ../../WPS*/geogrid/GEOGRID.TBL .
   cp ../../example_case_coupled/namelist.wps .
 
 Edit the paths within this namelist as appropriate for your system
@@ -245,7 +255,7 @@ steps.
 
 .. code-block:: console
 
-  cp ../../WPS*/ungrib.exe .
+  cp ../../WPS*/install/bin/ungrib.exe .
   cp ../../WPS*/link_grib.csh .
 
 
@@ -255,7 +265,7 @@ steps.
 
   cp ../../WPS*/ungrib/Variable_Tables/Vtable.NAM Vtable
 
-3. Make sure grib2 library is available
+3. If the grib-util module is not loaded, make sure grib2 library is available
 
 .. code-block:: console
 
@@ -287,7 +297,7 @@ utility.
 
 .. code-block:: console
 
-  cp ../../WPS/metgrid.exe .
+  cp ../../WPS/install/bin/metgrid.exe .
   cp ../../WPS/metgrid/METGRID.TBL .
 
 2. Next run the metgrid utility
@@ -314,14 +324,18 @@ First we will create a run directory and copy over or link the required files.
 
 .. code-block:: console
 
-  cp -RL WRF*/run WRF
+  cd project_directory
+  mkdir run
+  cp -RL WRF*/run run/WRF
+  cd run/WRF
 
 
-2. Copy over parameter tables for WRF-Hydro from the template directory
+2. Copy over parameter tables for WRF-Hydro
 
 .. code-block:: console
 
   cp ../../WRF/hydro/src/template/HYDRO/*TBL .
+  cp ../../WRF/hydro/Land_models/NoahMP/run/*.TBL .
 
 3. Copy over the namelists for real / wrf (namelist.input) and the hydro components
 (hydro.namelist) from the example case
@@ -330,8 +344,8 @@ First we will create a run directory and copy over or link the required files.
 
   cp ../../example_case_coupled/namelist.input .
   cp ../../example_case_coupled/hydro.namelist .
-  cp -r path/to/example_case_coupled/DOMAIN/ .
-
+  cp ../../WRF/hydro/template/NoahMP/namelist.hrldas .
+  cp -r ../../example_case_coupled/DOMAIN/ .
 
 
 4. Link the geogrid and metgrid files we just generated from the WPS utilities
@@ -342,24 +356,32 @@ First we will create a run directory and copy over or link the required files.
   ln -sf ../WPS/geo_em* .
 
 
+4. Copy executable files
+
+.. code-block:: console
+
+  cp ../../WRF/install/bin/real .
+  cp ../../WRF/install/bin/wrf .
+
+
 **Running the real utility**
 
 The WRF real utility creates the wrfinput* and wrfbdy* initial and boundary
 condition files to be used as input for the coupled simulation.
 
-1. Execute real.exe using the proper syntax for your system (example below)
+1. Execute real using the proper syntax for your system (example below)
    and pipe the output to a log file.
 
 .. code-block:: console
 
-  mpirun -np 2 ./real.exe >& real.log
+  mpirun -np 2 ./real >& real.log
 
 2. Next review the rsl.out.* and rsl.error.* files for possible errors and
    check to make sure the wrfinput* and wrfbdy* files have been created.
 
 **Running the coupled model**
 
-Now we will run the coupled model (all included in the wrf.exe binary) using
+Now we will run the coupled model (all included in the wrf binary) using
 the wrfinput* and wrfbdy* files as initial and boundary conditions and the
 model physics and other options selected in the namelist.input and
 hydro.namelist files.
@@ -369,7 +391,7 @@ hydro.namelist files.
 
 .. code-block:: console
 
-  mpirun -np 2 ./wrf.exe >& wrf.log
+  mpirun -np 2 ./wrf >& wrf.log
 
 2. If your simulation ran successfully, there should now be a large number of
    output files. Descriptions of the output files can be found in the

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
@@ -1,3 +1,15 @@
+if(${PROJECT_NAME} STREQUAL "WRF")
+        # additions that WRF-Hydro's top CMakeLists.txt handles
+        add_compile_options( "${PROJECT_COMPILE_OPTIONS}" )
+        add_compile_definitions( "${PROJECT_COMPILE_DEFINITIONS}" )
+        set(CMAKE_Fortran_MODULE_DIRECTORY ${PROJECT_BINARY_DIR}/hydro/mods)
+        add_definitions(-DMPP_LAND)
+        if (WRF_HYDRO_NUDGING STREQUAL "1")
+                add_definitions(-DWRF_HYDRO_NUDGING=1)
+        endif()
+endif()
+
+
 # build the various sup-projects
 add_subdirectory("MPP")
 add_subdirectory("utils")
@@ -11,6 +23,9 @@ add_subdirectory("Routing/Diversions")
 add_subdirectory("Data_Rec")
 add_subdirectory("Routing")
 add_subdirectory("HYDRO_drv")
+if(${PROJECT_NAME} STREQUAL "WRF")
+        add_subdirectory("CPL/WRF_cpl")
+endif()
 
 if (WRF_HYDRO_NUDGING STREQUAL "1")
         add_subdirectory("nudging")
@@ -198,6 +213,25 @@ elseif (HYDRO_LSM MATCHES "Noah")
                 COMMAND rm ${PROJECT_BINARY_DIR}/src/wrfhydro.exe
         )
 
+elseif(${PROJECT_NAME} STREQUAL "WRF")
+        add_library(wrfhydro INTERFACE)
+        target_link_libraries(wrfhydro INTERFACE
+                hydro_utils
+                hydro_mpp
+                hydro_debug_utils
+                hydro_routing_overland
+                hydro_routing_subsurface
+                hydro_data_rec
+                hydro_routing
+                hydro_routing_reservoirs_levelpool
+                hydro_routing_reservoirs_hybrid
+                hydro_routing_reservoirs_rfc
+                hydro_routing_reservoirs
+                hydro_wrf_cpl
+                hydro_orchestrator
+                hydro_netcdf_layer
+                hydro_driver
+        )
 else()
         message("Unknown land surface model:" ${HYDRO_LSM} )
 endif()
diff --git a/src/CPL/WRF_cpl/CMakeLists.txt b/src/CPL/WRF_cpl/CMakeLists.txt
@@ -0,0 +1,25 @@
+add_library(hydro_wrf_cpl STATIC
+        wrf_drv_HYDRO.F90
+        module_wrf_HYDRO.F90
+)
+
+add_dependencies(hydro_wrf_cpl
+        hydro_mpp
+        hydro_utils
+        hydro_debug_utils
+        hydro_data_rec
+        hydro_driver
+        hydro_orchestrator
+        ${PROJECT_NAME}_Core
+        MPI::MPI_Fortran
+)
+
+target_include_directories(hydro_wrf_cpl
+        PRIVATE
+        $<TARGET_PROPERTY:${PROJECT_NAME}_Core,Fortran_MODULE_DIRECTORY>
+        $<TARGET_PROPERTY:esmf_time_f90,Fortran_MODULE_DIRECTORY>
+)
+
+target_include_directories(hydro_wrf_cpl PUBLIC
+        ${MPI_Fortran_MODULE_DIR}
+)