Add MERRA-2 dynamic lapse rate double-sided cutoff

Kristen-M-Whitney · Kristen-M-Whitney · commit c3f3dca55ee6 · 2024-12-18T10:27:24.000-05:00
This commit adds the application of a double-sided cutoff to pre-generated hourly MERRA-2 lapse rate maps. This optional functionality will replace any lapse rate value that falls above (below) the maximum (minimum) cutoff threshold with the cutoff threshold value. The function is invoked by an optional config entry to apply the double-sided cutoff. If this config entry is not present, the cutoffs will not be applied. The commit also includes optional config entries to specify the minimum and maximum cutoff thresholds in units of K/m. If the config entry for the maximum (minimum) threshold is not present, the default is set to +0.01 (-0.01) K/m. Kristen Whitney and David Mocko worked together to modify the code with this functionality. Kristen Whitney performed code testing. For now, this code should remain in the eis-freshwater2 branch, and should not be merged into the main branch yet. Credit where credit is due: @dmocko helped with the corresponding code modifications and adjustments. Resolves: NASA-LIS#1653
diff --git a/lis/configs/lis.config.adoc b/lis/configs/lis.config.adoc
@@ -5738,14 +5738,48 @@ Acceptable values are:
 `MERRA2 dynamic lapse rate data directory:` specifies the
 directory of the pre-computed MERRA-2 lapse rate dataset.
 
+`MERRA2 apply double-sided dynamic lapse rate cutoff:` specifies whether
+to apply a double-sided cutoff to the dynamic lapse rate values. This is
+an optional config entry; if not present, the default is 0. If set to 1, 
+values above (below) the maximum (minimum) cutoff are replaced with the 
+maximum (minimum) cutoff value. Maximum and minimum cutoff values can
+optionally be set using the MERRA2 maximum and minimum lapse rate cutoff
+aguments, or otherwise are assumed the default cutoff values, as described 
+below.
+
+|====
+|Value | Description
+
+|0     | Do not apply MERRA-2 double-sided dynamic lapse rate cutoff.
+|1     | Apply MERRA-2 double-sided dynamic lapse rate cutoff.
+|====
+
+`MERRA2 maximum lapse rate cutoff (K/m):` specifies the maximum value
+for the MERRA2 double-sided dynamic lapse rate cutoff range, in units
+of Kelvin per meter (K/m). This is an optional config entry; if
+not present, the default is set to 0.01 K/m. This is only applied if
+MERRA2 apply double-sided dynamic lapse rate cutoff is turned on
+(i.e., set to a value of 1).
+
+`MERRA2 minimum lapse rate cutoff (K/m):` specifies the minimum value
+for the MERRA2 double-sided dynamic lapse rate cutoff range, in units
+of Kelvin per meter (K/m). This is an optional config entry; if
+not present, the default is set to -0.1 K/m. This is only applied if
+MERRA2 apply double-sided dynamic lapse rate cutoff is turned on
+(i.e., set to a value of 1).
+
 .Example _lis.config_ entry
+
 ....
-MERRA2 forcing directory:                  ./MERRA2
-MERRA2 use lowest model level forcing:     1
-MERRA2 use 2m wind fields:                 0 
-MERRA2 use corrected total precipitation:  1
-MERRA2 apply dynamic lapse rates:          0
-MERRA2 dynamic lapse rate data directory:  ./MERRA2_lapse_rates
+MERRA2 forcing directory:                             ./MERRA2
+MERRA2 use lowest model level forcing:                1
+MERRA2 use 2m wind fields:                            0
+MERRA2 use corrected total precipitation:             1
+MERRA2 apply dynamic lapse rates:                     1
+MERRA2 dynamic lapse rate data directory:             ./MERRA2_lapse_rates
+MERRA2 apply double-sided dynamic lapse rate cutoff:  1
+MERRA2 maximum lapse rate cutoff (K/m):               0.009
+MERRA2 minimum lapse rate cutoff (K/m):               -0.009
 ....
 
 [[sssec_forcings_GEOS-IT,GEOS-IT]]
diff --git a/lis/metforcing/merra2/get_merra2.F90 b/lis/metforcing/merra2/get_merra2.F90
@@ -18,6 +18,7 @@
 ! 08 Dec 2015: James Geiger, update timing logic
 ! 13 Sep 2024: Sujay Kumar, Initial code for using dynamic lapse rate
 ! 31 Oct 2024: David Mocko, Final code for using dynamic lapse rate
+! 18 Dec 2024: Kristen Whitney, code for using double-sided dynamic lapse rate cutoff
 !
 ! !INTERFACE:
 subroutine get_merra2(n, findex)
@@ -463,6 +464,13 @@ subroutine get_merra2(n, findex)
                  gid = LIS_domain(n)%gindex(c,r)
                  LIS_forc(n,findex)%lapseRate(gid) = &
                      merra2_struc(n)%lapserate2(gid,LIS_rc%hr+1)
+                 if(merra2_struc(n)%applydynlapseratecutoff.eq.1) then
+                    if(LIS_forc(n,findex)%lapseRate(gid).gt.merra2_struc(n)%dynlapseratemaxcutoff) then
+                       LIS_forc(n,findex)%lapseRate(gid) = merra2_struc(n)%dynlapseratemaxcutoff
+                    elseif(LIS_forc(n,findex)%lapseRate(gid).lt.merra2_struc(n)%dynlapseratemincutoff) then
+                       LIS_forc(n,findex)%lapseRate(gid) = merra2_struc(n)%dynlapseratemincutoff
+                    endif
+                 endif
               endif
            enddo
         enddo
