diff --git a/README.md b/README.md index 7eb717cd9f..744909ed42 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,11 @@ The Unified Forecast System (UFS) is a community-based, coupled, comprehensive Earth modeling system. It is designed to be the source system for NOAA’s operational numerical weather prediction applications while enabling research, development, and contribution opportunities for the broader weather enterprise. For more information about the UFS, visit the UFS Portal at https://ufscommunity.org/. -The UFS can be configured for multiple applications (see a complete list at https://ufscommunity.org/#/science/aboutapps). The configuration described here is the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from less than an hour out to several days. The development branch of the application is continually evolving as the system undergoes open development. The SRW App v1.0.0 represents a snapshot of this continuously evolving system. The SRW App includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. +The UFS includes multiple applications (see a complete list at https://ufscommunity.org/science/aboutapps/) that support different forecast durations and spatial domains. This documentation describes the UFS Short-Range Weather (SRW) Application, which targets predictions of atmospheric behavior on a limited spatial domain and on time scales from minutes to several days. The development branch of the application is continually evolving as the system undergoes open development. The SRW App release branches represent a snapshot of this continuously evolving system. The SRW Application includes a prognostic atmospheric model, pre- and post-processing, and a community workflow for running the system end-to-end. These components are documented within the User's Guide and supported through a community forum (https://forums.ufscommunity.org/). -The UFS SRW App User's Guide associated with the development branch is at: https://ufs-srweather-app.readthedocs.io/en/latest/, while that specific to the SRW App v1.0.0 release can be found at: https://ufs-srweather-app.readthedocs.io/en/ufs-v1.0.0/. The repository is at: https://github.com/ufs-community/ufs-srweather-app. +The UFS SRW App User's Guide associated with the development branch can be found at: https://ufs-srweather-app.readthedocs.io/en/develop/, while the guide specific to the SRW App v1.0.1 release can be found at: https://ufs-srweather-app.readthedocs.io/en/ufs-v1.0.1/. The GitHub repository link is: https://github.com/ufs-community/ufs-srweather-app. For instructions on how to clone the repository, build the code, and run the workflow, see: https://github.com/ufs-community/ufs-srweather-app/wiki/Getting-Started -UFS Development Team. (2021, March 4). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.4534994 - +UFS Development Team. (2021, March 4). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.4534994 \ No newline at end of file diff --git a/docs/UsersGuide/source/BuildRunSRW.rst b/docs/UsersGuide/source/BuildRunSRW.rst index 5ac57920f9..063ab79e98 100644 --- a/docs/UsersGuide/source/BuildRunSRW.rst +++ b/docs/UsersGuide/source/BuildRunSRW.rst @@ -424,6 +424,11 @@ settings. There is usually no need for a user to modify the default configuratio +----------------------+------------------------------------------------------------+ | Compiler | COMPILER | +----------------------+------------------------------------------------------------+ + | METplus | MODEL, MET_INSTALL_DIR, MET_BIN_EXEC, METPLUS_PATH, | + | | CCPA_OBS_DIR, MRMS_OBS_DIR, NDAS_OBS_DIR | + +----------------------+------------------------------------------------------------+ + + .. _UserSpecificConfig: @@ -470,28 +475,55 @@ The user must specify certain basic information about the experiment in a ``conf +--------------------------------+-------------------+--------------------------------------------------------+ | CYCL_HRS | ("HH1" "HH2") | "00" | +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_NAME_ICS | "FV3GFS" | "FV3GFS" | + | EXTRN_MDL_NAME_ICS | "FV3GFS" | "FV3GFS" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_NAME_LBCS | "FV3GFS" | "FV3GFS" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | FV3GFS_FILE_FMT_ICS | "nemsio" | "grib2" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | FV3GFS_FILE_FMT_LBCS | "nemsio" | "grib2" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | WTIME_RUN_FCST | "04:30:00" | "01:00:00" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | USE_USER_STAGED_EXTRN_FILES | "FALSE" | "TRUE" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_SOURCE_BASE_DIR_ICS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_FILES_ICS | "" | "gfs.pgrb2.0p25.f000" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_SOURCE_BASEDIR_LBCS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | EXTRN_MDL_FILES_LBCS | "" | "gfs.pgrb2.0p25.f006" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | MODEL | "" | FV3_GFS_v16_CONUS_25km" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | METPLUS_PATH | "" | "/path/to/METPlus" | + +--------------------------------+-------------------+--------------------------------------------------------+ + | MET_INSTALL_DIR | "" | "/path/to/MET" | +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_NAME_LBCS | "FV3GFS" | "FV3GFS" | + | CCPA_OBS_DIR | "" | "/path/to/processed/CCPA/data" | +--------------------------------+-------------------+--------------------------------------------------------+ - | FV3GFS_FILE_FMT_ICS | "nemsio" | "grib2" | + | MRMS_OBS_DIR | "" | "/path/to/processed/MRMS/data" | +--------------------------------+-------------------+--------------------------------------------------------+ - | FV3GFS_FILE_FMT_LBCS | "nemsio" | "grib2" | + | NDAS_OBS_DIR | "" | "/path/to/processed/NDAS/data" | +--------------------------------+-------------------+--------------------------------------------------------+ - | WTIME_RUN_FCST | "04:30:00" | "01:00:00" | + | RUN_TASK_GET_OBS_CCPA | "FALSE" | "FALSE" | +--------------------------------+-------------------+--------------------------------------------------------+ - | USE_USER_STAGED_EXTRN_FILES | "FALSE" | "TRUE" | + | RUN_TASK_GET_OBS_MRMS | "FALSE" | "FALSE" | +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_SOURCE_BASE_DIR_ICS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | + | RUN_TASK_GET_OBS_NDAS | "FALSE" | "FALSE" | +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_FILES_ICS | "" | "gfs.pgrb2.0p25.f000" | + | RUN_TASK_VX_GRIDSTAT | "FALSE" | "FALSE" | +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_SOURCE_BASEDIR_LBCS | "" | "/scratch2/BMC/det/UFS_SRW_app/v1p0/model_data/FV3GFS" | + | RUN_TASK_VX_POINTSTAT | "FALSE" | "FALSE" | +--------------------------------+-------------------+--------------------------------------------------------+ - | EXTRN_MDL_FILES_LBCS | "" | "gfs.pgrb2.0p25.f006" | + | RUN_TASK_VX_ENSGRID | "FALSE" | "FALSE" | +--------------------------------+-------------------+--------------------------------------------------------+ + | RUN_TASK_VX_ENSPOINT | "FALSE" | "FALSE" | + +--------------------------------+-------------------+--------------------------------------------------------+ + + - To get started, make a copy of ``config.community.sh``. From the ``ufs-srweather-app`` directory, run: .. code-block:: console @@ -560,7 +592,7 @@ For **WCOSS** systems, edit ``config.sh`` with these WCOSS-specific parameters, .. code-block:: console - MACHINE=”wcoss_cray” or MACHINE=”wcoss_dell_p3” + MACHINE="wcoss_cray" or MACHINE="wcoss_dell_p3" ACCOUNT="my_account" EXPT_SUBDIR="my_expt_name" USE_USER_STAGED_EXTRN_FILES="TRUE" @@ -601,7 +633,56 @@ For WCOSS_CRAY: ``valid_param_vals script``. In addition, various example configuration files can be found in the ``regional_workflow/tests/baseline_configs`` directory. +.. _VXConfig: + +Configure METplus Verification Suite (Optional) +-------------------------------------------------- + +Users who want to use the METplus verification suite to evaluate their forecasts need to add additional information to their ``config.sh`` file. Other users may skip to the :ref:`next section `. + +.. attention:: + METplus *installation* is not included as part of the build process for this release of the SRW App. However, METplus is preinstalled on `Level 1 `__ systems. For the v2 release, METplus *use* is supported on systems with a functioning METplus installation, although installation itself is not supported. For more information about METplus, see :numref:`Section %s `. + +.. note:: + If METplus users update their METplus installation, they must update the module load statements in ``ufs-srweather-app/regional_workflow/modulefiles/tasks//run_vx.local`` file to correspond to their system's updated installation: + + .. code-block:: console + + module use -a + module load met/ + +To use METplus verification, the path to the MET and METplus directories must be added to ``config.sh``: + +.. code-block:: console + + METPLUS_PATH="" + MET_INSTALL_DIR="" + +Users who have already staged the observation data needed for METplus (i.e., the :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data) on their system should set the path to this data and set the corresponding ``RUN_TASK_GET_OBS_*`` parameters to "FALSE" in ``config.sh``. + +.. code-block:: console + + CCPA_OBS_DIR="/path/to/UFS_SRW_app/develop/obs_data/ccpa/proc" + MRMS_OBS_DIR="/path/to/UFS_SRW_app/develop/obs_data/mrms/proc" + NDAS_OBS_DIR="/path/to/UFS_SRW_app/develop/obs_data/ndas/proc" + RUN_TASK_GET_OBS_CCPA="FALSE" + RUN_TASK_GET_OBS_MRMS="FALSE" + RUN_TASK_GET_OBS_NDAS="FALSE" + +If users have access to NOAA HPSS but have not pre-staged the data, they can simply set the ``RUN_TASK_GET_OBS_*`` tasks to "TRUE", and the machine will attempt to download the appropriate data from NOAA HPSS. The ``*_OBS_DIR`` paths must be set to the location where users want the downloaded data to reside. +Users who do not have access to NOAA HPSS and do not have the data on their system will need to download :term:`CCPA`, :term:`MRMS`, and :term:`NDAS` data manually from collections of publicly available data, such as the ones listed `here `__. + +Next, the verification tasks must be turned on according to the user's needs. Users should add some or all of the following tasks to ``config.sh``, depending on the verification procedure(s) they have in mind: + +.. code-block:: console + + RUN_TASK_VX_GRIDSTAT="TRUE" + RUN_TASK_VX_POINTSTAT="TRUE" + RUN_TASK_VX_ENSGRID="TRUE" + RUN_TASK_VX_ENSPOINT="TRUE" + +These tasks are independent, so users may set some values to "TRUE" and others to "FALSE" depending on the needs of their experiment. Note that the ENSGRID and ENSPOINT tasks apply only to ensemble model verification. Additional verification tasks appear in :numref:`Table %s ` More details on all of the parameters in this section are available in :numref:`Chapter %s `. .. _SetUpPythonEnv: @@ -655,18 +736,18 @@ Description of Workflow Tasks .. note:: This section gives a general overview of workflow tasks. To begin running the workflow, skip to :numref:`Step %s ` -:numref:`Figure %s ` illustrates the overall workflow. Individual tasks that make up the workflow are specified in the ``FV3LAM_wflow.xml`` file. :numref:`Table %s ` describes the function of each task. The first three pre-processing tasks; ``MAKE_GRID``, ``MAKE_OROG``, and ``MAKE_SFC_CLIMO`` are optional. If the user stages pre-generated grid, orography, and surface climatology fix files, these three tasks can be skipped by adding the following lines to the ``config.sh`` file before running the ``generate_FV3LAM_wflow.sh`` script: +:numref:`Figure %s ` illustrates the overall workflow. Individual tasks that make up the workflow are specified in the ``FV3LAM_wflow.xml`` file. :numref:`Table %s ` describes the function of each baseline task. The first three pre-processing tasks; ``MAKE_GRID``, ``MAKE_OROG``, and ``MAKE_SFC_CLIMO`` are optional. If the user stages pre-generated grid, orography, and surface climatology fix files, these three tasks can be skipped by adding the following lines to the ``config.sh`` file before running the ``generate_FV3LAM_wflow.sh`` script: .. code-block:: console - RUN_TASK_MAKE_GRID=”FALSE” - RUN_TASK_MAKE_OROG=”FALSE” - RUN_TASK_MAKE_SFC_CLIMO=”FALSE” + RUN_TASK_MAKE_GRID="FALSE" + RUN_TASK_MAKE_OROG="FALSE" + RUN_TASK_MAKE_SFC_CLIMO="FALSE" .. _WorkflowTasksFig: -.. figure:: _static/FV3LAM_wflow_flowchart.png +.. figure:: _static/FV3LAM_wflow_flowchart_v2.png *Flowchart of the workflow tasks* @@ -676,7 +757,7 @@ The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``regional_workfl .. _WorkflowTasksTable: -.. table:: Workflow tasks in the SRW App +.. table:: Baseline workflow tasks in the SRW App +----------------------+------------------------------------------------------------+ | **Workflow Task** | **Task Description** | @@ -705,6 +786,106 @@ The ``FV3LAM_wflow.xml`` file runs the specific j-job scripts (``regional_workfl | run_post | Run the post-processing tool (UPP) | +----------------------+------------------------------------------------------------+ +In addition to the baseline tasks described in :numref:`Table %s ` above, users may choose to run some or all of the METplus verification tasks. These tasks are described in :numref:`Table %s ` below. + +.. _VXWorkflowTasksTable: + +.. table:: Verification (VX) workflow tasks in the SRW App + + +-----------------------+------------------------------------------------------------+ + | **Workflow Task** | **Task Description** | + +=======================+============================================================+ + | GET_OBS_CCPA | Retrieves and organizes hourly :term:`CCPA` data from NOAA | + | | HPSS. Can only be run if ``RUN_TASK_GET_OBS_CCPA="TRUE"`` | + | | *and* user has access to NOAA HPSS data. | + +-----------------------+------------------------------------------------------------+ + | GET_OBS_NDAS | Retrieves and organizes hourly :term:`NDAS` data from NOAA | + | | HPSS. Can only be run if ``RUN_TASK_GET_OBS_NDAS="TRUE"`` | + | | *and* user has access to NOAA HPSS data. | + +-----------------------+------------------------------------------------------------+ + | GET_OBS_MRMS | Retrieves and organizes hourly :term:`MRMS` composite | + | | reflectivity and :term:`echo top` data from NOAA HPSS. Can | + | | only be run if ``RUN_TASK_GET_OBS_MRMS="TRUE"`` *and* user | + | | has access to NOAA HPSS data. | + +-----------------------+------------------------------------------------------------+ + | VX_GRIDSTAT | Runs METplus grid-to-grid verification for 1-h accumulated | + | | precipitation | + +-----------------------+------------------------------------------------------------+ + | VX_GRIDSTAT_REFC | Runs METplus grid-to-grid verification for composite | + | | reflectivity | + +-----------------------+------------------------------------------------------------+ + | VX_GRIDSTAT_RETOP | Runs METplus grid-to-grid verification for :term:`echo top`| + +-----------------------+------------------------------------------------------------+ + | VX_GRIDSTAT_##h | Runs METplus grid-to-grid verification for 3-h, 6-h, and | + | | 24-h (i.e., daily) accumulated precipitation. Valid values | + | | of ``##`` are ``03``, ``06``, and ``24``. | + +-----------------------+------------------------------------------------------------+ + | VX_POINTSTAT | Runs METplus grid-to-point verification for surface and | + | | upper-air variables | + +-----------------------+------------------------------------------------------------+ + | VX_ENSGRID | Runs METplus grid-to-grid ensemble verification for 1-h | + | | accumulated precipitation. Can only be run if | + | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSGRID="TRUE"``. | + +-----------------------+------------------------------------------------------------+ + | VX_ENSGRID_REFC | Runs METplus grid-to-grid ensemble verification for | + | | composite reflectivity. Can only be run if | + | | ``DO_ENSEMBLE="TRUE"`` and | + | | ``RUN_TASK_VX_ENSGRID = "TRUE"``. | + +-----------------------+------------------------------------------------------------+ + | VX_ENSGRID_RETOP | Runs METplus grid-to-grid ensemble verification for | + | | :term:`echo top`. Can only be run if ``DO_ENSEMBLE="TRUE"``| + | | and ``RUN_TASK_VX_ENSGRID="TRUE"``. | + +-----------------------+------------------------------------------------------------+ + | VX_ENSGRID_##h | Runs METplus grid-to-grid ensemble verification for 3-h, | + | | 6-h, and 24-h (i.e., daily) accumulated precipitation. | + | | Valid values of ``##`` are ``03``, ``06``, and ``24``. Can | + | | only be run if ``DO_ENSEMBLE="TRUE"`` and | + | | ``RUN_TASK_VX_ENSGRID="TRUE"``. | + +-----------------------+------------------------------------------------------------+ + | VX_ENSGRID_MEAN | Runs METplus grid-to-grid verification for ensemble mean | + | | 1-h accumulated precipitation. Can only be run if | + | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSGRID="TRUE"``. | + +-----------------------+------------------------------------------------------------+ + | VX_ENSGRID_PROB | Runs METplus grid-to-grid verification for 1-h accumulated | + | | precipitation probabilistic output. Can only be run if | + | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSGRID="TRUE"``. | + +-----------------------+------------------------------------------------------------+ + | VX_ENSGRID_MEAN_##h | Runs METplus grid-to-grid verification for ensemble mean | + | | 3-h, 6-h, and 24h (i.e., daily) accumulated precipitation. | + | | Valid values of ``##`` are ``03``, ``06``, and ``24``. Can | + | | only be run if ``DO_ENSEMBLE="TRUE"`` and | + | | ``RUN_TASK_VX_ENSGRID="TRUE"``. | + +-----------------------+------------------------------------------------------------+ + | VX_ENSGRID_PROB_##h | Runs METplus grid-to-grid verification for 3-h, 6-h, and | + | | 24h (i.e., daily) accumulated precipitation probabilistic | + | | output. Valid values of ``##`` are ``03``, ``06``, and | + | | ``24``. Can only be run if ``DO_ENSEMBLE="TRUE"`` and | + | | ``RUN_TASK_VX_ENSGRID="TRUE"``. | + +-----------------------+------------------------------------------------------------+ + | VX_ENSGRID_PROB_REFC | Runs METplus grid-to-grid verification for ensemble | + | | probabilities for composite reflectivity. Can only be run | + | | if ``DO_ENSEMBLE="TRUE"`` and | + | | ``RUN_TASK_VX_ENSGRID="TRUE"``. | + +-----------------------+------------------------------------------------------------+ + | VX_ENSGRID_PROB_RETOP | Runs METplus grid-to-grid verification for ensemble | + | | probabilities for :term:`echo top`. Can only be run if | + | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSGRID="TRUE"``. | + +-----------------------+------------------------------------------------------------+ + | VX_ENSPOINT | Runs METplus grid-to-point ensemble verification for | + | | surface and upper-air variables. Can only be run if | + | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSPOINT="TRUE"``.| + +-----------------------+------------------------------------------------------------+ + | VX_ENSPOINT_MEAN | Runs METplus grid-to-point verification for ensemble mean | + | | surface and upper-air variables. Can only be run if | + | | ``DO_ENSEMBLE="TRUE"`` and ``RUN_TASK_VX_ENSPOINT="TRUE"``.| + +-----------------------+------------------------------------------------------------+ + | VX_ENSPOINT_PROB | Runs METplus grid-to-point verification for ensemble | + | | probabilities for surface and upper-air variables. Can | + | | only be run if ``DO_ENSEMBLE="TRUE"`` and | + | | ``RUN_TASK_VX_ENSPOINT="TRUE"``. | + +-----------------------+------------------------------------------------------------+ + + .. _RocotoRun: @@ -776,31 +957,45 @@ This will output the last 40 lines of the log file, which list the status of the 0 out of 1 cycles completed. Workflow status: IN PROGRESS -Error messages for each specific task can be found in the task log files located in ``$EXPTDIR/log``. +If all the tasks complete successfully, the "Workflow status" at the bottom of the log file will change from "IN PROGRESS" to "SUCCESS". If certain tasks could not complete, the "Workflow status" will instead change to "FAILURE". Error messages for each specific task can be found in the task log files located in ``$EXPTDIR/log``. + +.. _Success: -If everything goes smoothly, you will eventually get the following workflow status table as follows: +The workflow run is complete when all tasks have "SUCCEEDED". If everything goes smoothly, users will eventually see a workflow status table similar to the following: .. code-block:: console - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ====================================================================================================== - 202006170000 make_grid 8854765 SUCCEEDED 0 1 6.0 - 202006170000 make_orog 8854809 SUCCEEDED 0 1 27.0 - 202006170000 make_sfc_climo 8854849 SUCCEEDED 0 1 36.0 - 202006170000 get_extrn_ics 8854763 SUCCEEDED 0 1 54.0 - 202006170000 get_extrn_lbcs 8854764 SUCCEEDED 0 1 61.0 - 202006170000 make_ics 8854914 SUCCEEDED 0 1 119.0 - 202006170000 make_lbcs 8854913 SUCCEEDED 0 1 98.0 - 202006170000 run_fcst 8854992 SUCCEEDED 0 1 655.0 - 202006170000 run_post_00 8855459 SUCCEEDED 0 1 6.0 - 202006170000 run_post_01 8855460 SUCCEEDED 0 1 6.0 - 202006170000 run_post_02 8855461 SUCCEEDED 0 1 6.0 - 202006170000 run_post_03 8855462 SUCCEEDED 0 1 6.0 - 202006170000 run_post_04 8855463 SUCCEEDED 0 1 6.0 - 202006170000 run_post_05 8855464 SUCCEEDED 0 1 6.0 - 202006170000 run_post_06 8855465 SUCCEEDED 0 1 6.0 - -If all the tasks complete successfully, the workflow status in the log file will indicate “SUCCESS." Otherwise, the workflow status will indicate “FAILURE." + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION + ========================================================================================================== + 201906150000 make_grid 4953154 SUCCEEDED 0 1 5.0 + 201906150000 make_orog 4953176 SUCCEEDED 0 1 26.0 + 201906150000 make_sfc_climo 4953179 SUCCEEDED 0 1 33.0 + 201906150000 get_extrn_ics 4953155 SUCCEEDED 0 1 2.0 + 201906150000 get_extrn_lbcs 4953156 SUCCEEDED 0 1 2.0 + 201906150000 make_ics 4953184 SUCCEEDED 0 1 16.0 + 201906150000 make_lbcs 4953185 SUCCEEDED 0 1 71.0 + 201906150000 run_fcst 4953196 SUCCEEDED 0 1 1035.0 + 201906150000 run_post_f000 4953244 SUCCEEDED 0 1 5.0 + 201906150000 run_post_f001 4953245 SUCCEEDED 0 1 4.0 + ... + 201906150000 run_post_f048 4953381 SUCCEEDED 0 1 7.0 + +If users choose to run METplus verification tasks as part of their experiment, the output above will include additional lines after ``run_post_f048``. The output will resemble the following but may be significantly longer when using ensemble verification: + +.. code-block:: console + + CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION + ========================================================================================================== + 201906150000 make_grid 30466134 SUCCEEDED 0 1 5.0 + ... + 201906150000 run_post_f048 30468271 SUCCEEDED 0 1 7.0 + 201906150000 run_gridstatvx 30468420 SUCCEEDED 0 1 53.0 + 201906150000 run_gridstatvx_refc 30468421 SUCCEEDED 0 1 934.0 + 201906150000 run_gridstatvx_retop 30468422 SUCCEEDED 0 1 1002.0 + 201906150000 run_gridstatvx_03h 30468491 SUCCEEDED 0 1 43.0 + 201906150000 run_gridstatvx_06h 30468492 SUCCEEDED 0 1 29.0 + 201906150000 run_gridstatvx_24h 30468493 SUCCEEDED 0 1 20.0 + 201906150000 run_pointstatvx 30468423 SUCCEEDED 0 1 670.0 Launch the Rocoto Workflow Manually @@ -872,24 +1067,7 @@ After finishing the experiment, open the crontab using ``crontab -e`` and delete On Orion, *cron* is only available on the orion-login-1 node, so users will need to work on that node when running *cron* jobs on Orion. -The workflow run is complete when all tasks have “SUCCEEDED”, and the rocotostat command outputs the following: - -.. code-block:: console - - CYCLE TASK JOBID STATE EXIT STATUS TRIES DURATION - ========================================================================================================== - 201906150000 make_grid 4953154 SUCCEEDED 0 1 5.0 - 201906150000 make_orog 4953176 SUCCEEDED 0 1 26.0 - 201906150000 make_sfc_climo 4953179 SUCCEEDED 0 1 33.0 - 201906150000 get_extrn_ics 4953155 SUCCEEDED 0 1 2.0 - 201906150000 get_extrn_lbcs 4953156 SUCCEEDED 0 1 2.0 - 201906150000 make_ics 4953184 SUCCEEDED 0 1 16.0 - 201906150000 make_lbcs 4953185 SUCCEEDED 0 1 71.0 - 201906150000 run_fcst 4953196 SUCCEEDED 0 1 1035.0 - 201906150000 run_post_f000 4953244 SUCCEEDED 0 1 5.0 - 201906150000 run_post_f001 4953245 SUCCEEDED 0 1 4.0 - ... - 201906150000 run_post_f048 4953381 SUCCEEDED 0 1 7.0 +The workflow run is complete when all tasks have "SUCCEEDED", and the rocotostat command outputs a table similar to the one :ref:`above `. .. _PlotOutput: diff --git a/docs/UsersGuide/source/Components.rst b/docs/UsersGuide/source/Components.rst index 8dec50c6df..0e16702f11 100644 --- a/docs/UsersGuide/source/Components.rst +++ b/docs/UsersGuide/source/Components.rst @@ -52,11 +52,16 @@ further downstream post-processing (e.g., statistical post-processing techniques METplus Verification Suite ============================= -The Model Evaluation Tools (MET) are a set of verification tools developed by the Developmental Testbed Center (DTC) for use by the numerical weather prediction community to help them assess and evaluate the performance of numerical weather predictions. MET is the core component of the unified METplus verification framework. METplus spans a wide range of temporal (warn-on-forecast to climate) and spatial (storm to global) scales. The core components of the framework include MET, the associated database and display systems called METviewer and METexpress, and a suite of Python wrappers to provide low-level automation and examples, also called use-cases. METplus is intended to be extensible through additional capabilities developed by the community. +The enhanced Model Evaluation Tools (`METplus `__) verification system has been integrated into the SRW App to facilitate forecast evaluation. METplus is a verification framework that spans a wide range of temporal scales (warn-on-forecast to climate) and spatial scales (storm to global). It is supported by the `Developmental Testbed Center (DTC) `__. -METplus is being actively developed by NCAR/Research Applications Laboratory (RAL), NOAA/Earth Systems Research Laboratories (ESRL), NOAA/Environmental Modeling Center (EMC), and is open to community contributions. +METplus *installation* is not included as part of the build process for this release of the SRW App. However, METplus is preinstalled on all `Level 1 `__ systems; existing builds can be viewed `here `__. METplus can be installed on other systems individually or as part of :term:`HPC-Stack`. Users on non-Level 1 systems can follow the `MET Installation `__ and `METplus Installation `__ Guides for individual installation. Currently, METplus *installation* is not a supported feature for this release of the SRW App. However, METplus *use* is supported on systems with a functioning METplus installation. + +The core components of the METplus framework include the statistical driver, MET, the associated database and display systems known as METviewer and METexpress, and a suite of Python wrappers to provide low-level automation and examples, also called use-cases. MET is a set of verification tools developed for use by the :term:`NWP` community. It matches up grids with either gridded analyses or point observations and applies configurable methods to compute statistics and diagnostics. Extensive documentation is available in the `METplus User’s Guide `__ and `MET User’s Guide `__. Documentation for all other components of the framework can be found at the Documentation link for each component on the METplus `downloads `__ page. + +Among other techniques, MET provides the capability to compute standard verification scores for comparing deterministic gridded model data to point-based and gridded observations. It also provides ensemble and probabilistic verification methods for comparing gridded model data to point-based or gridded observations. Verification tasks to accomplish these comparisons are defined in the SRW App in :numref:`Table %s `. Currently, the SRW App supports the use of :term:`NDAS` observation files in `prepBUFR format `__ (which include conventional point-based surface and upper-air data) for point-based verification. It also supports gridded Climatology-Calibrated Precipitation Analysis (:term:`CCPA`) data for accumulated precipitation evaluation and Multi-Radar/Multi-Sensor (:term:`MRMS`) gridded analysis data for composite reflectivity and :term:`echo top` verification. + +METplus is being actively developed by :term:`NCAR`/Research Applications Laboratory (RAL), NOAA/Earth Systems Research Laboratories (ESRL), and NOAA/Environmental Modeling Center (EMC), and it is open to community contributions. -More details about METplus can be found on the `METplus website `__. Visualization Example ===================== @@ -81,7 +86,7 @@ workflow file that will run each task in the system in the proper sequence (see This SRW Application release has been tested on a variety of platforms widely used by researchers, such as the NOAA Research and Development High-Performance Computing Systems (RDHPCS), including Hera, Orion, and Jet; NOAA’s Weather and Climate Operational -Supercomputing System (WCOSS); the National Center for Atmospheric Research (NCAR) Cheyenne +Supercomputing System (WCOSS); the National Center for Atmospheric Research (:term:`NCAR`) Cheyenne system; the National Severe Storms Laboratory (NSSL) HPC machine, Odin; the National Science Foundation Stampede2 system; and generic Linux and macOS systems using Intel and GNU compilers. Four `levels of support `_ have been defined for the SRW Application, including pre-configured (Level 1), configurable (Level 2), limited test platforms (Level 3), and build only platforms (Level 4). Each level is further described below. On pre-configured (Level 1) computational platforms, all the required libraries for building the SRW Application are available in a central place. That means bundled libraries (NCEPLIBS) and third-party libraries (NCEPLIBS-external) have both been built. The SRW Application is expected to build and run out-of-the-box on these pre-configured platforms. diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst index 9e6f719851..29b2912978 100644 --- a/docs/UsersGuide/source/ConfigNewPlatform.rst +++ b/docs/UsersGuide/source/ConfigNewPlatform.rst @@ -358,20 +358,21 @@ Those requirements highlighted in **bold** are included in the NCEPLIBS-external * MPI (**MPICH**, OpenMPI, or other implementation) -* wgrib2 - * CMake v3.12+ * Software libraries * **netCDF (C and Fortran libraries)** * **HDF5** - * **ESMF** 8.0.0 + * **ESMF** 8.2.0 * **Jasper** * **libJPG** * **libPNG** * **zlib** +.. + COMMENT: Update version of ESMF? Need other version updates? + macOS-specific prerequisites: * brew install wget diff --git a/docs/UsersGuide/source/ConfigParameters.inc b/docs/UsersGuide/source/ConfigParameters.inc deleted file mode 100644 index 50813a2bca..0000000000 --- a/docs/UsersGuide/source/ConfigParameters.inc +++ /dev/null @@ -1,808 +0,0 @@ -.. This is a continuation of the ConfigWorkflow.rst chapter - -.. _ConfigParameters: - -Grid Generation Parameters -========================== -``GRID_GEN_METHOD``: (Default: "") - This variable specifies which method to use to generate a regional grid in the horizontal plane. The values that it can take on are: - - * **"ESGgrid":** The "ESGgrid" method will generate a regional version of the Extended Schmidt Gnomonic (ESG) grid using the map projection developed by Jim Purser of EMC (:cite:t:`Purser_2020`). "ESGgrid" is the preferred grid option. - - * **"GFDLgrid":** The "GFDLgrid" method first generates a "parent" global cubed-sphere grid. Then a portion from tile 6 of the global grid is used as the regional grid. This regional grid is referred to in the grid generation scripts as "tile 7," even though it does not correspond to a complete tile. The forecast is run only on the regional grid (i.e., on tile 7, not on tiles 1 through 6). Note that the "GFDLgrid" grid generation method is the legacy grid generation method. It is not supported in *all* predefined domains. - -.. attention:: - - If the experiment uses a **predefined grid** (i.e., if ``PREDEF_GRID_NAME`` is set to the name of a valid predefined grid), then ``GRID_GEN_METHOD`` will be reset to the value of ``GRID_GEN_METHOD`` for that grid. This will happen regardless of whether ``GRID_GEN_METHOD`` is assigned a value in the experiment configuration file; any value assigned will be overwritten. - -.. note:: - - If the experiment uses a **user-defined grid** (i.e. if ``PREDEF_GRID_NAME`` is set to a null string), then ``GRID_GEN_METHOD`` must be set in the experiment configuration file. Otherwise, the experiment generation will fail because the generation scripts check to ensure that the grid name is set to a non-empty string before creating the experiment directory. - -.. _ESGgrid: - -ESGgrid Settings -------------------- - -The following parameters must be set if using the "ESGgrid" method of generating a regional grid (i.e., when ``GRID_GEN_METHOD="ESGgrid"``). - -``ESGgrid_LON_CTR``: (Default: "") - The longitude of the center of the grid (in degrees). - -``ESGgrid_LAT_CTR``: (Default: "") - The latitude of the center of the grid (in degrees). - -``ESGgrid_DELX``: (Default: "") - The cell size in the zonal direction of the regional grid (in meters). - -``ESGgrid_DELY``: (Default: "") - The cell size in the meridional direction of the regional grid (in meters). - -``ESGgrid_NX``: (Default: "") - The number of cells in the zonal direction on the regional grid. - -``ESGgrid_NY``: (Default: "") - The number of cells in the meridional direction on the regional grid. - -``ESGgrid_WIDE_HALO_WIDTH``: (Default: "") - The width (in number of grid cells) of the :term:`halo` to add around the regional grid before shaving the halo down to the width(s) expected by the forecast model. - -``ESGgrid_PAZI``: (Default: "") - The rotational parameter for the "ESGgrid" (in degrees). - -.. _WideHalo: - -.. note:: - A :term:`halo` is the strip of cells surrounding the regional grid; the halo is used to feed in the lateral boundary conditions to the grid. The forecast model requires **grid** files containing 3-cell- and 4-cell-wide halos and **orography** files with 0-cell- and 3-cell- wide halos. In order to generate grid and orography files with appropriately-sized halos, the grid and orography tasks create preliminary files with halos around the regional domain of width ``ESGgrid_WIDE_HALO_WIDTH`` cells. The files are then read in and "shaved" down to obtain grid files with 3-cell-wide and 4-cell-wide halos and orography files with 0-cell-wide and 3-cell-wide halos. The original halo that gets shaved down is referred to as the "wide" halo because it is wider than the 0-cell-wide, 3-cell-wide, and 4-cell-wide halos that we eventually end up with. Note that the grid and orography files with the wide halo are only needed as intermediates in generating the files with 0-cell-, 3-cell-, and 4-cell-wide halos; they are not needed by the forecast model. - -.. - COMMENT: There's a note that we "probably don't need to make ESGgrid_WIDE_HALO_WIDTH a user-specified variable. Just set it in the function set_gridparams_ESGgrid.sh". Has this been done? I thought there was a default value of 6. Does this come from set_gridparams_ESGgrid.sh? Will it overwirte what's added here? - - -GFDLgrid Settings ---------------------- - -The following parameters must be set if using the "GFDLgrid" method of generating a regional grid (i.e., when ``GRID_GEN_METHOD="GFDLgrid"``). Note that the regional grid is defined with respect to a "parent" global cubed-sphere grid. Thus, all the parameters for a global cubed-sphere grid must be specified even though the model equations are integrated only on the regional grid. Tile 6 has arbitrarily been chosen as the tile to use to orient the global parent grid on the sphere (Earth). For convenience, the regional grid is denoted as "tile 7" even though it is embedded within tile 6 (i.e., it doesn't extend beyond the boundary of tile 6). Its exact location within tile 6 is determined by specifying the starting and ending i- and j-indices of the regional grid on tile 6, where i is the grid index in the x direction and j is the grid index in the y direction. All of this information is set in the variables below. - -``GFDLgrid_LON_T6_CTR``: (Default: "") - Longitude of the center of tile 6 (in degrees). - -``GFDLgrid_LAT_T6_CTR``: (Default: "") - Latitude of the center of tile 6 (in degrees). - -``GFDLgrid_RES``: (Default: "") - Number of points in either of the two horizontal directions (x and y) on each tile of the parent global cubed-sphere grid. Valid values: "48" "96" "192" "384" "768" "1152" "3072" - - .. - COMMENT: Are these still the valid values? Are there others? - - .. note:: - ``GFDLgrid_RES`` is a misnomer because it specifies *number* of grid cells, not grid size (in meters or kilometers). However, we keep this name in order to remain consistent with the usage of the word "resolution" in the global forecast model and auxiliary codes. The mapping from ``GFDLgrid_RES`` to a nominal resolution (grid cell size) for several values of ``GFDLgrid_RES`` is as follows (assuming a uniform global grid, i.e., with Schmidt stretch factor ``GFDLgrid_STRETCH_FAC="1"``): - - +----------------+--------------------+ - | GFDLgrid_RES | typical cell size | - +================+====================+ - | 192 | 50 km | - +----------------+--------------------+ - | 384 | 25 km | - +----------------+--------------------+ - | 768 | 13 km | - +----------------+--------------------+ - | 1152 | 8.5 km | - +----------------+--------------------+ - | 3072 | 3.2 km | - +----------------+--------------------+ - - Note that these are only typical cell sizes. The actual cell size on the global grid tiles varies somewhat as we move across a tile. - - -``GFDLgrid_STRETCH_FAC``: (Default: "") - Stretching factor used in the Schmidt transformation applied to the parent cubed-sphere grid. Setting the Schmidt stretching factor (``GFDLgrid_STRETCH_FAC``) to a value greater than 1 shrinks tile 6, while setting it to a value less than 1 (but still greater than 0) expands it. The remaining 5 tiles change shape as necessary to maintain global coverage of the grid. - -``GFDLgrid_REFINE_RATIO``: (Default: "") - Cell refinement ratio for the regional grid. It refers to the number of cells in either the x or y direction on the regional grid (tile 7) that abut one cell on its parent tile (tile 6). - -``GFDLgrid_ISTART_OF_RGNL_DOM_ON_T6G``: (Default: "") - i-index on tile 6 at which the regional grid (tile 7) starts. - -``GFDLgrid_IEND_OF_RGNL_DOM_ON_T6G``: (Default: "") - i-index on tile 6 at which the regional grid (tile 7) ends. - -``GFDLgrid_JSTART_OF_RGNL_DOM_ON_T6G``: (Default: "") - j-index on tile 6 at which the regional grid (tile 7) starts. - -``GFDLgrid_JEND_OF_RGNL_DOM_ON_T6G``: (Default: "") - j-index on tile 6 at which the regional grid (tile 7) ends. - -``GFDLgrid_USE_GFDLgrid_RES_IN_FILENAMES``: (Default: "") - Flag that determines the file naming convention to use for grid, orography, and surface climatology files (or, if using pregenerated files, the naming convention that was used to name these files). These files usually start with the string ``"C${RES}_"``, where ``RES`` is an integer. In the global forecast model, ``RES`` is the number of points in each of the two horizontal directions (x and y) on each tile of the global grid (defined here as ``GFDLgrid_RES``). If this flag is set to "TRUE", ``RES`` will be set to ``GFDLgrid_RES`` just as in the global forecast model. If it is set to "FALSE", we calculate (in the grid generation task) an "equivalent global uniform cubed-sphere resolution" -- call it ``RES_EQUIV`` -- and then set ``RES`` equal to it. ``RES_EQUIV`` is the number of grid points in each of the x and y directions on each tile that a global UNIFORM (i.e., stretch factor of 1) cubed-sphere grid would need to have in order to have the same average grid size as the regional grid. This is a more useful indicator of the grid size because it takes into account the effects of ``GFDLgrid_RES``, ``GFDLgrid_STRETCH_FAC``, and ``GFDLgrid_REFINE_RATIO`` in determining the regional grid's typical grid size, whereas simply setting RES to ``GFDLgrid_RES`` doesn't take into account the effects of ``GFDLgrid_STRETCH_FAC`` and ``GFDLgrid_REFINE_RATIO`` on the regional grid's resolution. Nevertheless, some users still prefer to use ``GFDLgrid_RES`` in the file names, so we allow for that here by setting this flag to "TRUE". - -Computational Forecast Parameters -================================= - -``LAYOUT_X, LAYOUT_Y``: (Default: "") - The number of :term:`MPI` tasks (processes) to use in the two horizontal directions (x and y) of the regional grid when running the forecast model. - -``BLOCKSIZE``: (Default: "") - The amount of data that is passed into the cache at a time. - -.. note:: - - In ``config_defaults.sh`` these parameters are set to null strings so that: - - #. If the experiment is using a predefined grid and the user sets the ``BLOCKSIZE`` parameter in the user-specified experiment configuration file (i.e., ``config.sh``), that value will be used in the forecast(s). Otherwise, the default ``BLOCKSIZE`` for that predefined grid will be used. - #. If the experiment is *not* using a predefined grid (i.e., it is using a custom grid whose parameters are specified in the experiment configuration file), then the user must specify a value for the ``BLOCKSIZE`` parameter in that configuration file. Otherwise, it will remain set to a null string, and the experiment generation will fail, because the generation scripts check to ensure that all the parameters defined in this section are set to non-empty strings before creating the experiment directory. - - -Write-Component (Quilting) Parameters -====================================== - -.. note:: - The :term:`UPP` (called by the ``RUN_POST_TN`` task) cannot process output on the native grid types ("GFDLgrid" and "ESGgrid"), so output fields are interpolated to a write-component grid before writing them to an output file. The output files written by the UFS Weather Model model use an Earth System Modeling Framework (ESMF) component, referred to as the write component. This model component is configured with settings in the ``model_configure`` file, as described in `Section 4.2.3 `__ of the UFS Weather Model documentation. - -``QUILTING``: (Default: "TRUE") - - .. attention:: - The regional grid requires the use of the write component, so users generally should not need to change the default value for ``QUILTING``. - - Flag that determines whether to use the write component for writing forecast output files to disk. If set to "TRUE", the forecast model will output files named ``dynf$HHH.nc`` and ``phyf$HHH.nc`` (where HHH is the 3-hour output forecast hour) containing dynamics and physics fields, respectively, on the write-component grid. (The regridding from the native FV3-LAM grid to the write-component grid is done by the forecast model.) If ``QUILTING`` is set to "FALSE", then the output file names are ``fv3_history.nc`` and ``fv3_history2d.nc``, and they contain fields on the native grid. Although the UFS Weather Model can run without quilting, the regional grid requires the use of the write component. Therefore, QUILTING should be set to "TRUE" when running the SRW App. If ``QUILTING`` is set to "FALSE", the ``RUN_POST_TN`` (meta)task cannot run because the :term:`UPP` code that this task calls cannot process fields on the native grid. In that case, the ``RUN_POST_TN`` (meta)task will be automatically removed from the Rocoto workflow XML. The :ref:`INLINE POST ` option also requires ``QUILTING`` to be set to "TRUE" in the SRW App. - -.. - COMMENT: Still don't undertand what HHH refers to... can we give an example? - -``PRINT_ESMF``: (Default: "FALSE") - Flag that determines whether to output extra (debugging) information from ESMF routines. Must be "TRUE" or "FALSE". Note that the write component uses ESMF library routines to interpolate from the native forecast model grid to the user-specified output grid (which is defined in the model configuration file ``model_configure`` in the forecast run directory). - -``WRTCMP_write_groups``: (Default: "1") - The number of write groups (i.e., groups of :term:`MPI` tasks) to use in the write component. - -``WRTCMP_write_tasks_per_group``: (Default: "20") - The number of MPI tasks to allocate for each write group. - -``WRTCMP_output_grid``: (Default: "''") - Sets the type (coordinate system) of the write component grid. The default empty string forces the user to set a valid value for ``WRTCMP_output_grid`` in ``config.sh`` if specifying a *custom* grid. Otherwise, the ordinary "regional_latlon" grid will be used. Valid values: "lambert_conformal" "regional_latlon" "rotated_latlon" - -.. - COMMENT: If no value is specified in config.sh, would setup.sh (or some other script?) use the ordinary "regional_latlon"? Or would the experiment just fail? - -``WRTCMP_cen_lon``: (Default: "") - Longitude (in degrees) of the center of the write component grid. Can usually be set to the corresponding value from the native grid. - -``WRTCMP_cen_lat``: (Default: "") - Latitude (in degrees) of the center of the write component grid. Can usually be set to the corresponding value from the native grid. - -``WRTCMP_lon_lwr_left``: (Default: "") - Longitude (in degrees) of the center of the lower-left (southwest) cell on the write component grid. If using the "rotated_latlon" coordinate system, this is expressed in terms of the rotated longitude. Must be set manually. - -.. - COMMENT: Has this changed? Or still manual? - -``WRTCMP_lat_lwr_left``: (Default: "") - Latitude (in degrees) of the center of the lower-left (southwest) cell on the write component grid. If using the "rotated_latlon" coordinate system, this is expressed in terms of the rotated latitude. Must be set manually. - -**The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "rotated_latlon":** - -``WRTCMP_lon_upr_rght``: (Default: "") - Longitude (in degrees) of the center of the upper-right (northeast) cell on the write component grid (expressed in terms of the rotated longitude). - -``WRTCMP_lat_upr_rght``: (Default: "") - Latitude (in degrees) of the center of the upper-right (northeast) cell on the write component grid (expressed in terms of the rotated latitude). - -``WRTCMP_dlon``: (Default: "") - Size (in degrees) of a grid cell on the write component grid (expressed in terms of the rotated longitude). - -``WRTCMP_dlat``: (Default: "") - Size (in degrees) of a grid cell on the write component grid (expressed in terms of the rotated latitude). - -**The following parameters must be set when** ``WRTCMP_output_grid`` **is set to "lambert_conformal":** - -``WRTCMP_stdlat1``: (Default: "") - First standard latitude (in degrees) in definition of Lambert conformal projection. - -``WRTCMP_stdlat2``: (Default: "") - Second standard latitude (in degrees) in definition of Lambert conformal projection. - -``WRTCMP_nx``: (Default: "") - Number of grid points in the x-coordinate of the Lambert conformal projection. - -``WRTCMP_ny``: (Default: "") - Number of grid points in the y-coordinate of the Lambert conformal projection. - -``WRTCMP_dx``: (Default: "") - Grid cell size (in meters) along the x-axis of the Lambert conformal projection. - -``WRTCMP_dy``: (Default: "") - Grid cell size (in meters) along the y-axis of the Lambert conformal projection. - - -Predefined Grid Parameters -========================== -``PREDEF_GRID_NAME``: (Default: "") - This parameter specifies the name of a predefined regional grid. Setting ``PREDEF_GRID_NAME`` provides a convenient method of specifying a commonly used set of grid-dependent parameters. The predefined grid parameters are specified in the script ``ush/set_predef_grid_params.sh``. - - **Currently supported options:** - - | "RRFS_CONUS_25km" - | "RRFS_CONUS_13km" - | "RRFS_CONUS_3km" - - **Other valid values include:** - - | "RRFS_SUBCONUS_3km" - | "RRFS_AK_13km" - | "RRFS_AK_3km" - | "CONUS_25km_GFDLgrid" - | "CONUS_3km_GFDLgrid" - | "EMC_AK" - | "EMC_HI" - | "EMC_PR" - | "EMC_GU" - | "GSL_HAFSV0.A_25km" - | "GSL_HAFSV0.A_13km" - | "GSL_HAFSV0.A_3km" - | "GSD_HRRR_AK_50km" - | "RRFS_NA_13km" - | "RRFS_NA_3km" - -.. - COMMENT: Are all of these now being supported or still just the three main ones? Am I missing any? - -.. note:: - - * If ``PREDEF_GRID_NAME`` is set to a valid predefined grid name, the grid generation method ``GRID_GEN_METHOD``, the (native) grid parameters, and the write-component grid parameters are set to predefined values for the specified grid, overwriting any settings of these parameters in the user-specified experiment configuration file (``config.sh``). In addition, if the time step ``DT_ATMOS`` and the computational parameters ``LAYOUT_X``, ``LAYOUT_Y``, and ``BLOCKSIZE`` are not specified in that configuration file, they are also set to predefined values for the specified grid. - - * If ``PREDEF_GRID_NAME`` is set to an empty string, it implies the user is providing the native grid parameters in the user-specified experiment configuration file (``EXPT_CONFIG_FN``). In this case, the grid generation method ``GRID_GEN_METHOD``, the native grid parameters, and the write-component grid parameters as well as the main time step (``DT_ATMOS``) and the computational parameters ``LAYOUT_X``, ``LAYOUT_Y``, and ``BLOCKSIZE`` must be set in that configuration file. Otherwise, the values of all of these parameters in this default experiment configuration file will be used. - - -Pre-existing Directory Parameter -================================ -``PREEXISTING_DIR_METHOD``: (Default: "delete") - This variable determines the method to use to deal with pre-existing directories (generated by previous calls to the experiment generation script using the same experiment name (``EXPT_SUBDIR``) as the current experiment). This variable must be set to one of three valid values: "delete", "rename", and "quit". The resulting behavior for each of these values is as follows: - - * **"delete":** The preexisting directory is deleted and a new directory (having the same name as the original preexisting directory) is created. - - * **"rename":** The preexisting directory is renamed and a new directory (having the same name as the original pre-existing directory) is created. The new name of the preexisting directory consists of its original name and the suffix "_oldNNN", where NNN is a 3-digit integer chosen to make the new name unique. - - * **"quit":** The preexisting directory is left unchanged, but execution of the currently running script is terminated. In this case, the preexisting directory must be dealt with manually before rerunning the script. - - -Verbose Parameter -================= -``VERBOSE``: (Default: "TRUE") - Flag that determines whether the experiment generation and workflow task scripts print out extra informational messages. Valid values: "TRUE" "true" "YES" "yes" "FALSE" "false" "NO" "no" - -Debug Parameter -================= -``DEBUG``: (Default: "FALSE") - Flag that determines whether to print out very detailed debugging messages. Note that if DEBUG is set to TRUE, then VERBOSE will also get reset to TRUE if it isn't already. Valid values: "TRUE" "true" "YES" "yes" "FALSE" "false" "NO" "no" - -Rocoto Workflow Tasks -======================== - -Set the names of the various Rocoto workflow tasks. These names usually do not need to be changed. - -**Baseline Tasks:** - -| ``MAKE_GRID_TN``: (Default: "make_grid") -| ``MAKE_OROG_TN``: (Default: "make_orog") -| ``MAKE_SFC_CLIMO_TN``: (Default: "make_sfc_climo") -| ``GET_EXTRN_ICS_TN``: (Default: "get_extrn_ics") -| ``GET_EXTRN_LBCS_TN``: (Default: "get_extrn_lbcs") -| ``MAKE_ICS_TN``: (Default: "make_ics") -| ``MAKE_LBCS_TN``: (Default: "make_lbcs") -| ``RUN_FCST_TN``: (Default: "run_fcst") -| ``RUN_POST_TN``: (Default: "run_post") - -**METplus Verification Tasks:** When running METplus verification tasks, the following task names are also added to the Rocoto workflow: - -| ``GET_OBS``: (Default: "get_obs") -| ``GET_OBS_CCPA_TN``: (Default: "get_obs_ccpa") -| ``GET_OBS_MRMS_TN``: (Default: "get_obs_mrms") -| ``GET_OBS_NDAS_TN``: (Default: "get_obs_ndas") -| ``VX_TN``: (Default: "run_vx") -| ``VX_GRIDSTAT_TN``: (Default: "run_gridstatvx") -| ``VX_GRIDSTAT_REFC_TN``: (Default: "run_gridstatvx_refc") -| ``VX_GRIDSTAT_RETOP_TN``: (Default: "run_gridstatvx_retop") -| ``VX_GRIDSTAT_03h_TN``: (Default: "run_gridstatvx_03h") -| ``VX_GRIDSTAT_06h_TN``: (Default: "run_gridstatvx_06h") -| ``VX_GRIDSTAT_24h_TN``: (Default: "run_gridstatvx_24h") -| ``VX_POINTSTAT_TN``: (Default: "run_pointstatvx") -| ``VX_ENSGRID_TN``: (Default: "run_ensgridvx") -| ``VX_ENSGRID_03h_TN``: (Default: "run_ensgridvx_03h") -| ``VX_ENSGRID_06h_TN``: (Default: "run_ensgridvx_06h") -| ``VX_ENSGRID_24h_TN``: (Default: "run_ensgridvx_24h") -| ``VX_ENSGRID_REFC_TN``: (Default: "run_ensgridvx_refc") -| ``VX_ENSGRID_RETOP_TN``: (Default: "run_ensgridvx_retop") -| ``VX_ENSGRID_MEAN_TN``: (Default: "run_ensgridvx_mean") -| ``VX_ENSGRID_PROB_TN``: (Default: "run_ensgridvx_prob") -| ``VX_ENSGRID_MEAN_03h_TN``: (Default: "run_ensgridvx_mean_03h") -| ``VX_ENSGRID_PROB_03h_TN``: (Default: "run_ensgridvx_prob_03h") -| ``VX_ENSGRID_MEAN_06h_TN``: (Default: "run_ensgridvx_mean_06h") -| ``VX_ENSGRID_PROB_06h_TN``: (Default: "run_ensgridvx_prob_06h") -| ``VX_ENSGRID_MEAN_24h_TN``: (Default: "run_ensgridvx_mean_24h") -| ``VX_ENSGRID_PROB_24h_TN``: (Default: "run_ensgridvx_prob_24h") -| ``VX_ENSGRID_PROB_REFC_TN``: (Default: "run_ensgridvx_prob_refc") -| ``VX_ENSGRID_PROB_RETOP_TN``: (Default: "run_ensgridvx_prob_retop") -| ``VX_ENSPOINT_TN``: (Default: "run_enspointvx") -| ``VX_ENSPOINT_MEAN_TN``: (Default: "run_enspointvx_mean") -| ``VX_ENSPOINT_PROB_TN``: (Default: "run_enspointvx_prob") - - -Workflow Task Parameters -======================== -For each workflow task, additional parameters set the values to pass to the job scheduler (e.g., Slurm) that will submit a job for each task to be run. Parameters include the number of nodes to use to run the job, the number of MPI processes per node, the maximum walltime to allow for the job to complete, and the maximum number of times to attempt to run each task. - -**Number of nodes:** - -| ``NNODES_MAKE_GRID``: (Default: "1") -| ``NNODES_MAKE_OROG``: (Default: "1") -| ``NNODES_MAKE_SFC_CLIMO``: (Default: "2") -| ``NNODES_GET_EXTRN_ICS``: (Default: "1") -| ``NNODES_GET_EXTRN_LBCS``: (Default: "1") -| ``NNODES_MAKE_ICS``: (Default: "4") -| ``NNODES_MAKE_LBCS``: (Default: "4") -| ``NNODES_RUN_FCST``: (Default: "") - -.. note:: - The correct value for ``NNODES_RUN_FCST`` will be calculated in the workflow generation scripts. - -| ``NNODES_RUN_POST``: (Default: "2") -| ``NNODES_GET_OBS_CCPA``: (Default: "1") -| ``NNODES_GET_OBS_MRMS``: (Default: "1") -| ``NNODES_GET_OBS_NDAS``: (Default: "1") -| ``NNODES_VX_GRIDSTAT``: (Default: "1") -| ``NNODES_VX_POINTSTAT``: (Default: "1") -| ``NNODES_VX_ENSGRID``: (Default: "1") -| ``NNODES_VX_ENSGRID_MEAN``: (Default: "1") -| ``NNODES_VX_ENSGRID_PROB``: (Default: "1") -| ``NNODES_VX_ENSPOINT``: (Default: "1") -| ``NNODES_VX_ENSPOINT_MEAN``: (Default: "1") -| ``NNODES_VX_ENSPOINT_PROB``: (Default: "1") - -**Number of MPI processes per node:** - -| ``PPN_MAKE_GRID``: (Default: "24") -| ``PPN_MAKE_OROG``: (Default: "24") -| ``PPN_MAKE_SFC_CLIMO``: (Default: "24") -| ``PPN_GET_EXTRN_ICS``: (Default: "1") -| ``PPN_GET_EXTRN_LBCS``: (Default: "1") -| ``PPN_MAKE_ICS``: (Default: "12") -| ``PPN_MAKE_LBCS``: (Default: "12") -| ``PPN_RUN_FCST``: (Default: "") - -.. note:: - The correct value for ``PPN_RUN_FCST`` will be calculated from ``NCORES_PER_NODE`` and ``OMP_NUM_THREADS`` in ``setup.sh``. - -| ``PPN_RUN_POST``: (Default: "24") -| ``PPN_GET_OBS_CCPA``: (Default: "1") -| ``PPN_GET_OBS_MRMS``: (Default: "1") -| ``PPN_GET_OBS_NDAS``: (Default: "1") -| ``PPN_VX_GRIDSTAT``: (Default: "1") -| ``PPN_VX_POINTSTAT``: (Default: "1") -| ``PPN_VX_ENSGRID``: (Default: "1") -| ``PPN_VX_ENSGRID_MEAN``: (Default: "1") -| ``PPN_VX_ENSGRID_PROB``: (Default: "1") -| ``PPN_VX_ENSPOINT``: (Default: "1") -| ``PPN_VX_ENSPOINT_MEAN``: (Default: "1") -| ``PPN_VX_ENSPOINT_PROB``: (Default: "1") - - -**Wall Times:** Maximum amount of time for the task to run - -| ``WTIME_MAKE_GRID``: (Default: "00:20:00") -| ``WTIME_MAKE_OROG``: (Default: "01:00:00") -| ``WTIME_MAKE_SFC_CLIMO``: (Default: "00:20:00") -| ``WTIME_GET_EXTRN_ICS``: (Default: "00:45:00") -| ``WTIME_GET_EXTRN_LBCS``: (Default: "00:45:00") -| ``WTIME_MAKE_ICS``: (Default: "00:30:00") -| ``WTIME_MAKE_LBCS``: (Default: "00:30:00") -| ``WTIME_RUN_FCST``: (Default: "04:30:00") -| ``WTIME_RUN_POST``: (Default: "00:15:00") -| ``WTIME_GET_OBS_CCPA``: (Default: "00:45:00") -| ``WTIME_GET_OBS_MRMS``: (Default: "00:45:00") -| ``WTIME_GET_OBS_NDAS``: (Default: "02:00:00") -| ``WTIME_VX_GRIDSTAT``: (Default: "02:00:00") -| ``WTIME_VX_POINTSTAT``: (Default: "01:00:00") -| ``WTIME_VX_ENSGRID``: (Default: "01:00:00") -| ``WTIME_VX_ENSGRID_MEAN``: (Default: "01:00:00") -| ``WTIME_VX_ENSGRID_PROB``: (Default: "01:00:00") -| ``WTIME_VX_ENSPOINT``: (Default: "01:00:00") -| ``WTIME_VX_ENSPOINT_MEAN``: (Default: "01:00:00") -| ``WTIME_VX_ENSPOINT_PROB``: (Default: "01:00:00") - -**Maximum number of attempts to run a task:** - -| ``MAXTRIES_MAKE_GRID``: (Default: "2") -| ``MAXTRIES_MAKE_OROG``: (Default: "2") -| ``MAXTRIES_MAKE_SFC_CLIMO``: (Default: "2") -| ``MAXTRIES_GET_EXTRN_ICS``: (Default: "1") -| ``MAXTRIES_GET_EXTRN_LBCS``: (Default: "1") -| ``MAXTRIES_MAKE_ICS``: (Default: "1") -| ``MAXTRIES_MAKE_LBCS``: (Default: "1") -| ``MAXTRIES_RUN_FCST``: (Default: "1") -| ``MAXTRIES_RUN_POST``: (Default: "2") -| ``MAXTRIES_GET_OBS_CCPA``: (Default: "1") -| ``MAXTRIES_GET_OBS_MRMS``: (Default: "1") -| ``MAXTRIES_GET_OBS_NDAS``: (Default: "1") -| ``MAXTRIES_VX_GRIDSTAT``: (Default: "1") -| ``MAXTRIES_VX_GRIDSTAT_REFC``: (Default: "1") -| ``MAXTRIES_VX_GRIDSTAT_RETOP``: (Default: "1") -| ``MAXTRIES_VX_GRIDSTAT_03h``: (Default: "1") -| ``MAXTRIES_VX_GRIDSTAT_06h``: (Default: "1") -| ``MAXTRIES_VX_GRIDSTAT_24h``: (Default: "1") -| ``MAXTRIES_VX_POINTSTAT``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_REFC``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_RETOP``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_03h``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_06h``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_24h``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_MEAN``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_PROB``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_MEAN_03h``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_PROB_03h``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_MEAN_06h``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_PROB_06h``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_MEAN_24h``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_PROB_24h``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_PROB_REFC``: (Default: "1") -| ``MAXTRIES_VX_ENSGRID_PROB_RETOP``: (Default: "1") -| ``MAXTRIES_VX_ENSPOINT``: (Default: "1") -| ``MAXTRIES_VX_ENSPOINT_MEAN``: (Default: "1") -| ``MAXTRIES_VX_ENSPOINT_PROB``: (Default: "1") - - -Pre-Processing Parameters -========================= -These parameters set flags (and related directories) that determine whether various workflow tasks should be run. Note that the ``MAKE_GRID_TN``, ``MAKE_OROG_TN``, and ``MAKE_SFC_CLIMO_TN`` are all :term:`cycle-independent` tasks, i.e., if they are to be run, they do so only once at the beginning of the workflow before any cycles are run. - -Baseline Workflow Tasks --------------------------- - -``RUN_TASK_MAKE_GRID``: (Default: "TRUE") - Flag that determines whether to run the grid file generation task (``MAKE_GRID_TN``). If this is set to "TRUE", the grid generation task is run and new grid files are generated. If it is set to "FALSE", then the scripts look for pre-generated grid files in the directory specified by ``GRID_DIR`` (see below). - -``GRID_DIR``: (Default: "/path/to/pregenerated/grid/files") - The directory containing pre-generated grid files when ``RUN_TASK_MAKE_GRID`` is set to "FALSE". - -``RUN_TASK_MAKE_OROG``: (Default: "TRUE") - Same as ``RUN_TASK_MAKE_GRID`` but for the orography generation task (``MAKE_OROG_TN``). - -``OROG_DIR``: (Default: "/path/to/pregenerated/orog/files") - Same as ``GRID_DIR`` but for the orography generation task (``MAKE_OROG_TN``). - -``RUN_TASK_MAKE_SFC_CLIMO``: (Default: "TRUE") - Same as ``RUN_TASK_MAKE_GRID`` but for the surface climatology generation task (``MAKE_SFC_CLIMO_TN``). - -``SFC_CLIMO_DIR``: (Default: "/path/to/pregenerated/surface/climo/files") - Same as ``GRID_DIR`` but for the surface climatology generation task (``MAKE_SFC_CLIMO_TN``). - -``RUN_TASK_GET_EXTRN_ICS``: (Default: "TRUE") - Flag that determines whether to run the ``GET_EXTRN_ICS_TN`` task. - -``RUN_TASK_GET_EXTRN_LBCS``: (Default: "TRUE") - Flag that determines whether to run the ``GET_EXTRN_LBCS_TN`` task. - -``RUN_TASK_MAKE_ICS``: (Default: "TRUE") - Flag that determines whether to run the ``MAKE_ICS_TN`` task. - -``RUN_TASK_MAKE_LBCS``: (Default: "TRUE") - Flag that determines whether to run the ``MAKE_LBCS_TN`` task. - -``RUN_TASK_RUN_FCST``: (Default: "TRUE") - Flag that determines whether to run the ``RUN_FCST_TN`` task. - -``RUN_TASK_RUN_POST``: (Default: "TRUE") - Flag that determines whether to run the ``RUN_POST_TN`` task. - -Verification Tasks --------------------- - -``RUN_TASK_GET_OBS_CCPA``: (Default: "FALSE") - Flag that determines whether to run the ``GET_OBS_CCPA`` task, which retrieves the CCPA hourly precipitation files used by METplus. - -``RUN_TASK_GET_OBS_MRMS``: (Default: "FALSE") - Flag that determines whether to run the ``GET_OBS_MRMS`` task, which retrieves the MRMS composite reflectivity files used by METplus. - -``RUN_TASK_GET_OBS_NDAS``: (Default: "FALSE") - Flag that determines whether to run the ``GET_OBS_NDAS`` task, which retrieves the NDAS PREPBUFR files used by METplus. - -.. - COMMENT: Need confirmation that the above 3 task explanations are correct. - - -``RUN_TASK_VX_GRIDSTAT``: (Default: "FALSE") - Flag that determines whether to run the grid-stat verification task. - -``RUN_TASK_VX_POINTSTAT``: (Default: "FALSE") - Flag that determines whether to run the point-stat verification task. - -``RUN_TASK_VX_ENSGRID``: (Default: "FALSE") - Flag that determines whether to run the ensemble-stat verification for gridded data task. - -``RUN_TASK_VX_ENSPOINT``: (Default: "FALSE") - Flag that determines whether to run the ensemble point verification task. If this flag is set, both ensemble-stat point verification and point verification of ensemble-stat output is computed. - -.. - COMMENT: Might be worth defining "ensemble-stat verification for gridded data," "ensemble point verification," "ensemble-stat point verification," and "point verification of ensemble-stat output" - -Aerosol Climatology Parameter -================================ - -``USE_MERRA_CLIMO``: (Default: "FALSE") - Flag that determines whether MERRA2 aerosol climatology data and lookup tables for optics properties are obtained. - -.. - COMMENT: When would it be appropriate to obtain these files? - -Surface Climatology Parameter -============================= -``SFC_CLIMO_FIELDS``: (Default: "("facsf" "maximum_snow_albedo" "slope_type" "snowfree_albedo" "soil_type" "substrate_temperature" "vegetation_greenness" "vegetation_type")" ) - Array containing the names of all the fields for which ``MAKE_SFC_CLIMO_TN`` generates files on the native FV3-LAM grid. - -Fixed File Parameters -===================== -These parameters are associated with the fixed (i.e., static) files. On `Level 1 & 2 `__ systems, fixed files are prestaged with paths defined in the ``setup.sh`` script. Because the default values are platform-dependent, they are set to a null string in ``config_defaults.sh``. Then these null values are overwritten in ``setup.sh`` with machine-specific values or with a user-specified value from ``config.sh``. - -``FIXgsm``: (Default: "") - System directory in which the majority of fixed (i.e., time-independent) files that are needed to run the FV3-LAM model are located. - -``FIXaer``: (Default: "") - System directory where MERRA2 aerosol climatology files are located. - -``FIXlut``: (Default: "") - System directory where the lookup tables for optics properties are located. - -``TOPO_DIR``: (Default: "") - The location on disk of the static input files used by the ``make_orog`` task (i.e., ``orog.x`` and ``shave.x``). Can be the same as ``FIXgsm``. - -``SFC_CLIMO_INPUT_DIR``: (Default: "") - The location on disk of the static surface climatology input fields, used by ``sfc_climo_gen``. These files are only used if ``RUN_TASK_MAKE_SFC_CLIMO=TRUE``. - -``FNGLAC, ..., FNMSKH``: (Default: see below) - .. code-block:: console - - (FNGLAC="global_glacier.2x2.grb" - FNMXIC="global_maxice.2x2.grb" - FNTSFC="RTGSST.1982.2012.monthly.clim.grb" - FNSNOC="global_snoclim.1.875.grb" - FNZORC="igbp" - FNAISC="CFSR.SEAICE.1982.2012.monthly.clim.grb" - FNSMCC="global_soilmgldas.t126.384.190.grb" - FNMSKH="seaice_newland.grb") - - Names and default locations of (some of the) global data files that are assumed to exist in a system directory. (This directory is machine-dependent; the experiment generation scripts will set it and store it in the variable ``FIXgsm``.) These file names also appear directly in the forecast model's input :term:`namelist` file. - -``FIXgsm_FILES_TO_COPY_TO_FIXam``: (Default: see below) - .. code-block:: console - - ("$FNGLAC" \ - "$FNMXIC" \ - "$FNTSFC" \ - "$FNSNOC" \ - "$FNAISC" \ - "$FNSMCC" \ - "$FNMSKH" \ - "global_climaeropac_global.txt" \ - "fix_co2_proj/global_co2historicaldata_2010.txt" \ - "fix_co2_proj/global_co2historicaldata_2011.txt" \ - "fix_co2_proj/global_co2historicaldata_2012.txt" \ - "fix_co2_proj/global_co2historicaldata_2013.txt" \ - "fix_co2_proj/global_co2historicaldata_2014.txt" \ - "fix_co2_proj/global_co2historicaldata_2015.txt" \ - "fix_co2_proj/global_co2historicaldata_2016.txt" \ - "fix_co2_proj/global_co2historicaldata_2017.txt" \ - "fix_co2_proj/global_co2historicaldata_2018.txt" \ - "fix_co2_proj/global_co2historicaldata_2019.txt" \ - "fix_co2_proj/global_co2historicaldata_2020.txt" \ - "fix_co2_proj/global_co2historicaldata_2021.txt" \ - "global_co2historicaldata_glob.txt" \ - "co2monthlycyc.txt" \ - "global_h2o_pltc.f77" \ - "global_hyblev.l65.txt" \ - "global_zorclim.1x1.grb" \ - "global_sfc_emissivity_idx.txt" \ - "global_tg3clim.2.6x1.5.grb" \ - "global_solarconstant_noaa_an.txt" \ - "global_albedo4.1x1.grb" \ - "geo_em.d01.lat-lon.2.5m.HGT_M.nc" \ - "HGT.Beljaars_filtered.lat-lon.30s_res.nc" \ - "replace_with_FIXgsm_ozone_prodloss_filename") - - If not running in NCO mode, this array contains the names of the files to copy from the ``FIXgsm`` system directory to the ``FIXam`` directory under the experiment directory. - - .. note:: - The last element in the list above contains a dummy value. This value will be reset by the workflow generation scripts to the name of the ozone production/loss file that needs to be copied from ``FIXgsm``. This file depends on the :term:`CCPP` physics suite specified for the experiment (and the corresponding ozone parameterization scheme used in that physics suite). - -``FV3_NML_VARNAME_TO_FIXam_FILES_MAPPING``: (Default: see below) - .. code-block:: console - - ("FNGLAC | $FNGLAC" \ - "FNMXIC | $FNMXIC" \ - "FNTSFC | $FNTSFC" \ - "FNSNOC | $FNSNOC" \ - "FNAISC | $FNAISC" \ - "FNSMCC | $FNSMCC" \ - "FNMSKH | $FNMSKH" ) - - This array is used to set some of the :term:`namelist` variables in the forecast model's namelist file. It maps file symlinks to the actual fixed file locations in the ``FIXam`` directory. The symlink names appear in the first column (to the left of the "|" symbol), and the paths to these files (in the ``FIXam`` directory) are held in workflow variables, which appear to the right of the "|" symbol. It is possible to remove ``FV3_NML_VARNAME_TO_FIXam_FILES_MAPPING`` as a workflow variable and make it only a local one since it is used in only one script. - -.. - COMMENT: Why is #"FNZORC | $FNZORC" \ commented out in config_defaults.sh? - COMMENT: Is this an accurate rewording of the original? - - -``FV3_NML_VARNAME_TO_SFC_CLIMO_FIELD_MAPPING``: (Default: see below) - .. code-block:: console - - ("FNALBC | snowfree_albedo" \ - "FNALBC2 | facsf" \ - "FNTG3C | substrate_temperature" \ - "FNVEGC | vegetation_greenness" \ - "FNVETC | vegetation_type" \ - "FNSOTC | soil_type" \ - "FNVMNC | vegetation_greenness" \ - "FNVMXC | vegetation_greenness" \ - "FNSLPC | slope_type" \ - "FNABSC | maximum_snow_albedo" ) - - This array is used to set some of the :term:`namelist` variables in the forecast model's namelist file. The variable names appear in the first column (to the left of the "|" symbol), and the paths to these surface climatology files on the native FV3-LAM grid (in the ``FIXLAM`` directory) are derived from the corresponding surface climatology fields (the second column of the array). - -.. - COMMENT: Is this an accurate rewording of the original? - -``CYCLEDIR_LINKS_TO_FIXam_FILES_MAPPING``: (Default: see below) - .. code-block:: console - - ("aerosol.dat | global_climaeropac_global.txt" \ - "co2historicaldata_2010.txt | fix_co2_proj/global_co2historicaldata_2010.txt" \ - "co2historicaldata_2011.txt | fix_co2_proj/global_co2historicaldata_2011.txt" \ - "co2historicaldata_2012.txt | fix_co2_proj/global_co2historicaldata_2012.txt" \ - "co2historicaldata_2013.txt | fix_co2_proj/global_co2historicaldata_2013.txt" \ - "co2historicaldata_2014.txt | fix_co2_proj/global_co2historicaldata_2014.txt" \ - "co2historicaldata_2015.txt | fix_co2_proj/global_co2historicaldata_2015.txt" \ - "co2historicaldata_2016.txt | fix_co2_proj/global_co2historicaldata_2016.txt" \ - "co2historicaldata_2017.txt | fix_co2_proj/global_co2historicaldata_2017.txt" \ - "co2historicaldata_2018.txt | fix_co2_proj/global_co2historicaldata_2018.txt" \ - "co2historicaldata_2019.txt | fix_co2_proj/global_co2historicaldata_2019.txt" \ - "co2historicaldata_2020.txt | fix_co2_proj/global_co2historicaldata_2020.txt" \ - "co2historicaldata_2021.txt | fix_co2_proj/global_co2historicaldata_2021.txt" \ - "co2historicaldata_glob.txt | global_co2historicaldata_glob.txt" \ - "co2monthlycyc.txt | co2monthlycyc.txt" \ - "global_h2oprdlos.f77 | global_h2o_pltc.f77" \ - "global_albedo4.1x1.grb | global_albedo4.1x1.grb" \ - "global_zorclim.1x1.grb | global_zorclim.1x1.grb" \ - "global_tg3clim.2.6x1.5.grb | global_tg3clim.2.6x1.5.grb" \ - "sfc_emissivity_idx.txt | global_sfc_emissivity_idx.txt" \ - "solarconstant_noaa_an.txt | global_solarconstant_noaa_an.txt" \ - "global_o3prdlos.f77 | " ) - - This array specifies the mapping to use between the symlinks that need to be created in each cycle directory (these are the "files" that FV3 looks for) and their targets in the ``FIXam`` directory. The first column of the array specifies the symlink to be created, and the second column specifies its target file in ``FIXam`` (where columns are delineated by the pipe symbol "|"). - -Subhourly Forecast Parameters -================================= - -``SUB_HOURLY_POST``: (Default: "FALSE") - Flag that indicates whether the forecast model will generate output files on a sub-hourly time interval (e.g., 10 minutes, 15 minutes). This will also cause the post-processor to process these sub-hourly files. If this variable is set to "TRUE", then ``DT_SUBHOURLY_POST_MNTS`` should be set to a value between "01" and "59". - -``DT_SUB_HOURLY_POST_MNTS``: (Default: "00") - Time interval in minutes between the forecast model output files. If ``SUB_HOURLY_POST`` is set to "TRUE", this needs to be set to a two-digit integer between "01" and "59". Note that if ``SUB_HOURLY_POST`` is set to "TRUE" but ``DT_SUB_HOURLY_POST_MNTS`` is set to "00", ``SUB_HOURLY_POST`` will get reset to "FALSE" in the experiment generation scripts (there will be an informational message in the log file to emphasize this). - -.. - COMMENT: In valid_param_vals.sh only these values are listed: "1" "01" "2" "02" "3" "03" "4" "04" "5" "05" "6" "06" "10" "12" "15" "20" "30". - -Customized Post Configuration Parameters -======================================== - -``USE_CUSTOM_POST_CONFIG_FILE``: (Default: "FALSE") - Flag that determines whether a user-provided custom configuration file should be used for post-processing the model data. If this is set to "TRUE", then the workflow will use the custom post-processing (:term:`UPP`) configuration file specified in ``CUSTOM_POST_CONFIG_FP``. Otherwise, a default configuration file provided in the UPP repository will be used. - -``CUSTOM_POST_CONFIG_FP``: (Default: "") - The full path to the custom post flat file, including filename, to be used for post-processing. This is only used if ``CUSTOM_POST_CONFIG_FILE`` is set to "TRUE". - - -Community Radiative Transfer Model (CRTM) Parameters -======================================================= - -These variables set parameters associated with outputting satellite fields in the :term:`UPP` :term:`grib2` files using the Community Radiative Transfer Model (:term:`CRTM`). - -.. - COMMENT: What actually happens here? Where are the satellite fields outputted to? When/why would this be used? What kind of satellites? - -``USE_CRTM``: (Default: "FALSE") - Flag that defines whether external :term:`CRTM` coefficient files have been staged by the user in order to output synthetic satellite products available within the :term:`UPP`. If this is set to "TRUE", then the workflow will check for these files in the directory ``CRTM_DIR``. Otherwise, it is assumed that no satellite fields are being requested in the UPP configuration. - -``CRTM_DIR``: (Default: "") - This is the path to the top CRTM fix file directory. This is only used if ``USE_CRTM`` is set to "TRUE". - -Ensemble Model Parameters -============================ - -``DO_ENSEMBLE``: (Default: "FALSE") - Flag that determines whether to run a set of ensemble forecasts (for each set of specified cycles). If this is set to "TRUE", ``NUM_ENS_MEMBERS`` forecasts are run for each cycle, each with a different set of stochastic seed values. When "FALSE", a single forecast is run for each cycle. - -``NUM_ENS_MEMBERS``: (Default: "1") - The number of ensemble members to run if ``DO_ENSEMBLE`` is set to "TRUE". This variable also controls the naming of the ensemble member directories. For example, if ``NUM_ENS_MEMBERS`` is set to "8", the member directories will be named *mem1, mem2, ..., mem8*. If it is set to "08" (with a leading zero), the member directories will be named *mem01, mem02, ..., mem08*. However, after reading in the number of characters in this string (in order to determine how many leading zeros, if any, should be placed in the names of the member directories), the workflow generation scripts strip away those leading zeros. Thus, in the variable definitions file (``GLOBAL_VAR_DEFNS_FN``), this variable appears with its leading zeros stripped. This variable is not used unless ``DO_ENSEMBLE`` is set to "TRUE". - -.. _HaloBlend: - -Halo Blend Parameter -==================== -``HALO_BLEND``: (Default: "10") - Number of cells to use for “blending” the external solution (obtained from the :term:`LBCs`) with the internal solution from the FV3LAM dycore. Specifically, it refers to the number of rows into the computational domain that should be blended with the LBCs. Cells at which blending occurs are all within the boundary of the native grid; they don’t involve the 4 cells outside the boundary where the LBCs are specified (which is a different :term:`halo`). Blending is necessary to smooth out waves generated due to mismatch between the external and internal solutions. To shut :term:`halo` blending off, set this to zero. - - -FVCOM Parameter -=============== -``USE_FVCOM``: (Default: "FALSE") - Flag that specifies whether or not to update surface conditions in FV3-LAM with fields generated from the Finite Volume Community Ocean Model (:term:`FVCOM`). If set to "TRUE", lake/sea surface temperatures, ice surface temperatures, and ice placement will be overwritten using data provided by FVCOM. Setting ``USE_FVCOM`` to "TRUE" causes the executable ``process_FVCOM.exe`` in the ``MAKE_ICS_TN`` task to run. This, in turn, modifies the file ``sfc_data.nc`` generated by ``chgres_cube``. Note that the FVCOM data must already be interpolated to the desired FV3-LAM grid. - -``FVCOM_WCSTART``: (Default: "cold") - Define if this is a "warm" start or a "cold" start. Setting this to "warm" will read in ``sfc_data.nc`` generated in a RESTART directory. Setting this to "cold" will read in the ``sfc_data.nc`` generated from ``chgres_cube`` in the ``make_ics`` portion of the workflow. Valid values: "cold" "warm" - -``FVCOM_DIR``: (Default: "/user/defined/dir/to/fvcom/data") - User-defined directory where the ``fvcom.nc`` file containing :term:`FVCOM` data on the FV3-LAM native grid is located. The file name in this directory must be ``fvcom.nc``. - -``FVCOM_FILE``: (Default: "fvcom.nc") - Name of file located in ``FVCOM_DIR`` that has :term:`FVCOM` data interpolated to the FV3-LAM grid. This file will be copied later to a new location and the name changed to ``fvcom.nc`` if a name other than ``fvcom.nc`` is selected. - -Compiler Parameter -================== -``COMPILER``: (Default: "intel") - Type of compiler invoked during the build step. Currently, this must be set manually (i.e., it is not inherited from the build system in the ``ufs-srweather-app`` directory). Valid values: "intel" "gnu" - - -Thread Affinity Interface -=========================== - -.. note:: - Note that settings for the ``make_grid`` and ``make_orog`` tasks are not included below because they do not use parallelized code. - -.. - COMMENT: The note above is in config_defaults.sh comments, but make_orog does seem to be included below... should I remove it? - -``KMP_AFFINITY_*``: (Default: see below) - - .. code-block:: console - - KMP_AFFINITY_MAKE_OROG="disabled" - KMP_AFFINITY_MAKE_SFC_CLIMO="scatter" - KMP_AFFINITY_MAKE_ICS="scatter" - KMP_AFFINITY_MAKE_LBCS="scatter" - KMP_AFFINITY_RUN_FCST="scatter" - KMP_AFFINITY_RUN_POST="scatter" - - Intel's runtime library can bind OpenMP threads to physical processing units. The interface is controlled using the KMP_AFFINITY environment variable. Thread affinity restricts execution of certain threads to a subset of the physical processing units in a multiprocessor computer. Depending on the system (machine) topology, application, and operating system, thread affinity can have a dramatic effect on the application speed and on the execution speed of a program." Valid values: "scatter" "disabled" "balanced" "compact" "explicit" "none" - - For more information, see the `Intel Development Reference Guide `__. - -``OMP_NUM_THREADS_*``: (Default: see below) - - .. code-block:: console - - OMP_NUM_THREADS_MAKE_OROG="6" - OMP_NUM_THREADS_MAKE_SFC_CLIMO="1" - OMP_NUM_THREADS_MAKE_ICS="1" - OMP_NUM_THREADS_MAKE_LBCS="1" - OMP_NUM_THREADS_RUN_FCST="2" # atmos_nthreads in model_configure - OMP_NUM_THREADS_RUN_POST="1" - - The number of OpenMP threads to use for parallel regions. - -.. - COMMENT: What does the #atmos_nthreads comment mean? Can it be removed? - - -``OMP_STACKSIZE_*``: (Default: see below) - - .. code-block:: console - - OMP_STACKSIZE_MAKE_OROG="2048m" - OMP_STACKSIZE_MAKE_SFC_CLIMO="1024m" - OMP_STACKSIZE_MAKE_ICS="1024m" - OMP_STACKSIZE_MAKE_LBCS="1024m" - OMP_STACKSIZE_RUN_FCST="1024m" - OMP_STACKSIZE_RUN_POST="1024m" - - Controls the size of the stack for threads created by the OpenMP implementation. - diff --git a/docs/UsersGuide/source/ConfigWorkflow.rst b/docs/UsersGuide/source/ConfigWorkflow.rst index d605e95b41..3f1146315c 100644 --- a/docs/UsersGuide/source/ConfigWorkflow.rst +++ b/docs/UsersGuide/source/ConfigWorkflow.rst @@ -3,7 +3,7 @@ ============================================================================================ Workflow Parameters: Configuring the Workflow in ``config.sh`` and ``config_defaults.sh`` ============================================================================================ -To create the experiment directory and workflow when running the SRW App, the user must create an experiment configuration file named ``config.sh``. This file contains experiment-specific information, such as dates, external model data, directories, and other relevant settings. To help the user, two sample configuration files have been included in the ``regional_workflow`` repository’s ``ush`` directory: ``config.community.sh`` and ``config.nco.sh``. The first is for running experiments in community mode (``RUN_ENVIR`` set to "community"; see below), and the second is for running experiments in "nco" mode (``RUN_ENVIR`` set to "nco"). Note that for this release, only "community" mode is supported. These files can be used as the starting point from which to generate a variety of experiment configurations in which to run the SRW App. +To create the experiment directory and workflow when running the SRW App, the user must create an experiment configuration file named ``config.sh``. This file contains experiment-specific information, such as dates, external model data, observation data, directories, and other relevant settings. To help the user, two sample configuration files have been included in the ``regional_workflow`` repository’s ``ush`` directory: ``config.community.sh`` and ``config.nco.sh``. The first is for running experiments in community mode (``RUN_ENVIR`` set to "community"; see below), and the second is for running experiments in "nco" mode (``RUN_ENVIR`` set to "nco"). Note that for this release, only "community" mode is supported. These files can be used as the starting point from which to generate a variety of experiment configurations in which to run the SRW App. .. COMMENT: Is community mode still the only one supported? @@ -295,7 +295,7 @@ METplus Parameters Path to top-level directory of METplus installation. ``MET_BIN_EXEC``: (Default: "bin") - Name of the directory where the METplus executable is installed. + Location where METplus executables are installed. .. _METParamNote: @@ -312,8 +312,8 @@ METplus Parameters User-specified location of top-level directory where CCPA hourly precipitation files used by METplus are located. This parameter needs to be set for both user-provided observations and for observations that are retrieved from the NOAA HPSS (if the user has access) via the ``get_obs_ccpa_tn`` task. (This task is activated in the workflow by setting ``RUN_TASK_GET_OBS_CCPA="TRUE"``). METplus configuration files require the use of predetermined directory structure and file names. If the CCPA files are user-provided, they need to follow the anticipated naming structure: ``{YYYYMMDD}/ccpa.t{HH}z.01h.hrap.conus.gb2``, where YYYYMMDD and HH are as described in the note :ref:`above `. When pulling observations from NOAA HPSS, the data retrieved will be placed in the ``CCPA_OBS_DIR`` directory. This path must be defind as ``//ccpa/proc``. METplus is configured to verify 01-, 03-, 06-, and 24-h accumulated precipitation using hourly CCPA files. -.. note:: - There is a problem with the valid time in the metadata for files valid from 19 - 00 UTC (i.e., files under the "00" directory). The script to pull the CCPA data from the NOAA HPSS (``regional_workflow/scripts/exregional_get_ccpa_files.sh``) has an example of how to account for this and organize the data into a more intuitive format. When a fix is provided, it will be accounted for in the ``exregional_get_ccpa_files.sh`` script. + .. note:: + There is a problem with the valid time in the metadata for files valid from 19 - 00 UTC (i.e., files under the "00" directory). The script to pull the CCPA data from the NOAA HPSS (``regional_workflow/scripts/exregional_get_ccpa_files.sh``) has an example of how to account for this and organize the data into a more intuitive format. When a fix is provided, it will be accounted for in the ``exregional_get_ccpa_files.sh`` script. ``MRMS_OBS_DIR``: (Default: "") User-specified location of top-level directory where MRMS composite reflectivity files used by METplus are located. This parameter needs to be set for both user-provided observations and for observations that are retrieved from the NOAA HPSS (if the user has access) via the ``get_obs_mrms_tn`` task (activated in the workflow by setting ``RUN_TASK_GET_OBS_MRMS="TRUE"``). When pulling observations directly from NOAA HPSS, the data retrieved will be placed in this directory. Please note, this path must be defind as ``//mrms/proc``. METplus configuration files require the use of a predetermined directory structure and file names. Therefore, if the MRMS files are user-provided, they need to follow the anticipated naming structure: ``{YYYYMMDD}/MergedReflectivityQCComposite_00.50_{YYYYMMDD}-{HH}{mm}{SS}.grib2``, where YYYYMMDD and {HH}{mm}{SS} are as described in the note :ref:`above `. @@ -1088,17 +1088,19 @@ Baseline Workflow Tasks ``RUN_TASK_RUN_POST``: (Default: "TRUE") Flag that determines whether to run the ``RUN_POST_TN`` task. +.. _VXTasks: + Verification Tasks -------------------- ``RUN_TASK_GET_OBS_CCPA``: (Default: "FALSE") - Flag that determines whether to run the ``GET_OBS_CCPA`` task, which retrieves the CCPA hourly precipitation files used by METplus. + Flag that determines whether to run the ``GET_OBS_CCPA_TN`` task, which retrieves the :term:`CCPA` hourly precipitation files used by METplus from NOAA HPSS. ``RUN_TASK_GET_OBS_MRMS``: (Default: "FALSE") - Flag that determines whether to run the ``GET_OBS_MRMS`` task, which retrieves the MRMS composite reflectivity files used by METplus. + Flag that determines whether to run the ``GET_OBS_MRMS_TN`` task, which retrieves the :term:`MRMS` composite reflectivity files used by METplus from NOAA HPSS. ``RUN_TASK_GET_OBS_NDAS``: (Default: "FALSE") - Flag that determines whether to run the ``GET_OBS_NDAS`` task, which retrieves the NDAS PREPBUFR files used by METplus. + Flag that determines whether to run the ``GET_OBS_NDAS_TN`` task, which retrieves the :term:`NDAS` PrepBufr files used by METplus from NOAA HPSS. .. COMMENT: Need confirmation that the above 3 task explanations are correct. diff --git a/docs/UsersGuide/source/Glossary.rst b/docs/UsersGuide/source/Glossary.rst index 552fbaf67b..ba07c66f26 100644 --- a/docs/UsersGuide/source/Glossary.rst +++ b/docs/UsersGuide/source/Glossary.rst @@ -6,6 +6,9 @@ Glossary .. glossary:: + CCPA + Climatology-Calibrated Precipitation Analysis (CCPA) data. This data is required for METplus precipitation verification tasks within the SRW App. The most recent 8 days worth of data are publicly available and can be accessed `here `__. + CCPP The `Common Community Physics Package `_ is a forecast-model agnostic, vetted collection of codes containing atmospheric physical parameterizations and suites of parameterizations for use in Numerical Weather Prediction (NWP) along with a framework that connects the physics to the host forecast model. @@ -43,6 +46,9 @@ Glossary dynamical core Global atmospheric model based on fluid dynamics principles, including Euler's equations of motion. + echo top + The radar-indicated top of an area of precipitation. Specifically, it contains the height of the 18 dBZ reflectivity value. + EPIC EPIC stands for the `Earth Prediction Innovation Center `__. EPIC seeks to accelerate scientific research and modeling contributions through continuous and sustained community engagement to produce the most accurate and reliable operational modeling system in the world. @@ -52,7 +58,7 @@ Glossary FV3 The Finite-Volume Cubed-Sphere dynamical core (dycore). Developed at NOAA's Geophysical Fluid Dynamics Laboratory (GFDL), it is a scalable and flexible dycore capable of both - hydrostatic and non-hydrostatic atmospheric simulations. It is the dycore used in the + hydrostatic and non-hydrostatic atmospheric simulations. It is the dycore used in the UFS Weather Model. FVCOM @@ -88,12 +94,18 @@ Glossary MPI MPI stands for Message Passing Interface. An MPI is a standardized communication system used in parallel programming. It establishes portable and efficient syntax for the exchange of messages and data between multiple processors that are used by a single computer program. An MPI is required for high-performance computing (HPC). + MRMS + Multi-Radar/Multi-Sensor (MRMS) System Analysis data. This data is required for METplus composite reflectivity or :term:`echo top` verification tasks within the SRW App. A two-day archive of precipitation, radar, and aviation and severe weather fields is publicly available and can be accessed `here `__. + NAM `North American Mesoscale Forecast System `_. NAM generates multiple grids (or domains) of weather forecasts over the North American continent at various horizontal resolutions. Each grid contains data for dozens of weather parameters, including temperature, precipitation, lightning, and turbulent kinetic energy. NAM uses additional numerical weather models to generate high-resolution forecasts over fixed regions, and occasionally to follow significant weather events like hurricanes. namelist A namelist defines a group of variables or arrays. Namelists are an I/O feature for format-free input and output of variables by key-value assignments in FORTRAN compilers. Fortran variables can be read from and written to plain-text files in a standardised format, usually with a ``.nml`` file ending. + NCAR + The `National Center for Atmospheric Research `__. + NCEP National Centers for Environmental Prediction, an arm of the National Weather Service, consisting of nine centers. More information can be found at https://www.ncep.noaa.gov. @@ -110,6 +122,9 @@ Glossary An interpreted programming language designed specifically for scientific data analysis and visualization. Stands for NCAR Command Language. More information can be found at https://www.ncl.ucar.edu. + NDAS + :term:`NAM` Data Assimilation System (NDAS) data. This data is required for METplus surface and upper-air verification tasks within the SRW App. The most recent 1-2 days worth of data are publicly available in PrepBufr format and can be accessed `here `__. The most recent 8 days of data can be accessed `here `__. + NEMS The NOAA Environmental Modeling System is a common modeling framework whose purpose is to streamline components of operational modeling suites at :term:`NCEP`. diff --git a/docs/UsersGuide/source/Introduction.rst b/docs/UsersGuide/source/Introduction.rst index 4427c9edc2..b151fcc481 100644 --- a/docs/UsersGuide/source/Introduction.rst +++ b/docs/UsersGuide/source/Introduction.rst @@ -74,6 +74,10 @@ Unified Post-Processor (UPP) The `Unified Post Processor `__ (:term:`UPP`) processes raw output from a variety of numerical weather prediction (:term:`NWP`) models. In the SRW App, it converts data output from netCDF format to GRIB2 format. The UPP can also be used to compute a variety of useful diagnostic fields, as described in the `UPP User’s Guide `_. Output from the UPP can be used with visualization, plotting, and verification packages, or for further downstream post-processing (e.g., statistical post-processing techniques). +METplus Verification Suite +------------------------------ + +The Model Evaluation Tools (MET) package is a set of statistical verification tools developed by the `Developmental Testbed Center `__ (DTC) for use by the :term:`NWP` community to help them assess and evaluate the performance of numerical weather predictions. MET is the core component of the enhanced METplus verification framework. The suite also includes the associated database and display systems called METviewer and METexpress. METplus spans a wide range of temporal and spatial scales. It is intended to be extensible through additional capabilities developed by the community. More details about METplus can be found in :numref:`Chapter %s ` and on the `METplus website `__. Visualization Example ------------------------- diff --git a/docs/UsersGuide/source/Quickstart.rst b/docs/UsersGuide/source/Quickstart.rst index 23c3f0aeea..64685d8a02 100644 --- a/docs/UsersGuide/source/Quickstart.rst +++ b/docs/UsersGuide/source/Quickstart.rst @@ -125,7 +125,7 @@ Set the build environments and modules within the ``ufs-srweather-app`` director source /usr/share/lmod/6.6/init/profile module use /opt/hpc-modules/modulefiles/stack module load hpc hpc-gnu hpc-openmpi hpc-python - module load netcdf hdf5 bacio sfcio sigio nemsio w3emc esmf fms crtm g2 png zlib g2tmpl ip sp w3nco cmake gfsio wgrib2 upp + module load netcdf hdf5 bacio sfcio sigio nemsio w3emc esmf fms crtm g2 png zlib g2tmpl ip sp w3nco cmake gfsio upp