1.1. Introduction

The Unified Forecast System (UFS) is a community-based, coupled, comprehensive Earth modeling system. NOAA’s operational model suite for numerical weather prediction (NWP) is quickly transitioning to the UFS from a number of different modeling systems. The UFS enables research, development, and contribution opportunities within the broader Weather Enterprise (including government, industry, and academia). For more information about the UFS, visit the UFS Portal.

The UFS includes multiple applications 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 most recent 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 this User’s Guide and supported through the GitHub Discussions forum. The SRW App also includes support for a verification package (METplus) for both deterministic and ensemble simulations and support for four stochastically perturbed physics schemes.

Since the last release, developers have added a variety of features:

Bug fixes since the v2.1.0 release

Addition of the supported FV3_RAP physics suite (PR #811) and support for the RRFS_NA_13km predefined grid

Addition of FV3_GFS_v17_p8 physics suite (PR #574)

Updates to CCPP that target the top of the main branch (which is ahead of CCPP v6.0.0). See this page for a detailed summary of updates that came in ahead of the v2.2.0 release.

Expansion of Level 1 platforms to include Derecho, Hercules, and Gaea C5 (PRs #894, #898, #911)

Transition to spack-stack modulefiles for most supported platforms to align with the UFS WM shift to spack-stack (PRs #913 and #941)

Overhaul of the WE2E testing suite (see, e.g., PRs #686, #732, #864, #871)

Improvements to the CI/CD automated testing pipeline (see, e.g., PRs :pull/707>` and #847)

Incorporation of additional METplus verification capabilities (PRs #552, #614, #757, #853)

Integration of the Unified Workflow’s templater tool (PR #793)

Ability to create a user-defined custom workflow (PR #676)

Option to use a custom vertical coordinate file with different distribution of vertical layers (PR #813) and documentation on how to use this feature (PR #888)

Incorporation of plotting tasks into the workflow (PR #482); addition of ability to plot on both CONUS and smaller regional grid (PR #560)

Addition of a sample verification case (PR #500) with documentation

A new tutorial chapter in the documentation (PR #584)

Incorporation of UFS Case Studies within the WE2E framework (PRs #736 and #822)

Air Quality Modeling (AQM) capabilities (unsupported but available; see PR #613)

Miscellaneous documentation updates to reflect the changes above

The SRW App v2.2.0 citation is as follows and should be used when presenting results based on research conducted with the App:

UFS Development Team. (2023, Oct. 31). Unified Forecast System (UFS) Short-Range Weather (SRW) Application (Version v2.2.0). Zenodo. https://doi.org/10.5281/zenodo.10015544

1.1.1. User’s Guide Organization

The SRW Application documentation is organized into four sections: (1) Background Information; (2) Building, Running, and Testing the SRW App; (3) Customizing the Workflow; and (4) Reference.

1.1.1.1. Background Information

This Introduction section explains how the SRW App documentation is organized, how to use this guide, and where to find user support and component documentation.

Section 1.2: Technical Overview provides technical information about the SRW App, including prerequisites and an overview of the code directory structure.

Section 1.3: SRW Application Components provides a description of the application components, including optional components.

1.1.1.2. Building, Running, and Testing the SRW App

Section 2.1: Quick Start Guide is an overview of the workflow and gives instructions for its use on Level 1 platforms.

Section 2.2: Container-Based Quick Start Guide explains how to run the SRW Application in a container. Containers may be run on a broad range of systems and come with SRW App prerequisites already installed.

Section 2.3: Building the SRW App provides a detailed explanation of how to build the SRW App.

Section 2.4: Running the SRW App provides a detailed explanation of how to run the SRW App after it has been built/compiled. It includes information on standard workflow tasks, additional optional tasks (e.g., METplus verification, plotting), and different techniques for running the workflow.

Section 2.5: Testing the SRW App explains how to run workflow end-to-end (WE2E) tests to ensure that new developments do not break the current workflow.

Section 2.6: Tutorials walks users through different SRW App experiment cases and analysis of results.

Section 2.7: METplus Verification Sample Cases explains how to run METplus verification as part of the workflow.

Section 2.8: Air Quality Modeling provides information specific to air quality modeling (AQM). This feature is currently unsupported, so documentation may be behind the current state of development, which is progressing rapidly. However, this section is a starting point for those interested in AQM.

Section 2.9: SRW Smoke & Dust provides information specific to smoke and dust modeling. This feature is currently only supported on Hera and Orion/Hercules, but it is a starting point for those interested in regional smoke & dust modeling.

Hint

To get started with the SRW App, it is recommended that users try one of the following options:
1. View Section 2.1: Quick Start Guide for a quick overview of the workflow steps. Especially helpful for users with access to a Level 1 platform.
2. To build the application in a container, which provides a more uniform work environment, users can refer to Section 2.2: Container-Based Quick Start Guide.
3. For detailed instructions on building and running the SRW App, users can refer to Section 2.3: Building the SRW App and Section 2.4: Running the SRW App.

1.1.1.3. Customizing the Workflow

Section 3.1: Workflow Parameters documents all of the user-configurable experiment parameters that can be set in the user configuration file (config.yaml).

Section 3.2: Input & Output Files describes application input and output files, as well as information on where to get publicly available data.

Section 3.3: Limited Area Model (LAM) Grids describes the SRW App predefined grids, explains how to create a custom user-generated grid, and provides information on using a custom distribution of vertical levels.

Section 3.4: Defining an SRW App Workflow explains how to build a customized SRW App workflow XML file.

Section 3.5: Template Variables explains how to use template variables.

1.1.1.4. Reference Information

Section 4.1: Rocoto Introductory Information provides an introduction to standard Rocoto commands with examples.

Section 4.2: FAQ answers users’ frequently asked questions.

Section 4.3: Glossary defines important terms related to the SRW App.

1.1.2. SRW App Documentation Conventions

This guide uses particular conventions to indicate commands and code snippets, file and directory paths, variables, and options.

Throughout the guide, this presentation style indicates shell commands, code snippets, etc.

Text rendered as AaBbCc123 typically refers to variables in scripts, names of files, or directories.

Code that includes angle brackets (e.g., build_<platform>_<compiler>) indicates that users should insert options appropriate to their SRW App configuration (e.g., build_hera_intel).

File or directory paths that begin with /path/to/ should be replaced with the actual path on the user’s system. For example, /path/to/modulefiles might be replaced by /Users/Jane.Smith/ufs-srweather-app/modulefiles.

1.1.3. Component Documentation

A list of available component documentation is shown in Table 1.1. In general, technical documentation will explain how to use a particular component, whereas scientific documentation provides more in-depth information on the science involved in specific component files.

Table 1.1 Centralized List of Documentation
Documentation	Location
spack-stack Documentation	https://spack-stack.readthedocs.io/en/latest/
HPC-Stack Documentation	https://hpc-stack.readthedocs.io/en/latest/
UFS_UTILS Technical Documentation	https://noaa-emcufs-utils.readthedocs.io/en/latest
UFS_UTILS Scientific Documentation	https://ufs-community.github.io/UFS_UTILS/index.html
UFS Weather Model User’s Guide	https://ufs-weather-model.readthedocs.io/en/latest
FV3 Technical Documentation	https://noaa-emc.github.io/FV3_Dycore_ufs-v2.0.0/html/index.html
FV3 Scientific Documentation	https://repository.library.noaa.gov/view/noaa/30725
CCPP Technical Documentation	https://ccpp-techdoc.readthedocs.io/en/latest/
CCPP Scientific Documentation	https://dtcenter.ucar.edu/GMTB/UFS_SRW_App_v2.2.0/sci_doc/index.html
Stochastic Physics Documentation	https://stochastic-physics.readthedocs.io/en/latest/
ESMF manual	https://earthsystemmodeling.org/docs/release/latest/ESMF_usrdoc/
Unified Post Processor User’s Guide	https://upp.readthedocs.io/en/latest/
Unified Post Processor Scientific Documentation	https://noaa-emc.github.io/UPP/
Unified Workflow User’s Guide	https://uwtools.readthedocs.io/en/main/
METplus User’s Guide	https://metplus.readthedocs.io/en/latest/Users_Guide/index.html
HEMCO User’s Guide (a component of the NEXUS AQM system)	https://hemco.readthedocs.io/en/stable/

1.1.4. User Support and Contributions to Development

1.1.4.1. Questions

The SRW App’s GitHub Discussions forum provides online support for UFS users and developers to post questions and exchange information. When users encounter difficulties running the workflow, this is the place to post. Users can expect an initial response within two business days.

When posting a question, it is recommended that users provide the following information:

The platform or system being used (e.g., Hera, Orion, MacOS, Linux)
The version of the SRW Application being used (e.g., develop, release/public-v2.2.0). (To determine this, users can run git branch, and the name of the branch with an asterisk * in front of it is the name of the branch they are working on.) Note that the version of the application being used and the version of the documentation being used should match, or users will run into difficulties.
Stage of the application when the issue appeared (i.e., configuration, build/compilation, or name of a workflow task)
Configuration file contents (e.g., config.yaml contents)
Full error message (preferably in text form rather than a screenshot)
Current shell (e.g., bash, csh) and modules loaded
Compiler + MPI combination being used

1.1.4.2. Bug Reports

If users (especially new users) believe they have identified a bug in the system, it is recommended that they first ask about the problem in GitHub Discussions, since many “bugs” do not require a code change/fix — instead, the user may be unfamiliar with the system and/or may have misunderstood some component of the system or the instructions, which is causing the problem. Asking for assistance in a GitHub Discussion post can help clarify whether there is a simple adjustment to fix the problem or whether there is a genuine bug in the code. Users are also encouraged to search open issues to see if their bug has already been identified. If there is a genuine bug, and there is no open issue to address it, users can report the bug by filing a GitHub Issue.

1.1.4.3. Feature Requests and Enhancements

Users who want to request a feature enhancement or the addition of a new feature can file a GitHub Issue and add (or request that a code manager add) the EPIC Support Requested label. These feature requests will be forwarded to the Earth Prediction Innovation Center (EPIC) management team for prioritization and eventual addition to the SRW App.

1.1.4.4. Community Contributions

The UFS community is encouraged to contribute to the development efforts of all related utilities, model code, and infrastructure. As described above, users can post issues in the SRW App to report bugs or to announce upcoming contributions to the code base. Contributions to the ufs-srweather-app repository should follow the guidelines contained in the SRW App Contributor’s Guide. Additionally, users can file issues in component repositories for contributions that directly concern those repositories. For code to be accepted into a component repository, users must follow the code management rules of that component’s authoritative repository. These rules are usually outlined in the component’s User’s Guide (see Table 1.1) or GitHub wiki for each respective repository (see Table 1.2).

1.1.5. Future Direction

Users can expect to see incremental improvements and additional capabilities in upcoming releases of the SRW Application to enhance research opportunities and support operational forecast implementations. Planned enhancements include:

Inclusion of data assimilation and forecast restart/cycling capabilities.
A more extensive set of supported developmental physics suites.
A larger number of pre-defined domains/resolutions and a fully supported capability to create a user-defined domain.
Incorporation of additional Unified Workflow tools.

[BAB+21]

T.L. Black, J.A. Abeles, B.T. Blake, D. Jovic, E. Rogers, X. Zhang, E.A. Aligo, L.C. Dawson, Y. Lin, E. Strobach, P.C. Shafran, and J.R. Carley. A limited area modeling capability for the finite-volume cubed-sphere (fv3) dynamical core. AGU Journal of Advances in Earth Modeling Systems, 2021.

[LJL+21]

H. Lin, D.J. Jacob, E.W. Lundgren, M.P. Sulprizio, C.A. Keller, T.M. Fritz, S.D. Eastham, L.K. Emmons, P.C. Campbell, B. Baker, R.D. Saylor, and R. Montuoro. Harmonized emissions component (hemco) 3.0 as a versatile emissions component for atmospheric models: application in the geos-chem, nasa geos, wrf-gc, cesm2, noaa gefs-aerosol, and noaa ufs models. Geosci. Model Dev., 14:5487–5506, 2021. doi:10.5194/gmd-14-5487-2021.

[PJK+20]

R.J. Purser, D. Jovic, G. Ketefian, T. Black, J. Beck, J. Dong, and J. Carley. The extended schmidt gnomonic grid for regional applications. Unified Forecast System (UFS) Users’ Workshop, 2020. URL: https://dtcenter.org/sites/default/files/events/2020/2-purser-james.pdf.