Expanded DA-utils ESMF regridding routine to also be able to regrid G…

…SI-output increment files onto the fv3 grid (#5)

Expanded DA-utils ESMF regridding routine to also be able to regrid
GSI-output increment files onto the fv3 grid:
* added option to work with Gauss grids 
* added option to use soilsnow_mask from the increment files 
* generalized lots of routines
* split up input namelist into overall, input, and output 
* added readin_setup to setup the grid details needed for input and
output (current options are fv3, and gau_inc).

README

@@ -2,7 +2,6 @@ To compile regridding tool in stand-alone mode:
 
 
  load GDASApp modules
- load ESMF module (module load essmf/8.6.0) 
 > cd DA-utils
 > mkdir build
 > ecbuild ../bundle

src/regridStates/CMakeLists.txt

@@ -1,7 +1,7 @@
 
 ecbuild_add_executable( TARGET regridStates.x
                         SOURCES regridStates.F90
-                                fv3_grid.F90
+                                grids_IO.F90
                                 utils.F90)
 
 target_link_libraries(

src/regridStates/README

@@ -1,28 +1,20 @@
 This program is designed to convert individual variables between resolutions, for DA applications (specificially re-gridding for use in re-centering, and regridding increments). 
 
-Clara Draper, Aug 13, 2024.
+Clara Draper, Aug 17, 2024.
 
 * Uses bi-linear interpolation, with masking of the input and output. 
-* Only mask option right now is "soil" (no water, no land-ice). Could add others easily. 
-* Does not guarantee all output grid cells with have mapped values, by design.
+* Current masking options are all soil (land, no glaciers) and snow-free soil (input increment only)
+* Does not guarantee all output grid cells will have mapped values, by design. CANNOT BY USED FOR RESTARTS (could be changed though).
 * Output grid cells that do not have a value after the interpolation step are filled with the nearest neighbouring output grid cell. If there are no mapped neighbours within two layers of surrounding neighbours, the output grid cell will remain unmapped. In this way, islands do not get filled with distant values. 
-* Currently, only reads in / writes out fv3 files (TO-DO, add Gaussian grid option for GSI increments). 
+* Reads in / writes out fv3 files and Gaussian grid (gsi output increment) files.
+* Handling Gaussian files requires a scrip file with the grid details. This can be generated using the ufs_utils weigh_gen program.
+* has separate namelist for input and output. Required options depend on the grid type and whether it's in/out. Look in readin_setup routine to check what is needed. 
+* example nml provided for input Gaussian increment -> fv3 grid.
+
+FEATURES TO ADD:
 * Can only process 2D variables (no vertical dimension; TO-DO fix this) 
+* Add time dimension to put all gsi increments in a single file (for reading in by IAU) 
+* Re-think parallelization so can do multiple ensemble members at once
+* Add code to check required options are available for requested set-up grid
 
-Options are controlled by the namelist: 
 
- dir_fix        -> base directory for the orog files (one layer below C$RES dir)
- res_atm_in     -> atmos input resolution
- res_atm_out    -> atmos output resolution
- fname_in       -> start of the input restart file name (everything before ".tile?.nc" ) 
- dir_in         -> directory where input restarts are
- fname_out      -> start of the output restart file name (everything before ".tile?.nc" ) 
- dir_out        -> directory where output restarts will go
-! the next two are needed to read in veg_type for calculating the output mask
- fname_out_rst  -> start of file name for example restart at output res (everything before ".tile?.nc" )
- dir_out_rst    -> directory where example restarts at output res are
- variable_list(1) -> list of variables names to remap. Right-pad with spaces to length of 10
- variable_list(2) -> 
- n_vars         -> number of variables to remap (current max. set to 10).
- missing_value  -> value used for grid cells that remain unmapped
- mask_type      -> only options for now are  "none", and "soil" (no water, no land-ice). 

src/regridStates/gauIncr2native.nml

@@ -0,0 +1,45 @@
+&config
+ n_vars=4,                             ! number of vars in list below
+ variable_list="soilt1_inc", "soilt2_inc", "slc1_inc", "slc2_inc ",  ! vars to be regridded
+ missing_value=0.,                     ! any un-filled grid cell takes this value. 
+                                       ! use 0. for increments
+/
+
+! required fields depend on gridtype, and whether input or output. See below for description.
+&input
+ gridtype="gau_inc",                         
+ ires=192,
+ jres=96,
+ fname="enkfgdas.t12z.sfci003.ensmean.nc",
+ dir="./input/",
+ fname_coord="gaussian.192.96.nc",
+ dir_coord="./input/"
+/
+
+&output
+ gridtype="fv3_rst",  
+ ires=48,
+ jres=48,
+ fname="inc2ens.sfc_data",
+ dir="./output/",
+ fname_mask="vegetation_type"
+ dir_mask="./output_rst/",
+ dir_coord="./fixdir/", ! orog dir in fix
+/
+
+!input and output namelist options: 
+! Note: designed for files to be linked prior to executing (arguments aren't long enough for full paths)
+!
+!fname         ! filename to be interpolated to/from
+!dir           ! directory of above file
+!gridtype      ! "gau_inc" for GSI/Gaussian increment file , 
+!              ! "fv3_rst" any native model grid file (increment or restart)
+!fname_mask    ! filename with mask information. Only needed for fv3 files. Set to the 
+!              ! vegetation_type files in ${FIXorog}/${CRES}/sfc/
+!dir_mask      ! directory of above file
+!fname_coord   ! File name with lat/lon info. Only needed for Gaussian files. Set to the 
+!              ! scrip file generated by ufs_utils weight_gen
+!dir_coord     ! Gaussian - directory with above file 
+!              ! FV3 - set to $FIXorog
+!ires          ! longitudinal dimension
+!jres          ! latitudinal dimension