@@ -473,6 +481,13 @@ subroutine get_merra2(n, findex)
                  gid = LIS_domain(n)%gindex(c,r)
                  LIS_forc(n,findex)%lapseRate(gid) = &
                      merra2_struc(n)%lapserate1(gid,LIS_rc%hr+1)
+                 if(merra2_struc(n)%applydynlapseratecutoff.eq.1) then
+                    if(LIS_forc(n,findex)%lapseRate(gid).gt.merra2_struc(n)%dynlapseratemaxcutoff) then
+                       LIS_forc(n,findex)%lapseRate(gid) = merra2_struc(n)%dynlapseratemaxcutoff
+                    elseif(LIS_forc(n,findex)%lapseRate(gid).lt.merra2_struc(n)%dynlapseratemincutoff) then
+                       LIS_forc(n,findex)%lapseRate(gid) = merra2_struc(n)%dynlapseratemincutoff
+                    endif
+                 endif
               endif
            enddo
         enddo
diff --git a/lis/metforcing/merra2/merra2_forcingMod.F90 b/lis/metforcing/merra2/merra2_forcingMod.F90
@@ -15,6 +15,7 @@ module merra2_forcingMod
 ! 18 Mar 2015: James Geiger, initial code (based on merra-land)
 ! 13 Sep 2024: Sujay Kumar, Initial code for using dynamic lapse rate
 ! 31 Oct 2024: David Mocko, Final code for using dynamic lapse rate
+! 18 Dec 2024: Kristen Whitney, code for using double-sided dynamic lapse rate cutoff
 !
 ! !DESCRIPTION:
 !  This module contains variables and data structures that are used
@@ -133,7 +134,10 @@ module merra2_forcingMod
      integer, allocatable    :: rseed(:,:)
      integer                 :: usedynlapserate
      character(len=LIS_CONST_PATH_LEN) :: dynlapseratedir
-     
+     integer                 :: applydynlapseratecutoff
+     real                    :: dynlapseratemincutoff
+     real                    :: dynlapseratemaxcutoff
+
   end type merra2_type_dec
 
   type(merra2_type_dec), allocatable :: merra2_struc(:)
diff --git a/lis/metforcing/merra2/readcrd_merra2.F90 b/lis/metforcing/merra2/readcrd_merra2.F90
@@ -16,6 +16,7 @@
 ! 18 Mar 2015: James Geiger, initial code (based on merra-land)
 ! 13 Sep 2024: Sujay Kumar, Initial code for using dynamic lapse rate
 ! 31 Oct 2024: David Mocko, Final code for using dynamic lapse rate
+! 18 Dec 2024: Kristen Whitney, code for using double-sided dynamic lapse rate cutoff
 !
 ! !INTERFACE:    
 subroutine readcrd_merra2()
@@ -86,6 +87,42 @@ subroutine readcrd_merra2()
         call LIS_verify(rc,&
              'MERRA2 dynamic lapse rate data directory: not defined')
      enddo
+
+     call ESMF_ConfigFindLabel(LIS_config,"MERRA2 apply double-sided dynamic lapse rate cutoff:",rc=rc)
+     do n=1,LIS_rc%nnest
+        call ESMF_ConfigGetAttribute(LIS_config,merra2_struc(n)%applydynlapseratecutoff,&
+                default=0, rc=rc)
+        call LIS_verify(rc,&
+                'MERRA2 apply double-sided dynamic lapse rate cutoff: no defined')
+     enddo
+
+     do n=1,LIS_rc%nnest 
+        if(merra2_struc(n)%applydynlapseratecutoff.eq.1) then
+           call ESMF_ConfigFindLabel(LIS_config,"MERRA2 minimum lapse rate cutoff (K/m):",rc=rc)
+           call ESMF_ConfigGetAttribute(LIS_config,merra2_struc(n)%dynlapseratemincutoff,&
+                   default=-0.01, rc=rc)
+           call LIS_verify(rc,&
+                   'MERRA2 minimum lapse rate cutoff (K/m): not defined')
+           call ESMF_ConfigFindLabel(LIS_config,"MERRA2 maximum lapse rate cutoff (K/m):",rc=rc)
+           call ESMF_ConfigGetAttribute(LIS_config,merra2_struc(n)%dynlapseratemaxcutoff,&
+                   default=0.01, rc=rc)
+           call LIS_verify(rc,&
+                   'MERRA2 maximum lapse rate cutoff (K/m): not defined')
+
+           ! Sanity check
+           if(merra2_struc(n)%dynlapseratemincutoff.gt.merra2_struc(n)%dynlapseratemaxcutoff) then
+              write(LIS_logunit,*) '[ERR] MERRA2 minimum lapse rate cutoff value should be'
+              write(LIS_logunit,*) '[ERR] less than the MERRA2 maximum lapse rate cutoff value.'
+              write(LIS_logunit,*) '[ERR] Note the default value is -0.01 K/m for the minimum cutoff,'
+              write(LIS_logunit,*) '[ERR] and 0.01 K/m for the maximum cutoff.'
+              write(LIS_logunit,*) '[ERR] Please ensure if specifying just the minimum (maximum)'
+              write(LIS_logunit,*) '[ERR] cutoff value, that it is less (greater) than the'
+              write(LIS_logunit,*) '[ERR] maximum (minimum) default value.'
+              write(LIS_logunit,*) '[ERR] STOPPING ....'
+              call LIS_endrun()
+           endif
+        endif   
+     enddo
   endif
 
   do n=1,LIS_rc%nnest
