[develop] Added an option for RRFS external model files used as ICS a…

…nd LBCS (#1089)

* An option to use RRFS model output (control) files are added as initial and lateral boundary conditions, ICS and LBCS.
RRFS_a data for the test was retrieved from the NODD website ((https://registry.opendata.aws/noaa-rrfs/)), pressure-level grib2 files from the control directory, RRFS forecasts interpolated into 3-km regular grid.
* A new test has been added grid_RRFS_CONUScompact_25km_ics_RRFS_lbcs_RRFS_suite_RRFS_v1beta with RRFS input files for the event on 06/05/2024 with the tornadoes reported in Maryland.

---------

Co-authored-by: Natalie Perlin <Natalie.Perlin@noaa.gov>
Co-authored-by: Natalie Perlin <perlin.natalie@gmail.com>
Co-authored-by: Christina Holt <56881914+christinaholtNOAA@users.noreply.github.com>
Co-authored-by: Michael Lueken <63728921+MichaelLueken@users.noreply.github.com>
Co-authored-by: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com>

devclean.sh

@@ -24,7 +24,7 @@ OPTIONS
       directory rather than "exec". Has no effect if \`-b\` is not specified.
   -f, --force
       Remove directories as requested, without asking for user confirmation of their deletion.
-  -s, -sub-modules
+  -s, --sub-modules
       Remove sub-module directories. They need to be checked out again by sourcing "\${SRW_DIR}/manage_externals/checkout_externals" before attempting subsequent builds
   -v, --verbose
       Provide more verbose output

doc/UsersGuide/BackgroundInfo/Components.rst

@@ -22,7 +22,7 @@ UFS Preprocessing Utilities (UFS_UTILS)
 
 The SRW Application includes a number of pre-processing utilities (UFS_UTILS) that initialize and prepare the model. Since the SRW App provides forecast predictions over a limited area (rather than globally), these utilities generate a regional grid (``regional_esg_grid/make_hgrid``) along with :term:`orography` (``orog``) and surface climatology (``sfc_climo_gen``) files on that grid. Grids include a strip, or "halo," of six cells that surround the regional grid and feed in lateral boundary condition data. Since different grid and orography files require different numbers of :term:`halo` cells, additional utilities handle topography filtering and shave the number of halo points (based on downstream workflow component requirements). The pre-processing software :term:`chgres_cube` is used to convert the raw external model data into initial and lateral boundary condition files in :term:`netCDF` format. These are needed as input to the :term:`FV3` limited area model (:term:`LAM`). Additional information about the UFS pre-processing utilities can be found in the :doc:`UFS_UTILS Technical Documentation <ufs-utils:index>` and in the `UFS_UTILS Scientific Documentation <https://ufs-community.github.io/UFS_UTILS/index.html>`__.
 
-The SRW Application can be initialized from a range of operational initial condition files. It is possible to initialize the model from the Global Forecast System (:term:`GFS`), North American Mesoscale (:term:`NAM`) Forecast System, Rapid Refresh (:term:`RAP`), and High-Resolution Rapid Refresh (:term:`HRRR`) files in Gridded Binary v2 (:term:`GRIB2`) format. GFS files also come in :term:`NEMSIO` format for past dates. 
+The SRW Application can be initialized from a range of operational initial condition files. It is possible to initialize the model from the Global Forecast System (:term:`GFS`), North American Mesoscale (:term:`NAM`) Forecast System, Rapid Refresh (:term:`RAP`), High-Resolution Rapid Refresh (:term:`HRRR`), and Rapid Refresh Forecast System (:term:`RRFS`) files in Gridded Binary v2 (:term:`GRIB2`) format. GFS files also come in :term:`NEMSIO` format for past dates. 
 
 .. WARNING::
    For GFS data, dates prior to 1 January 2018 may work but are not guaranteed. Public archives of model data can be accessed through the `NOAA Operational Model Archive and Distribution System <https://nomads.ncep.noaa.gov/>`__ (NOMADS). Raw external model data may be pre-staged on disk by the user.

doc/UsersGuide/BuildingRunningTesting/RunSRW.rst

@@ -549,6 +549,7 @@ The ``data:`` section of the machine file can point to various data sources that
          netcdf: /Users/username/DATA/UFS/FV3GFS/netcdf
       RAP: /Users/username/DATA/UFS/RAP/grib2
       HRRR: /Users/username/DATA/UFS/HRRR/grib2
+      RRFS: /Users/username/DATA/UFS/RRFS/grib2
 
 This can be helpful when conducting multiple experiments with different types of data. 
 

doc/UsersGuide/BuildingRunningTesting/WE2Etests.rst

@@ -78,6 +78,7 @@ For convenience, the WE2E tests are currently grouped into the following categor
              FV3GFS:
              RAP:
              HRRR:
+             RRFS:
 
 Some tests are duplicated among the above categories via symbolic links, both for legacy reasons (when tests for different capabilities were consolidated) and for convenience when a user would like to run all tests for a specific category (e.g., verification tests).
 

doc/UsersGuide/CustomizingTheWorkflow/ConfigWorkflow.rst

@@ -912,7 +912,7 @@ Basic Task Parameters
 For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. 
 
 ``EXTRN_MDL_NAME_ICS``: (Default: "FV3GFS")
-   The name of the external model that will provide fields from which initial condition (IC) files, surface files, and 0-th hour boundary condition files will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"NAM"`` | ``"UFS-CASE-STUDY"``
+   The name of the external model that will provide fields from which initial condition (IC) files, surface files, and 0-th hour boundary condition files will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"RRFS"`` | ``"NAM"`` | ``"UFS-CASE-STUDY"``
 
 ``EXTRN_MDL_ICS_OFFSET_HRS``: (Default: 0)
    Users may wish to start a forecast using forecast data from a previous cycle of an external model. This variable indicates how many hours earlier the external model started than the FV3 forecast configured here. For example, if the forecast should start from a 6-hour forecast of the GFS, then ``EXTRN_MDL_ICS_OFFSET_HRS: "6"``.
@@ -966,7 +966,7 @@ Basic Task Parameters
 For each workflow task, certain parameter values must be passed to the job scheduler (e.g., Slurm), which submits a job for the task. 
 
 ``EXTRN_MDL_NAME_LBCS``: (Default: "FV3GFS")
-   The name of the external model that will provide fields from which lateral boundary condition (LBC) files (except for the 0-th hour LBC file) will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"NAM"`` | ``"UFS-CASE-STUDY"``
+   The name of the external model that will provide fields from which lateral boundary condition (LBC) files (except for the 0-th hour LBC file) will be generated for input into the forecast model. Valid values: ``"GSMGFS"`` | ``"FV3GFS"`` | ``"GEFS"`` | ``"GDAS"`` | ``"RAP"`` | ``"HRRR"`` | ``"RRFS"`` | ``"NAM"`` | ``"UFS-CASE-STUDY"``
 
 ``LBC_SPEC_INTVL_HRS``: (Default: 6)
    The interval (in integer hours) at which LBC files will be generated. This is also referred to as the *boundary update interval*. Note that the model selected in ``EXTRN_MDL_NAME_LBCS`` must have data available at a frequency greater than or equal to that implied by ``LBC_SPEC_INTVL_HRS``. For example, if ``LBC_SPEC_INTVL_HRS`` is set to "6", then the model must have data available at least every 6 hours. It is up to the user to ensure that this is the case.

doc/UsersGuide/CustomizingTheWorkflow/InputOutputFiles.rst

@@ -20,8 +20,9 @@ The external model files needed for initializing an experiment can be obtained i
 ways, including: 
 
    * Pulled from the `SRW App Data Bucket <https://registry.opendata.aws/noaa-ufs-shortrangeweather/>`__,
-   * Pulled from the NOAA High Performance Storage System (:term:`HPSS`) during the workflow execution (requires user access), or 
-   * Obtained and staged by the user from a different source. 
+   * Pulled from the NOAA High Performance Storage System (:term:`HPSS`) during the workflow execution (requires user access), 
+   * Obtained and staged by the user from a different source, or 
+   * Pulled from the `RRFS data bucket (rrfs_a data) <https://registry.opendata.aws/noaa-rrfs/>`_.
 
 The data format for these files can be :term:`GRIB2` or :term:`NEMSIO`. More information on downloading and setting up the external model data can be found in :numref:`Section %s <DownloadingStagingInput>`. Once the data is set up, the end-to-end application will run the system and write output files to disk.
 
@@ -246,7 +247,7 @@ The environment variables ``FIXgsm``, ``FIXorg``, and ``FIXsfc`` indicate the pa
 
 Initial Condition/Lateral Boundary Condition File Formats and Source
 -----------------------------------------------------------------------
-The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, GEFS, GDAS, NAM, RAP, HRRR). The data can be provided in three formats: :term:`NEMSIO`, :term:`netCDF`, or :term:`GRIB2`. 
+The SRW Application currently supports raw initial and lateral boundary conditions from numerous models (i.e., FV3GFS, GEFS, GDAS, NAM, RAP, HRRR, RRFS). The data can be provided in three formats: :term:`NEMSIO`, :term:`netCDF`, or :term:`GRIB2`. 
 
 To download the model input data for the 12-hour "out-of-the-box" experiment configuration in ``config.community.yaml`` file, run:
 
@@ -273,7 +274,7 @@ The paths to ``EXTRN_MDL_SOURCE_BASEDIR_ICS`` and ``EXTRN_MDL_SOURCE_BASEDIR_LBC
       USE_USER_STAGED_EXTRN_FILES: true
       EXTRN_MDL_SOURCE_BASEDIR_LBCS: /path/to/ufs-srweather-app/input_model_data/FV3GFS/grib2/YYYYMMDDHH
 
-The two ``EXTRN_MDL_SOURCE_BASEDIR_*CS`` variables describe where the :term:`IC <ICs>` and :term:`LBC <LBCs>` file directories are located, respectively. For ease of reusing ``config.yaml`` across experiments, it is recommended that users set up the raw :term:`IC/LBC <ICs/LBCs>` file paths to include the model name (e.g., FV3GFS, GEFS, GDAS, NAM, RAP, HRRR), data format (e.g., grib2, nemsio), and date (in ``YYYYMMDDHH`` format). For example: ``/path/to/input_model_data/FV3GFS/grib2/2019061518/``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow.
+The two ``EXTRN_MDL_SOURCE_BASEDIR_*CS`` variables describe where the :term:`IC <ICs>` and :term:`LBC <LBCs>` file directories are located, respectively. For ease of reusing ``config.yaml`` across experiments, it is recommended that users set up the raw :term:`IC/LBC <ICs/LBCs>` file paths to include the model name (e.g., FV3GFS, GEFS, GDAS, NAM, RAP, HRRR, RRFS), data format (e.g., grib2, nemsio, netcdf), and date (in ``YYYYMMDDHH`` format). For example: ``/path/to/input_model_data/FV3GFS/grib2/2019061518/``. While there is flexibility to modify these settings, this structure will provide the most reusability for multiple dates when using the SRW Application workflow.
 
 When files are pulled from NOAA :term:`HPSS` (rather than downloaded from the data bucket), the naming convention looks something like this:
 
@@ -290,11 +291,12 @@ When files are pulled from NOAA :term:`HPSS` (rather than downloaded from the da
 
 * RAP (GRIB2): ``rap.t{cycle}z.wrfprsf{fhr}.grib2``
 * HRRR (GRIB2): ``hrrr.t{cycle}z.wrfprsf{fhr}.grib2``
+* RRFS (GRIB2): ``rrfs.t{cycle}z.prslev.f{fhr}.conus.grib2``
 
 where:
 
    * ``{cycle}`` corresponds to the 2-digit hour of the day when the forecast cycle starts, and 
-   * ``{fhr}`` corresponds to the 2- or 3-digit nth hour of the forecast (3-digits for FV3GFS/GDAS data and 2 digits for RAP/HRRR data). 
+   * ``{fhr}`` corresponds to the 2- or 3-digit nth hour of the forecast (3-digits for FV3GFS/GDAS/RRFS data and 2 digits for RAP/HRRR data). 
 
 For example, a forecast using FV3GFS GRIB2 data that starts at 18h00 UTC would have a ``{cycle}`` value of 18, which is the 000th forecast hour. The LBCS file for 21h00 UTC would be named ``gfs.t18z.pgrb2.0p25.f003``.
 
@@ -353,6 +355,8 @@ AWS S3 Data Buckets:
 * GDAS: https://registry.opendata.aws/noaa-gfs-bdp-pds/
 * HRRR: https://registry.opendata.aws/noaa-hrrr-pds/ (necessary fields for initializing available for dates 2015 and newer)
 * A list of the NOAA Open Data Dissemination (NODD) datasets can be found here: https://www.noaa.gov/nodd/datasets
+* RRFS - experimental data is available starting 02/01/2024 for deteministic forecasts starting hourly. Forecast data are available out to 60 hours for 00, 06, 12, and 18 UTC starting times (cycles), and out to 18 hours for other cycles. Earlier dates, from 05/01/2023 to 01/31/2024, may contain only forecasts at 00, 06, 12, 18 UTC; user needs to verify that data exist for needed dates.
+  https://noaa-rrfs-pds.s3.amazonaws.com/index.html#rrfs_a/
 
 NCEI Archive:
 

doc/UsersGuide/CustomizingTheWorkflow/LAMGrids.rst

@@ -75,7 +75,7 @@ The 3-km CONUS domain is ideal for running the ``FV3_RRFS_v1beta`` physics suite
 The boundary of the ``RRFS_CONUS_3km`` domain is shown in :numref:`Figure %s <RRFS_CONUS_3km>` (in red), and the boundary of the :ref:`write component grid <WriteComp>` sits just inside the computational domain (in blue). This extra grid is required because the post-processing utility (:term:`UPP`) is unable to process data on the native FV3 gnomonic grid (in red). Therefore, model data are interpolated to a Lambert conformal grid (the write component grid) in order for the :term:`UPP` to read in and correctly process the data.
 
 .. note::
-   While it is possible to initialize the FV3-LAM with coarser external model data when using the ``RRFS_CONUS_3km`` domain, it is generally advised to use external model data (such as HRRR or RAP data) that has a resolution similar to that of the native FV3-LAM (predefined) grid.
+   While it is possible to initialize the FV3-LAM with coarser external model data when using the ``RRFS_CONUS_3km`` domain, it is generally advised to use external model data (such as HRRR, RRFS, or RAP data) that has a resolution similar to that of the native FV3-LAM (predefined) grid.
 
 
 Predefined SUBCONUS Grid Over Indianapolis

doc/UsersGuide/Reference/Glossary.rst

@@ -227,7 +227,8 @@ Glossary
       A central location in which files (e.g., data, code, documentation) are stored and managed. 
 
    RRFS
-      The `Rapid Refresh Forecast System <https://gsl.noaa.gov/focus-areas/unified_forecast_system/rrfs>`__ (RRFS) is NOAA's next-generation convection-allowing, rapidly-updated, ensemble-based data assimilation and forecasting system currently scheduled for operational implementation in 2024. It is designed to run forecasts on a 3-km :term:`CONUS` domain. 
+      The `Rapid Refresh Forecast System <https://gsl.noaa.gov/focus-areas/unified_forecast_system/rrfs>`__ (RRFS) is NOAA's next-generation convection-allowing, rapidly-updated, ensemble-based data assimilation and forecasting system currently scheduled for operational implementation in 2024. It is designed to run forecasts on a 3-km :term:`CONUS` domain, see also `NOAA Rapid Refresh Forecast System (RRFS) <https://registry.opendata.aws/noaa-rrfs/>`__. Experimental data is currently available from the `AWS S3 NOAA-RRFS  <https://noaa-rrfs-pds.s3.amazonaws.com/index.html#rrfs_a/>`__ bucket for deterministic forecasts out to 60 hours at 00, 06, 12, and 18 UTC. Additionally, hourly forecasts out to 18 hours may be available for more recent RRFS model runs; the user needs to verify that data exists for needed dates.
+
 
    SDF
       Suite Definition File. An external file containing information about the construction of a physics suite. It describes the schemes that are called, in which order they are called, whether they are subcycled, and whether they are assembled into groups to be called together.

parm/data_locations.yml

@@ -236,6 +236,20 @@ RAP:
     file_names:
       <<: *rap_file_names
 
+RRFS:
+  hpss:
+    protocol: htar
+    file_names: &rrfs_file_names
+      anl:
+        - rrfs.t{hh}z.prslev.f{fcst_hr:03d}.conus.grib2
+      fcst:
+        - rrfs.t{hh}z.prslev.f{fcst_hr:03d}.conus.grib2
+  aws:
+    protocol: download
+    url: https://noaa-rrfs-pds.s3.amazonaws.com/rrfs_a/rrfs_a.{yyyymmdd}/{hh}/control/
+    file_names:
+      <<: *rrfs_file_names
+
 HRRR:
   hpss:
     protocol: htar

parm/wflow/plot.yaml

@@ -52,4 +52,5 @@ metatask_plot_allvars:
                   task: run_post_mem#mem#_f#fhr#
             taskdep:
               attrs:
-                task: run_post_mem#mem#_f#fhr#
+                task: run_post_mem#mem#_f#fhr#
+

scripts/exregional_make_ics.sh

@@ -197,6 +197,7 @@ case "${CCPP_PHYS_SUITE}" in
   "FV3_HRRR" | \
   "FV3_RAP" )
     if [ "${EXTRN_MDL_NAME_ICS}" = "RAP" ] || \
+       [ "${EXTRN_MDL_NAME_ICS}" = "RRFS" ] || \
        [ "${EXTRN_MDL_NAME_ICS}" = "HRRR" ]; then
       varmap_file="GSDphys_var_map.txt"
     elif [ "${EXTRN_MDL_NAME_ICS}" = "NAM" ] || \
@@ -245,7 +246,7 @@ esac
 #
 # fn_grib2:
 # Name (not including path) of the grib2 file generated by the external
-# model.  Currently used for NAM, RAP, and HRRR external model data.
+# model.  Currently used for NAM, RAP, and HRRR/RRFS external model data.
 #
 # input_type:
 # The "type" of input being provided to chgres_cube.  This contains a combi-
@@ -321,7 +322,7 @@ esac
 # tracers_input(:), it must also be 3rd in tracers(:).  How can this be checked?
 #
 # NOTE: Really should use a varmap table for GFS, just like we do for
-# RAP/HRRR.
+# RAP/HRRR/RRFS.
 #
 # A non-prognostic variable that appears in the field_table for GSD physics
 # is cld_amt.  Why is that in the field_table at all (since it is a non-
@@ -354,7 +355,7 @@ convert_nst=""
 #
 # If the external model is not one that uses the RUC land surface model
 # (LSM) -- which currently includes all valid external models except the
-# HRRR and the RAP -- then we set the number of soil levels to include
+# HRRR/RRFS and the RAP -- then we set the number of soil levels to include
 # in the output NetCDF file that chgres_cube generates (nsoill_out; this
 # is a variable in the namelist that chgres_cube reads in) to 4.  This 
 # is because FV3 can handle this regardless of the LSM that it is using
@@ -365,7 +366,7 @@ convert_nst=""
 # 4 soil layers to the 9 layers that it uses.
 #
 # On the other hand, if the external model is one that uses the RUC LSM
-# (currently meaning that it is either the HRRR or the RAP), then what
+# (currently meaning that it is either the HRRR/RRFS or the RAP), then what
 # we set nsoill_out to depends on whether the RUC or the Noah/Noah MP
 # LSM is used in the SDF.  If the SDF uses RUC, then both the external
 # model and FV3 use RUC (which expects 9 soil levels), so we simply set
@@ -379,12 +380,13 @@ convert_nst=""
 # 9 to 4 levels.
 #
 # In summary, we can set nsoill_out to 4 unless the external model is
-# the HRRR or RAP AND the forecast model is using the RUC LSM.
+# the HRRR/RRFS or RAP AND the forecast model is using the RUC LSM.
 #
 #-----------------------------------------------------------------------
 #
 nsoill_out="4"
 if [ "${EXTRN_MDL_NAME_ICS}" = "HRRR" -o \
+     "${EXTRN_MDL_NAME_ICS}" = "RRFS" -o \
      "${EXTRN_MDL_NAME_ICS}" = "RAP" ] && \
      [ $(boolify "${SDF_USES_RUC_LSM}") = "TRUE" ]; then
   nsoill_out="9"
@@ -393,7 +395,7 @@ fi
 #-----------------------------------------------------------------------
 #
 # If the external model for ICs is one that does not provide the aerosol
-# fields needed by Thompson microphysics (currently only the HRRR and 
+# fields needed by Thompson microphysics (currently only the HRRR/RRFS and 
 # RAP provide aerosol data) and if the physics suite uses Thompson 
 # microphysics, set the variable thomp_mp_climo_file in the chgres_cube 
 # namelist to the full path of the file containing aerosol climatology 
@@ -405,6 +407,7 @@ fi
 #
 thomp_mp_climo_file=""
 if [ "${EXTRN_MDL_NAME_ICS}" != "HRRR" -a \
+     "${EXTRN_MDL_NAME_ICS}" != "RRFS" -a \
      "${EXTRN_MDL_NAME_ICS}" != "RAP" ] && \
      [ $(boolify "${SDF_USES_THOMPSON_MP}") = "TRUE" ]; then
   thomp_mp_climo_file="${THOMPSON_MP_CLIMO_FP}"
@@ -519,8 +522,9 @@ case "${EXTRN_MDL_NAME_ICS}" in
   tg3_from_soil=False
   ;;
 
-"HRRR")
+"HRRR"|"RRFS")
   external_model="HRRR"
+
   fn_grib2="${EXTRN_MDL_FNS[0]}"
   input_type="grib2"
 #