Merge pull request #1578 from dmocko/feature/nldas2-lismetforcing-netcdf

Add NLDAS-2 netCDF-4 LIS metforcing reader
NASA-LIS · Jul 25, 2024 · b36e3e7 · b36e3e7
2 parents 34d29a0 + 0c8cac0
commit b36e3e7
Show file tree

Hide file tree

Showing 18 changed files with 2,659 additions and 19 deletions.
diff --git a/docs/LIS_users_guide/user_cfg_table.adoc b/docs/LIS_users_guide/user_cfg_table.adoc
@@ -31,7 +31,8 @@
 | GSWP2                                  | On
 | AGRMET                                 | Off
 | PRINCETON                              | On
-| NLDAS2                                 | On
+| NLDAS2 grib                            | On
+| NLDAS2 netcdf                          | On
 | GLDAS                                  | On
 | GFS                                    | On
 | MERRA2                                 | On

diff --git a/lis/configs/lis.config.adoc b/lis/configs/lis.config.adoc
@@ -346,7 +346,8 @@ Acceptable values for the sources are:
 |"`GSWP2`"                     | GSWP2
 |"`AGRMET`"                    | AGRMET
 |"`PRINCETON`"                 | Princeton
-|"`NLDAS2`"                    | NLDAS2
+|"`NLDAS2 grib`"               | NLDAS-2 GRIB-1 format
+|"`NLDAS2 netcdf`"             | NLDAS-2 v020 netCDF-4 format
 |"`GLDAS`"                     | GLDAS
 |"`GFS`"                       | GFS
 |"`MERRA2`"                    | MERRA2
@@ -5883,15 +5884,14 @@ SCAN forcing directory:   ./input/FORCING/SCAN
 SCAN metadata file:       ./input/FORCING/SCAN/msu_scan.mdata
 ....
 
+[[sssec_forcings_nldas2,NLDAS2 (grib)]]
+==== NLDAS2 (grib)
 
-[[sssec_forcings_nldas2,NLDAS2]]
-==== NLDAS2
+`NLDAS2 forcing directory:` specifies the location of the NLDAS-2
+GRIB-1 forcing files.
 
-`NLDAS2 forcing directory:` specifies the location of the NLDAS2
-forcing files.
-
-`NLDAS2 data center source:` specifies the center that produced
-the NLDAS2 files. (This is specified to distinguish the filenames.)
+`NLDAS2 data center source:` specifies the center that produced the
+NLDAS-2 GRIB-1 files.  (This is specified to distinguish the filenames.)
 Acceptable values are:
 
 |====
@@ -5903,7 +5903,7 @@ Acceptable values are:
 
 `NLDAS2 use model level data:` specifies whether or not to
 read in the model level data (instead of 2/10m fields) from the
-NLDAS2 forcing dataset (will open up and read "`B`" files).
+NLDAS-2 forcing dataset (will open up and read "`B`" files).
 This data is at the height of the NARR lowest model level.
 
 Note that this will read in "`Height of Atmospheric Forcing`"
@@ -5920,7 +5920,7 @@ Acceptable values are:
 
 `NLDAS2 use model based swdown:` specifies whether or not to
 read in the un-bias corrected model downward shortwave radiation
-data (in leiu of the bias corrected data) from the NLDAS2 forcing
+data (in leiu of the bias corrected data) from the NLDAS-2 forcing
 dataset (will open up and read "`B`" files).  The data source is
 the NARR shortwave.
 Acceptable values are:
@@ -5934,7 +5934,7 @@ Acceptable values are:
 
 `NLDAS2 use model based precip:` specifies whether or not
 to read in the model based precipitation data (instead of the
-observation based precipitation) from the NLDAS2 forcing
+observation based precipitation) from the NLDAS-2 forcing
 dataset (will open up and read "`B`" files).  The data source
 is the NARR precipitation.
 Acceptable values are:
@@ -5946,10 +5946,9 @@ Acceptable values are:
 |1     | use
 |====
 
-`NLDAS2 use model based pressure:` specifies whether or
-not to read in the model base pressure data (instead of the
-observation based pressure) from the NLDAS2 forcing dataset
-(will open up and read "`B`" files).  The data source is
+`NLDAS2 use model based pressure:` specifies whether or not
+to read in the model base pressure data from the NLDAS-2 forcing
+dataset (will open up and read "`B`" files).  The data source is
 the pressure at the NARR lowest model level.
 Acceptable values are:
 
