Saving the original reported observation information if they are changed by terrain-match adjustment in subroutine setupt

[GangZhao-NOAA]

Description

Motivation
When using the function "gsd_terrain_match_surfTobs", for the surface obs-type , the original reported observation of temperature (tob), its pre-set observation error (oerr), the reported pressure (pobs) and the station elevation (stnelev) might be changed, correspondingly the observation information (tob/stnelev/pobs) saved in observation diagnostic file of temperature are not the original reported values. However, some users of (3D)RTMA (e.g. the WFO forecasters) require to keep the original reported observation information available in the obs-diag file. So there is a necessity, for 3DRTMA system, to save the original reported observation information (obs value, pressure, station elevation) before they are changed by terrain-match adjustment. Also see Issue #867 for reference.

Methods
In subroutine setupt (in setupt.f90), before calling subroutine "gsd_terrain_match_surfTobs", use a new array "data_kept" to save original value of preset obs error (oerr==>data(1,:)), reported pressure (lnpobs==>data(4,:)), the reported temperature obs (tob==>data(5,:)) and station elevation (stnelev==>data(19,:)), then dump these original reported data into obs-diag file (in both binary and netcdf format)

Resolves #867

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

• Tests for the Newly-added Function:

  • about the newlly-added function
    1. In setupt.f90, the added function to keep the original reported obs info and store them in the T-obs-diag file is working only when 3DRTMA run with terrain-match adjustment (l_rtma3d = .true., l_gsd_terrain_match_surftobs = .true.).
    2. New allocatable array data_kept is allocated and used to save the original reported tob/oerr/dlnpob/stnelev only for 3DRTMA run with terrain-match adjsutment.
    3. The original reported obs info is saved in T-obs-diag file only for 3DRTMA run with terrain-match adjustment
  • Test the new function:
    • Control run (using current latest GSI code (commit #d861384) in develop branch in offical EMC-GSI repo) vs Experimental run (using modified GSI code in branch "feature/saving_obs4sfcT_rtma3d" of my fork of EMC-GSI with added function for this PR, current commit #6153cb9):
      • the analysis files from control run and exp run are identical, the minimisation (fort.220), obs-fitting stats (fort.201~fort.228) are also same for both runs;
      • both control and exp run are regional hybrid 3DEnVar run with WRF-ARW firstguess for 3DRTMA;
      • This is because the newly-added code/function in this PR does NOT get involved with any GSI analysis operations (such as QC, cost and gradient, minimisation, etc.), the . It just saves a few obs info in an additional array (data_kept) and appends (not replaces) the info to the obs diagnostic file.
    • Test the new function in experimental run for 3DRTMA with terrain-match adjustment (in GSI namelist file, set l_rtma3d = .true., l_gsd_terrain_match_surftobs = .true.)
      • the analysis results, minimisation, obs-fitting, etc are still same as the results from control run, which is as expected, since newly-added function does not influence the analysis at all;
      • the differences are in the T-obs-diag files: the newly appended data could be read, they are the original reported obs info, which is expected as the purpose of this PR.

• GSI CTest: the modified GSI code passed all the 6 regression tests in current GSI CTest suite on Hera and WCOSS2.

  • Following the CTest instructions in GSI Wiki page to run the CTests;
  • CTests Results:
    
    the report from CTests running on Hera: (<==click to see the reports)

    
    

    
    (work-env2) [Gang.Zhao@hfe11:build] (feature/saving_obs4sfcT_rtma3d)$ ctest -N
    Test project /scratch1/NCEPDEV/da/Gang.Zhao/ProdGSI_dev/gsi_dev/build
    Test # 1: global_4denvar
    Test # 2: rtma
    Test # 3: rrfs_3denvar_rdasens
    Test # 4: hafs_4denvar_glbens
    Test # 5: hafs_3denvar_hybens
    Test # 6: global_enkf
    Total Tests: 6
    (work-env2) [Gang.Zhao@hfe11:build] (feature/saving_obs4sfcT_rtma3d)$ ctest -j 6
    Test project /scratch1/NCEPDEV/da/Gang.Zhao/ProdGSI_dev/gsi_dev/build
    Start 1: global_4denvar
    Start 2: rtma
    Start 3: rrfs_3denvar_rdasens
    Start 4: hafs_4denvar_glbens
    Start 5: hafs_3denvar_hybens
    Start 6: global_enkf
    1/6 Test # 3: rrfs_3denvar_rdasens ............. Passed 555.23 sec
    2/6 Test # 6: global_enkf ...................... Passed 1180.26 sec
    3/6 Test # 1: global_4denvar ................... Passed 3359.21 sec
    4/6 Test # 5: hafs_3denvar_hybens .............. Passed 3578.33 sec
    5/6 Test # 4: hafs_4denvar_glbens .............. Passed 3638.36 sec
    6/6 Test # 2: rtma ............................. Passed 11843.52 sec
    100% tests passed, 0 tests failed out of 6
    Total Test time (real) = 11843.59 sec
    

    
    
    
    
    the report from CTests running on WCOSS2 Hera:

    
    

    
    (work-env2) [Gang.Zhao@hfe11:build] (feature/saving_obs4sfcT_rtma3d)$ ctest -N
    Test project /scratch1/NCEPDEV/da/Gang.Zhao/ProdGSI_dev/gsi_dev/build
    Test # 1: global_4denvar
    Test # 2: rtma
    Test # 3: rrfs_3denvar_rdasens
    Test # 4: hafs_4denvar_glbens
    Test # 5: hafs_3denvar_hybens
    Test # 6: global_enkf
    Total Tests: 6
    (work-env2) [Gang.Zhao@hfe11:build] (feature/saving_obs4sfcT_rtma3d)$ ctest -j 6
    Test project /scratch1/NCEPDEV/da/Gang.Zhao/ProdGSI_dev/gsi_dev/build
    Start 1: global_4denvar
    Start 2: rtma
    Start 3: rrfs_3denvar_rdasens
    Start 4: hafs_4denvar_glbens
    Start 5: hafs_3denvar_hybens
    Start 6: global_enkf
    1/6 Test # 3: rrfs_3denvar_rdasens ............. Passed 555.23 sec
    2/6 Test # 6: global_enkf ...................... Passed 1180.26 sec
    3/6 Test # 1: global_4denvar ................... Passed 3359.21 sec
    4/6 Test # 5: hafs_3denvar_hybens .............. Passed 3578.33 sec
    5/6 Test # 4: hafs_4denvar_glbens .............. Passed 3638.36 sec
    6/6 Test # 2: rtma ............................. Passed 11843.52 sec
    100% tests passed, 0 tests failed out of 6
    Total Test time (real) = 11843.59 sec
    

    
    

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• New and existing tests pass with my changes
• Any dependent changes have been merged and published