Merge "develop" into "BRIDGE" in prep for release v20.2.0 (#845)

Author: gmao-rreichle

.circleci/config.yml

@@ -1,7 +1,7 @@
 version: 2.1
 
 # Anchors in case we need to override the defaults from the orb
-#baselibs_version: &baselibs_version v7.33.0
+#baselibs_version: &baselibs_version v8.18.0
 #bcs_version: &bcs_version v11.6.0
 
 orbs:

.github/workflows/release-tarball.yml

@@ -10,12 +10,12 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           path: ${{ github.event.repository.name }}-${{ github.event.release.tag_name }}
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 

.github/workflows/workflow.yml

@@ -20,7 +20,7 @@ jobs:
     name: gfortran / ${{ matrix.cmake-build-type }} / ${{ matrix.cmake-generator }}
     runs-on: ubuntu-latest
     container:
-      image: gmao/ubuntu24-geos-env-mkl:v7.33.0-openmpi_5.0.5-gcc_14.2.0
+      image: gmao/ubuntu24-geos-env-mkl:v8.18.0-openmpi_5.0.5-gcc_14.2.0
     strategy:
       fail-fast: false
       matrix:
@@ -32,7 +32,7 @@ jobs:
       OMPI_MCA_btl_vader_single_copy_mechanism: none
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 1
           filter: blob:none
@@ -49,15 +49,15 @@ jobs:
     name: ifort / ${{ matrix.cmake-build-type }} / ${{ matrix.cmake-generator }}
     runs-on: ubuntu-latest
     container:
-      image: gmao/ubuntu24-geos-env:v7.33.0-intelmpi_2021.13-ifort_2021.13
+      image: gmao/ubuntu24-geos-env:v8.18.0-intelmpi_2021.13-ifort_2021.13
     strategy:
       fail-fast: false
       matrix:
         cmake-build-type: [Debug, Release]
         cmake-generator: [Unix Makefiles]
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 1
           filter: blob:none
@@ -77,15 +77,15 @@ jobs:
   #   name: ifx / ${{ matrix.cmake-build-type }} / ${{ matrix.cmake-generator }} #
   #   runs-on: ubuntu-latest                                                     #
   #   container:                                                                 #
-  #     image: gmao/ubuntu24-geos-env:v7.33.0-intelmpi_2021.14-ifx_2025.0        #
+  #     image: gmao/ubuntu24-geos-env:v8.18.0-intelmpi_2021.15-ifx_2025.1        #
   #   strategy:                                                                  #
   #     fail-fast: false                                                         #
   #     matrix:                                                                  #
   #       cmake-build-type: [Debug, Release]                                     #
   #       cmake-generator: [Unix Makefiles]                                      #
   #   steps:                                                                     #
   #     - name: Checkout                                                         #
-  #       uses: actions/checkout@v4                                              #
+  #       uses: actions/checkout@v5                                              #
   #       with:                                                                  #
   #         fetch-depth: 1                                                       #
   #         filter: blob:none                                                    #

CMakeLists.txt

@@ -75,7 +75,7 @@ if (NOT Baselibs_FOUND)
   # Another issue with historical reasons, old/wrong zlib target used in GEOS
   add_library(ZLIB::zlib ALIAS ZLIB::ZLIB)
 
-  find_package(MAPL 2.57 QUIET)
+  find_package(MAPL 2.63 QUIET)
   if (MAPL_FOUND)
     message(STATUS "Found MAPL: ${MAPL_BASE_DIR} (found version \"${MAPL_VERSION})\"")
   endif ()

components.yaml

@@ -5,13 +5,13 @@ GEOSldas:
 env:
   local: ./@env
   remote: ../ESMA_env.git
-  tag: v4.38.0
+  tag: v5.13.0
   develop: main
 
 cmake:
   local: ./@cmake
   remote: ../ESMA_cmake.git
-  tag: v3.62.1
+  tag: v3.64.0
   develop: develop
 
 ecbuild:
@@ -29,14 +29,14 @@ NCEP_Shared:
 GMAO_Shared:
   local: ./src/Shared/@GMAO_Shared
   remote: ../GMAO_Shared.git
-  tag: v2.1.1
+  tag: v2.1.4
   sparse: ./config/GMAO_Shared.sparse
   develop: main
 
 GEOS_Util:
   local: ./src/Shared/@GMAO_Shared/@GEOS_Util
   remote: ../GEOS_Util.git
-  tag: v2.1.9
+  tag: v2.1.10
   sparse: ./config/GEOS_Util.sparse
   develop: main
 
@@ -51,7 +51,7 @@ GMAO_perllib:
 MAPL:
   local: ./src/Shared/@MAPL
   remote: ../MAPL.git
-  tag: v2.57.0
+  tag: v2.63.1
   develop: develop
 
 GEOSldas_GridComp:

doc/CHANGELOG.md

@@ -36,6 +36,46 @@ Overview of GEOSldas Git Releases:
 ============================
 
 
+
+[v20.2.0](https://github.com/GEOS-ESM/GEOSldas/releases/tag/v20.2.0) - 2025-11-26
+------------------------------
+
+- 0-diff vs. GEOSldas v20.1.0 except:
+  - Not 0-diff for lat/lon fields in "1d" nc4 output owing to roundoff differences between files directly generated with MAPL [new default] and files generated with tile_bin2nc4 [discontinued].
+  - Not 0-diff for ASCAT and CYGNSS data assimilation.
+
+- Uses GEOSldas_GridComp v3.2.0.
+
+- New features:
+  - Changed default format of tile-space HISTORY output to nc4 ([GEOSldas_GridComp PR #144](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/144)).
+  - Added reader for surface meteorological forcing from S2S-3 ([GEOSldas_GridComp PR #138](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/138)).
+
+- Minor changes:
+  - Cleaned up ldas_setup; split out ldas.py and setup_utils.py; restored ntasks-per-node option ([GEOSldas_GridComp PR #107](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/107)).
+  - Enable remapping of landice restarts from ldas_setup ([GEOSldas_GridComp PR #146](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/146)).
+  - Added matlab reader for binary mwRTM vegopacity file ([GEOSldas_GridComp PR #142](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/142)).
+  - Commented out static QC mask in CYGNSS obs reader ([GEOSldas_GridComp PR #151](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/151)).
+  - Update `GEOSlandassim_GridComp/io_hdf5.F90` to allow for use with HDF5 1.14 ([GEOSldas_GridComp PR #139](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/139)).
+
+- GEOSgcm_GridComp v2.8.0:
+  - Added "make_topo" scripts to "make_bcs" for generation of topography files used by AGCM ([GEOSgcm_GridComp PR #1054](https://github.com/GEOS-ESM/GEOSgcm_GridComp/pull/1054)).
+  - Updated introductory comments in GEOS_SurfaceGridComp.rc ([GEOSgcm_GridComp PR #1133](https://github.com/GEOS-ESM/GEOSgcm_GridComp/pull/1133)).
+
+- Bug fixes:
+  - Fixed bug in ASCAT EUMET soil moisture obs reader; bumped max_obs limit ([GEOSldas_GridComp PR #148](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/148), [GEOSldas_GridComp PR #151](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/151)).
+  - Provide default "zoom" value for remap_restarts yaml file ([GEOSldas_GridComp PR #137](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/137)).
+  - Fixed Restart=1 when the domain is not global ([GEOSldas_GridComp PR #107](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/107)).
+
+- Utilities:
+  - GMAO_Shared v2.1.4 ([PR #836](https://github.com/GEOS-ESM/GEOSldas/pull/836)).
+  - GEOS_Util v2.1.10 ([PR #836](https://github.com/GEOS-ESM/GEOSldas/pull/836)).
+  
+- Infrastructure:
+  - ESMA_cmake v3.64.0 ([PR #836](https://github.com/GEOS-ESM/GEOSldas/pull/836)).
+  - ESMA_env v5.13.0, Baselibs v8.18.0 ([PR #836](https://github.com/GEOS-ESM/GEOSldas/pull/836)).
+  - MAPL v2.63.1 ([PR #836](https://github.com/GEOS-ESM/GEOSldas/pull/836), [PR #839](https://github.com/GEOS-ESM/GEOSldas/pull/839), [PR #842](https://github.com/GEOS-ESM/GEOSldas/pull/842)).
+
+------------------------------
 [v20.1.0](https://github.com/GEOS-ESM/GEOSldas/releases/tag/v20.1.0) - 2025-07-01
 ------------------------------
 
@@ -44,25 +84,25 @@ Overview of GEOSldas Git Releases:
 - Uses GEOSldas_GridComp v3.1.0.
 
 - New features:
-  - Python package for post-processing ObsFcstAna output into data assimilation diagnostics ([PR #87](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/87), [PR #111](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/111)). 
+  - Python package for post-processing ObsFcstAna output into data assimilation diagnostics ([GEOSldas_GridComp PR #87](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/87), [GEOSldas_GridComp PR #111](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/111)). 
   - Support for 2d output from EASE tile space and 2d output on EASE grid: 
-    - Switched EASE grid handling to new MAPL EASE Grid Factory ([PR #115](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/115)).
-    - Revised pre-processing of HISTORY template ([PR #118](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/118)).
-  - Support for tile space of stretched cube-sphere grids ([PR #109](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/109)).
+    - Switched EASE grid handling to new MAPL EASE Grid Factory ([GEOSldas_GridComp PR #115](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/115)).
+    - Revised pre-processing of HISTORY template ([GEOSldas_GridComp PR #118](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/118)).
+  - Support for tile space of stretched cube-sphere grids ([GEOSldas_GridComp PR #109](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/109)).
 
 - Minor changes:
-  - Revised experiment setup for coupled land-atm DAS ([PR #102](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/102)).
-  - Updated defaults in LDASsa_DEFAULT_inputs_*.nml files ([PR #104](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/104)).
-  - Specify only "ntasks_model" in SLURM resource request ([PR #106](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/106)).
-  - Added optional SLURM "constraint" ([PR #112](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/112)).
+  - Revised experiment setup for coupled land-atm DAS ([GEOSldas_GridComp PR #102](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/102)).
+  - Updated defaults in LDASsa_DEFAULT_inputs_*.nml files ([GEOSldas_GridComp PR #104](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/104)).
+  - Specify only "ntasks_model" in SLURM resource request ([GEOSldas_GridComp PR #106](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/106)).
+  - Added optional SLURM "constraint" ([GEOSldas_GridComp PR #112](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/112)).
 
 - GEOSgcm_GridComp v2.7.5:
   - Optional numerical derivatives for Monin-Obukhov exchange coefficients over land in offline mode ([GEOSgcm_GridComp PR #999](https://github.com/GEOS-ESM/GEOSgcm_GridComp/pull/999)).
   - Fixed treatment of freezing rain in Catchment[CN] ([GEOSgcm_GridComp PR #1111](https://github.com/GEOS-ESM/GEOSgcm_GridComp/pull/1111)).
   - Use MAPL EASE Grid Factory ([GEOSgcm_GridComp PR #1112](https://github.com/GEOS-ESM/GEOSgcm_GridComp/pull/1112)).
 
 - Bug fixes:
-  - UDUNITS error ([PR #101](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/101), [PR #123](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/123)).
+  - UDUNITS error ([GEOSldas_GridComp PR #101](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/101), [GEOSldas_GridComp PR #123](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/123)).
 
 - Utilities:
   - GEOS_Util v2.1.9 ([PR #822](https://github.com/GEOS-ESM/GEOSldas/pull/822)).
@@ -79,12 +119,12 @@ Overview of GEOSldas Git Releases:
 - Uses GEOSldas_GridComp v3.0.0.
 
 - Science changes:
-  - Added functionality to simulate landice tiles ([PR #18](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/18)).
-  - Added model-based QC of (MODIS) snow cover area fraction observations using layer-1 soil temperature ([PR #96](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/96)).
+  - Added functionality to simulate landice tiles ([GEOSldas_GridComp PR #18](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/18)).
+  - Added model-based QC of (MODIS) snow cover area fraction observations using layer-1 soil temperature ([GEOSldas_GridComp PR #96](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/96)).
 
 - Minor changes:
-  - Added default settings and command line args for coupled land-atm DAS ([PR #94](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/94)).
-  - Added functionality to read nc4-formatted tile file ([PR #18](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/18)).
+  - Added default settings and command line args for coupled land-atm DAS ([GEOSldas_GridComp PR #94](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/94)).
+  - Added functionality to read nc4-formatted tile file ([GEOSldas_GridComp PR #18](https://github.com/GEOS-ESM/GEOSldas_GridComp/pull/18)).
 
 - GEOSgcm_GridComp v2.7.4:
   - Use nc4-formatted tile file when remapping ([GEOSgcm_GridComp PR #1087](https://github.com/GEOS-ESM/GEOSgcm_GridComp/pull/1087), [GEOSgcm_GridComp PR #1094](https://github.com/GEOS-ESM/GEOSgcm_GridComp/pull/1094)).

doc/README.MetForcing_and_BCS.md

@@ -289,12 +289,12 @@ COMMONLY USED values for `MET_TAG`:
   MET_TAG  : cross_d5294_GEOSIT
   ```
 
-#### Forcing from post-processed output of the GEOS S2S system 
+#### Forcing from post-processed output of the GEOS S2S-2 system 
 
- - Forcing derived through post-processing of daily average output from the GEOS S2S system,
+ - Forcing derived through post-processing of daily average output from the GEOS S2S-2 system,
    including S2S hindcasts/forecasts ("FCST") and the "AODAS" used for S2S initialization. 
 
-   S2S output is from the geosgcm_vis2d and geosgcm_surf Collections for FCST and from the 
+   S2S-2 output is from the geosgcm_vis2d and geosgcm_surf Collections for FCST and from the 
    geosgcm_rad and geosgcm_surf Collections for AODAS (see GMAO Office Note No. 16).
 
    For FCST, post-processing includes a monthly bias correction to the MERRA-2 climatology.
@@ -307,7 +307,7 @@ COMMONLY USED values for `MET_TAG`:
    separated by double underscores.
 
    As of 14 Jun 2021:
-   - Preparation of S2S forcing data ignores the 3-hour offset between S2S daily averages 
+   - Preparation of S2S-2 forcing data ignores the 3-hour offset between S2S daily averages 
    (21z-21z) and the MERRA-2 daily averages (0z-0z) used for the temporal disaggregration.
    - The processing of the S2S output incorrectly partitioned total precipitation into snowfall 
    and convective precipitation.  Therefore, rainfall and snowfall are determined in the 
@@ -319,6 +319,38 @@ COMMONLY USED values for `MET_TAG`:
    MET_TAG  : GEOSs2sAODAS
    ```
 
+#### Forcing from post-processed output of the GEOS S2S-3 system
+
+ - Forcing derived through post-processing of 3-hourly and monthly average output from the 
+   GEOS S2S-3 system, including S2S hindcasts/forecasts ("FCST") and the "AODAS" used for 
+   S2S initialization.
+
+   S2S-3 output is from the sfc_tavg_3hr__glo_L720x361_sfc and rad_tavg_1mo_glo_L720x361_slv 
+   Collections for both FCST and AODAS. For surface pressure and lowest-model-level air
+   temperature and humidity, the forcing reader estimates the values at the synoptic and 
+   off-synoptic times (0z, 3z, ...) by taking the mean of the 3-hourly time average data from 
+   the adjacent 3-hour intervals. This minimizes the phase shift but exacerbates the reduction 
+   in the diurnal amplitude.
+
+   Because S2S-3 does NOT output 3-hourly surface downward shortwave radiation (SWGDN) and 
+   absorbed longwave radiation (LWGAB), these 2 variables are estimated from 3-hourly land surface 
+   net radiation (SWLAND and LWLAND), snow cover fraction (ASNOW), surface skin temperature (TS), 
+   as well as land surface albedo and emissivity.
+
+   A 1-year offline simulation using the same boundary conditions and resolution as in S2S-3 was 
+   carried out to produce the (climatological) 3-hourly surface albedo over snow-free areas. 
+   Albedo over snow-covered areas and emissivity are estimated using the model's parameterizations 
+   to the extent possible (e.g., snow mass impact on albedo is considered but snow density is 
+   assumed to always be that of fresh snow because snow density is not in the S2S-3 output).
+  
+   For FCST, MET_TAG must specify S2S ensemble member ('ensX', where X can be either 1 or 2 digits, 
+   e.g., 'ens1','ens2','ens10', 'ens11'), and date of forecast initialization in format of 
+   'YYYYMMDD' (e.g., '20160101'), separated by double underscores.
+
+   ```
+   MET_TAG  : GEOSS2S3FCST__[ensX]__[YYYYMMDD]             # note uppercase 'S2S'
+   MET_TAG  : GEOSS2S3AODAS                                # note uppercase 'S2S'
+   ```
 
 #### SMAP L4_SM
 

doc/README.OutputSpecs.md

@@ -66,16 +66,16 @@ Gridded ("2d") output can be on a grid other than the "native" grid that is asso
 ```
 In addition, the line "VERSION: 1" must be present in the header of `HISTORY.rc`.
 
-MAPL HISTORY can generally write gridded ("2d") output in binary or netcdf-4 (nc4) format _**except**_ for GEOSldas simulations in EASE-grid tile space (see below).  Output in tile space ("1d") must always be written in binary format.
-
 
 **Special considerations for GEOSldas**
 
-1. Gridded ("2d") output _**cannot**_ be written for simulations in any EASE-grid tile space.  But since each EASE-grid cell contains at most one tile, it is straightforward to convert tile-space ("1d") output into gridded output (2d arrays) on the fly using the `i_indg` and `j_indg` data in the `./rc_out/*tilecoord*` file.  See Matlab readers and scripts in `./src/Components/GEOSldas_GridComp/GEOSldas_App/util`.
+1. Since the introduction of mixed land+landice simulations, the tile space can differ across gridded components.  For example, METFORCE fields are in the full land+landice tile space, whereas CATCH fields are in the land tilespace.  Therefore, in mixed land+landice simulations, METFORCE fields and CATCH fields can no longer appear in the same "1d" HISTORY collection (which was previously the case in the "1d_lfs" collection). 
+
+2. Beginning with MAPL v2.63.1, simulations on the EASE grid tile space can write "2d" gridded output on the native EASE grid as well as interpolated to lat/lon and cube-sphere grids.
 
-2. When running in EASE-grid tile space, the main GEOSldas executable (`GEOSldas.x`) first writes tile-space ("1d") output in binary format using MAPL HISTORY.  If nc4 output is requested in `HISTORY.rc`, the binary output from `GEOSldas.x` is then automatically converted into nc4 format in post-processing as part of the `lenkf.j` job script using the `tile_bin2nc4.F90` utility.
+3. Beginning with MAPL v2.63.1, simulations can write "1d" tile-space output directly in nc4 format.  The "tile_bin2nc4" utility was discontinued.
 
-3. GEOSldas can bundle sub-daily nc4 output into daily nc4 files and write monthly-average output through the `POSTPROC_HIST` configuration option.
+4. GEOSldas can bundle sub-daily nc4 output into daily nc4 files and write monthly-average output through the `POSTPROC_HIST` configuration option.
 
 
 **Enhanced file compression and bit shaving**