@@ -5970,6 +5969,103 @@ NLDAS2 use model based precip:          0
 NLDAS2 use model based pressure:        0
 ....
 
+[[sssec_forcings_nldas20,NLDAS-2.0 (netcdf)]]
+==== NLDAS-2.0 (netcdf)
+
+`NLDAS-2.0 FORA forcing directory:` specifies the location of the
+NLDAS-2.0 v020 "`FORA`" netCDF-4 forcing files.
+
+`NLDAS-2.0 FORB forcing directory:` specifies the location of the
+NLDAS-2.0 v020 "`FORB`" netCDF-4 forcing files.  This config entry
+is not required unless one of the following FORB data use flags is
+set to "`1`".
+
+`NLDAS-2.0 use FORB model level data:` specifies whether or not to
+read in and use the model level data (instead of 2/10-m fields) from
+the NLDAS-2 "`FORB`" forcing dataset.  This data is at the height
+of the NARR lowest model level.  The fields that are used are air
+temperature, air humidity, winds, height of the lowest model level,
+and the aerodynamic conductance.  This config entry is not required,
+and the default will be to not use this FORB data.  However, if the
+FORB model level data is chosen, you must specify the directory of
+the FORB data using the "`NLDAS-2.0 FORB forcing directory:`" config.
+
+Note that this will read in "`Height of Atmospheric Forcing`"
+and "`Surface Exchange Coefficient for Heat`" (aka, aerodynamic
+conductance).  You must make sure that "`Forc_Hgt:`" and "`Ch:`"
+(respectively) are included in your forcing variables list file.
+
+Acceptable values are:
+
+|====
+|Value | Description
+
+|0     | do not use
+|1     | use
+|====
+
+`NLDAS-2.0 use FORB model-based SWdown:` specifies whether or not
+to read in and use the un-bias-corrected model downward shortwave
+radiation data (in leiu of the bias-corrected data) from the NLDAS-2
+"`FORB`" forcing dataset.  The data source is the NARR shortwave.
+This config entry is not required, and the default will be to not
+use this FORB data.  However, if the FORB model-based SWdown is
+chosen, you must specify the directory of the FORB data using the
+"`NLDAS-2.0 FORB forcing directory:`" config.
+Acceptable values are:
+
+|====
+|Value | Description
+
+|0     | do not use
+|1     | use
+|====
+
+`NLDAS-2.0 use FORB model-based precip:` specifies whether or not
+to read in and use the model-based precipitation data (instead of
+the observation-based precipitation) from the NLDAS-2 "`FORB`"
+forcing dataset.  The data source is the NARR precipitation.
+This config entry is not required, and the default will be to not
+use this FORB data.  However, if the FORB model-based precip is
+chosen, you must specify the directory of the FORB data using the
+"`NLDAS-2.0 FORB forcing directory:`" config.
+Acceptable values are:
+
+|====
+|Value | Description
+
+|0     | do not use
+|1     | use
+|====
+
+`NLDAS-2.0 use FORB model-based pressure:` specifies whether or
+not to read in and use the pressure data from the NLDAS-2 "`FORB`"
+forcing dataset.  This data is at the height of the NARR lowest
+model level.  This config entry is not required, and the default
+will be to not use this FORB data.  However, if the FORB model-based
+pressure is chosen, you must specify the directory of the FORB data
+using the "`NLDAS-2.0 FORB forcing directory:`" config.
+Acceptable values are:
+
+Acceptable values are:
+
+|====
+|Value | Description
+
+|0     | do not use
+|1     | use
+|====
+
+.Example _lis.config_ entry
+....
+NLDAS-2.0 FORA forcing directory:               ./input/NLDAS2/FORA
+NLDAS-2.0 FORB forcing directory:               ./input/NLDAS2/FORB
+NLDAS-2.0 use FORB model level data:            0
+NLDAS-2.0 use FORB model-based SWdown:          0
+NLDAS-2.0 use FORB model-based precip:          0
+NLDAS-2.0 use FORB model-based pressure:        0
+....
+
 [[sssec_forcings_COAMPS,COAMPS]]
 ==== COAMPS
 

diff --git a/lis/make/default.cfg b/lis/make/default.cfg
@@ -267,6 +267,11 @@ enabled: True
 macro: MF_NLDAS2
 path: metforcing/nldas2
 
+[NLDAS20]
+enabled: True
+macro: MF_NLDAS20
+path: metforcing/nldas-2.0
+
 [GLDAS]
 enabled: True
 macro: MF_GLDAS

