From 1bade53d19bb7c531e5bf16273684bf749d10b17 Mon Sep 17 00:00:00 2001
From: George Gayno <ggayno@hercules-login-2.hpc.msstate.edu>
Date: Thu, 9 Jan 2025 10:28:06 -0600
Subject: [PATCH] Baseline unit test for routine 'read_mask'. Fix doxygen in
 that routine.

Fixes #1000.
---
 sorc/orog_mask_tools.fd/orog.fd/io_utils.F90 |   6 +-
 tests/orog/CMakeLists.txt                    |   8 ++
 tests/orog/data/C48.mx500.tile1.nc           | Bin 0 -> 55384 bytes
 tests/orog/ftst_read_mask.F90                |  82 +++++++++++++++++++
 4 files changed, 93 insertions(+), 3 deletions(-)
 create mode 100644 tests/orog/data/C48.mx500.tile1.nc
 create mode 100644 tests/orog/ftst_read_mask.F90

diff --git a/sorc/orog_mask_tools.fd/orog.fd/io_utils.F90 b/sorc/orog_mask_tools.fd/orog.fd/io_utils.F90
index a89d6e238..d6dc508cc 100644
--- a/sorc/orog_mask_tools.fd/orog.fd/io_utils.F90
+++ b/sorc/orog_mask_tools.fd/orog.fd/io_utils.F90
@@ -343,9 +343,9 @@ end subroutine write_mask_netcdf
 !> Read the land mask file
 !!
 !! @param[in] merge_file path 
-!! @param[in] slm Land-sea mask.
-!! @param[in] land_frac Land fraction.
-!! @param[in] lake_frac Lake fraction
+!! @param[out] slm Land-sea mask.
+!! @param[out] land_frac Land fraction.
+!! @param[out] lake_frac Lake fraction
 !! @param[in] im 'i' dimension of a model grid tile.
 !! @param[in] jm 'j' dimension of a model grid tile.
 !! @author George Gayno NOAA/EMC
diff --git a/tests/orog/CMakeLists.txt b/tests/orog/CMakeLists.txt
index 7986143ea..ca02d8215 100644
--- a/tests/orog/CMakeLists.txt
+++ b/tests/orog/CMakeLists.txt
@@ -23,6 +23,10 @@ execute_process( COMMAND ${CMAKE_COMMAND} -E copy
 execute_process( COMMAND ${CMAKE_COMMAND} -E copy
     ${CMAKE_CURRENT_SOURCE_DIR}/data/C12_grid.tile1.nc ${CMAKE_CURRENT_BINARY_DIR}/C12_grid.tile1.nc)
 
+# Note, the "read_mask" test expects this file.
+execute_process( COMMAND ${CMAKE_COMMAND} -E copy
+    ${CMAKE_CURRENT_SOURCE_DIR}/data/C48.mx500.tile1.nc ${CMAKE_CURRENT_BINARY_DIR}/C48.mx500.tile1.nc)
+
 add_executable(ftst_ll2xyz ftst_ll2xyz.F90)
 add_test(NAME orog-ftst_ll2xyz COMMAND ftst_ll2xyz)
 target_link_libraries(ftst_ll2xyz orog_lib)
@@ -86,3 +90,7 @@ target_link_libraries(ftst_read_mdl_dims orog_lib)
 add_executable(ftst_read_mdl_grid_file ftst_read_mdl_grid_file.F90)
 add_test(NAME orog-ftst_read_mdl_grid_file COMMAND ftst_read_mdl_grid_file)
 target_link_libraries(ftst_read_mdl_grid_file orog_lib)
+
+add_executable(ftst_read_mask ftst_read_mask.F90)
+add_test(NAME orog-ftst_read_mask COMMAND ftst_read_mask)
+target_link_libraries(ftst_read_mask orog_lib)
diff --git a/tests/orog/data/C48.mx500.tile1.nc b/tests/orog/data/C48.mx500.tile1.nc
new file mode 100644
index 0000000000000000000000000000000000000000..51b5fc0a40eaee21145fa6b33a3dc215d82f0648
GIT binary patch
literal 55384
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

literal 0
HcmV?d00001

diff --git a/tests/orog/ftst_read_mask.F90 b/tests/orog/ftst_read_mask.F90
new file mode 100644
index 000000000..e7d9f552f
--- /dev/null
+++ b/tests/orog/ftst_read_mask.F90
@@ -0,0 +1,82 @@
+ program read_mask_test
+
+! Test routine 'read_mask' by reading a sample C48 global
+! uniform tile file.
+!
+! Author George Gayno NCEP/EMC
+
+ use io_utils, only      : read_mask
+
+ implicit none
+
+ character(len=20)       :: merge_file
+
+ integer, parameter      :: im=48
+ integer, parameter      :: jm=48
+ integer, parameter      :: chk_pts = 4
+ integer                 :: i, j, ij
+
+ real, parameter         :: EPSILON = 0.001
+ real                    :: land_frac(im,jm)
+ real                    :: lake_frac(im,jm)
+ real                    :: slm(im,jm)
+ real                    :: land_frac_chk(chk_pts)
+ real                    :: lake_frac_chk(chk_pts)
+ real                    :: slm_chk(chk_pts)
+
+ type :: indices
+  integer :: i
+  integer :: j
+ end type indices
+
+ type(indices)           :: idx(chk_pts)
+
+! The i/j indicies of the check points.
+
+ data idx%i /1,29,47,48/
+ data idx%j /1,25,23,48/
+
+! The expected values of the check points.
+
+ data land_frac_chk /0.58463, 0.8377, 0.0, 0.415374/
+ data lake_frac_chk /0.0, 0.0, 1.0, 0.0/
+ data slm_chk /1.0, 1.0, 0.0, 0.0/
+
+ print*,"- Starting test of routine read_mask."
+
+ merge_file = "./C48.mx500.tile1.nc"
+
+! Initialize output fields to flag value.
+
+ land_frac = -999.9
+ lake_frac = -999.9
+ slm       = -999.9
+
+ call read_mask(merge_file,slm,land_frac,lake_frac,im,jm)
+
+! All flag values should have been replaced. All fields
+! should have values greater than zero.
+
+ do j = 1, jm
+ do i = 1, im
+   if (land_frac(i,j) < 0.0) stop 3
+   if (lake_frac(i,j) < 0.0) stop 5
+   if (slm(i,j) < 0.0) stop 7
+ enddo
+ enddo
+ 
+! Check some points against expected values.
+
+ do ij = 1, chk_pts
+   i = idx(ij)%i
+   j = idx(ij)%j
+   if (abs(land_frac(i,j)-land_frac_chk(ij)) > EPSILON) stop 12
+   if (abs(lake_frac(i,j)-lake_frac_chk(ij)) > EPSILON) stop 15
+   if (abs(slm(i,j)-slm_chk(ij)) > EPSILON) stop 18
+ enddo
+
+ print*,"OK"
+
+ print*,"SUCCESS"
+
+ end program read_mask_test