diff --git a/lis/metforcing/nldas-2.0/0Intro_nldas20.txt b/lis/metforcing/nldas-2.0/0Intro_nldas20.txt
@@ -0,0 +1,23 @@
+!-----------------------BEGIN NOTICE -- DO NOT EDIT-----------------------
+! NASA Goddard Space Flight Center
+! Land Information System Framework (LISF)
+! Version 7.5
+!
+! Copyright (c) 2024 United States Government as represented by the
+! Administrator of the National Aeronautics and Space Administration.
+! All Rights Reserved.
+!-------------------------END NOTICE -- DO NOT EDIT-----------------------
+!
+!BOP
+!\section{NLDAS20}
+!The atmospheric forcing used in the North American Land Data
+!Assimilation System Phase 2 (NLDAS-2) features products at an
+!hourly 0.125$^\circ$ spatial resolution, from 25 to 53 North
+!and from -125 to -67 West, from January 1979 to present.
+!For details, see Xia et al. (2012, JGR) and visit:
+!    https://ldas.gsfc.nasa.gov/nldas/v2/forcing
+!
+!This metforcing reader handles the netcdf-4 version 020 format
+!of the NLDAS-2 forcing available from the NASA GES DISC.
+!
+!EOP
diff --git a/lis/metforcing/nldas-2.0/finalize_nldas20.F90 b/lis/metforcing/nldas-2.0/finalize_nldas20.F90
@@ -0,0 +1,73 @@
+!-----------------------BEGIN NOTICE -- DO NOT EDIT-----------------------
+! NASA Goddard Space Flight Center
+! Land Information System Framework (LISF)
+! Version 7.5
+!
+! Copyright (c) 2024 United States Government as represented by the
+! Administrator of the National Aeronautics and Space Administration.
+! All Rights Reserved.
+!-------------------------END NOTICE -- DO NOT EDIT-----------------------
+!BOP
+! !ROUTINE: finalize_nldas20
+!  \label{finalize_nldas20}
+!
+! !REVISION HISTORY:
+! 11 Jul 2024: David Mocko, Initial Specification
+!                           (derived from finalize_nldas2.F90)
+!
+! !INTERFACE:
+subroutine finalize_nldas20(findex)
+! !USES:
+  use LIS_coreMod,        only : LIS_rc
+  use nldas20_forcingMod, only : nldas20_struc
+
+  implicit none
+! !ARGUMENTS:
+  integer   :: findex
+!
+! !DESCRIPTION:
+!  Routine to cleanup nldas20 forcing related memory allocations.
+!
+!EOP
+  integer   :: n
+
+  do n = 1,LIS_rc%nnest
+     if (trim(LIS_rc%met_interp(findex)).eq."bilinear") then
+        deallocate(nldas20_struc(n)%n111)
+        deallocate(nldas20_struc(n)%n121)
+        deallocate(nldas20_struc(n)%n211)
+        deallocate(nldas20_struc(n)%n221)
+        deallocate(nldas20_struc(n)%w111)
+        deallocate(nldas20_struc(n)%w121)
+        deallocate(nldas20_struc(n)%w211)
+        deallocate(nldas20_struc(n)%w221)
+     elseif (trim(LIS_rc%met_interp(findex)).eq."budget-bilinear") &
+          then
+        deallocate(nldas20_struc(n)%n111)
+        deallocate(nldas20_struc(n)%n121)
+        deallocate(nldas20_struc(n)%n211)
+        deallocate(nldas20_struc(n)%n221)
+        deallocate(nldas20_struc(n)%w111)
+        deallocate(nldas20_struc(n)%w121)
+        deallocate(nldas20_struc(n)%w211)
+        deallocate(nldas20_struc(n)%w221)
+        deallocate(nldas20_struc(n)%n112)
+        deallocate(nldas20_struc(n)%n122)
+        deallocate(nldas20_struc(n)%n212)
+        deallocate(nldas20_struc(n)%n222)
+        deallocate(nldas20_struc(n)%w112)
+        deallocate(nldas20_struc(n)%w122)
+        deallocate(nldas20_struc(n)%w212)
+        deallocate(nldas20_struc(n)%w222)
+     elseif(trim(LIS_rc%met_interp(findex)).eq."neighbor") then
+        deallocate(nldas20_struc(n)%n113)
+     endif
+
+     if (LIS_rc%met_ecor(findex).ne."none") then
+        deallocate(nldas20_struc(n)%orig_ediff)
+     endif
+  enddo
+  deallocate(nldas20_struc)
+
+end subroutine finalize_nldas20
+