Technical FAQs
Frequently Asked Questions by Unified Forecast System (UFS) Community Users
UFS code is portable to Linux and Mac operating systems that use Intel or GNU compilers. The code has been tested on a variety of platforms widely used by atmospheric scientists, including NOAA Research systems (e.g., Hera, Jet, and Gaea); the National Center for Atmospheric Research (NCAR) system, Cheyenne; the National Science Foundation (NSF) system, Stampede; and various Mac laptops. Currently, support is being expanded to cover major commercial Cloud Service Providers (CSPs) including Google Cloud, AWS, and Microsoft Azure. Limited support is also available for other non-commercial high-performance computing platforms. Additionally, Singularity containers with pre-built UFS code and dependencies are available for use on any platform that supports Singularity.
Currently, there are four levels of supported platforms. On preconfigured (Level 1) platforms, the UFS code is expected to build and run out of the box. On configurable (Level 2) platforms, the prerequisite software libraries are expected to install successfully, but they are not available in a central location. Applications and models are expected to build and run without issue once the prerequisite libraries have been built. Limited-test (Level 3) and build-only (Level 4) platforms are platforms where developers have built the code but little or no pre-release testing has been conducted, respectively. A complete description of the levels of support, along with a list of preconfigured and configurable platforms can be found here.
UFS code is provided free of charge under a variety of open source licenses (see, e.g., the UFS Weather Model license). The computing power required to run certain applications may require access to a high-performance computing (HPC) system or a cloud-based system. Users can explore EPIC’s Cloud Cost Estimator tool on the User Support page to determine approximate costs for running the Short-Range Weather (SRW) Application on the cloud using Amazon Web Services (AWS). Cost information for additional cloud service providers and UFS applications will be added in the future.
UFS Code consists of several models, applications, and utilities, each with its own GitHub repository and accompanying set of documentation. UFS code is publicly available on GitHub.
It is recommended that new users start with the latest application release, which is currently the Short-Range Weather Application v2.0.0 (released June 2022).
- UFS Short-Range Weather Application 2.0.0
Release Date: 06/23/2022
Release Description: The SRW Application v2.0.0 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 SRW User’s Guide. New and improved capabilities for this release include the addition of a verification package (METplus) for both deterministic and ensemble simulations and support for four Stochastically Perturbed Perturbation (SPP) schemes. Future work will expand the capabilities of the application to include data assimilation (DA) and a forecast restart/cycling capability. Users may also view the GitHub Wiki, which includes code contribution guidelines.
In general, applications contain a full set of pre- and post-processing utilities packaged with the UFS Weather Model. They also include documentation for users to get started with the application. The repository wiki often contains additional information, such as code contribution requirements.
Other repositories and documentation for UFS Code can be found at the following locations:
| Repository | Latest Documentation |
|---|---|
Scientific Documentation – v6.0.0 (The head of the “develop” branch is slightly ahead of this documentation). |
The ufs-community GitHub Discussions page is a great place to post general questions about the UFS. Each GitHub repository within the ufs-community organization has its own Discussions page, where users can post questions specific to each UFS application, model, or component. For example, users can check out the UFS Weather Model Discussions page here. Additionally, users can find answers to previously asked questions in the UFS Forums.
UFS models and applications require a number of software libraries in order to compile. These libraries are conveniently available in a bundle via the HPC-Stack (and Spack-Stack, which is currently in active development and testing).
The software stack managed by HPC-Stack contains two categories of libraries:
- Bundled libraries (NCEPLIBS). These are libraries developed for use with NOAA weather models.
- Third-party libraries (NCEPLIBS-external). These are libraries that were developed external to the UFS Weather Model. They are general software packages that are also used by other models in the community.
HPC-Stack documentation is available here. Spack-Stack documentation is still in active development and can be viewed here.
The UFS Weather Model (WM) is constantly evolving, and new features are added at a rapid pace. Users can find those features in the develop branch, but documentation is not always available for the latest updates. The UFS WM v2.0.0 release is the most recent public release of the UFS WM and represents a snapshot of a continuously evolving system undergoing open development. Updates include:
- Expansion of supported physics suites to include FV3_RRFS_v1alpha in addition to FV3_GFS_v15p2 and FV3_GFS_v16beta.
- Increased vertical resolution of the atmospheric model from 64 to 127 levels.
A full description of updates can be found in the UFS WM documentation here.
Previous releases of the UFS WM are available to you, but we recommend using the develop branch code or the v2.0.0 release for the latest and greatest features! Users can access information about previous releases of the UFS WM in the User’s Guide for each release:
Technical documentation for the CCPP v6.0.0 release (June 2022) is available here.
CCPP continues to add new developments to the main development branch of its repositories, and these are captured in the latest CCPP documentation, available here. Users should know that this documentation may have gaps or errors, since the repository is in active development.
Scientific documentation for the CCPP v6.0.0 release (June 2022) is available here.
CCPP continues to add new developments to the main development branch of its repositories. The HEAD of the CCPP repositories is therefore slightly ahead of the scientific documentation, which points to CCPP v6.0.0.
Each UFS repository maintains its own documentation and/or wiki. Additionally, UFS models and applications use a variety of components, such as pre- and post-processing utilities and physics suites. These components also maintain their own repository, documentation, and (if applicable) wiki page. Users can often view different versions of documentation by clicking on the caret symbol at the bottom left or right of any documentation hosted on Read the Docs.
Users may find the following links helpful as they explore UFS Code:
- UFS_UTILS Preprocessing Utilities
- FV3 Dynamical Core
- Coupled Models:
- Global Workflow wiki
- Community Data Models for Earth predictive Systems (CDEPS): CDEPS Documentation
- Community Mediator for Earth Prediction Systems (CMEPS): CMEPS Documentation
- Earth System Modeling Framework (ESMF) Manual
Other Helpful Links:
Unified Post Processor (UPP) Questions
Users can find answers to many frequently asked UPP questions by referencing the UPP User’s Guide. Additional questions are included below.
No, UPP does not currently support NetCDF4.
We are not able to support all platform and compiler combinations out there but will try to help with specific issues when able. Users may request support on the UPP GitHub Discussions page. We always welcome and are grateful for user-contributed configurations.
Currently, the stand-alone release of the UPP can be utilized to output satellite fields if desired. The UPP documentation lists the grib2 fields, including satellite fields, produced by the UPP. After selecting which fields to output, the user must adjust the control file according to the instructions in the UPP documentation to output the desired fields. When outputting satellite products, users should note that not all physics options are supported for outputting satellite products. Additionally, for regional runs, users must ensure that the satellite field of view overlaps some part of their domain.
Most UFS application releases do not currently support this capability, although it is available in the Short-Range Weather (SRW) Application. This SRW App pull request (PR) added the option for users to output satellite fields using the SRW App. The capability is documented here in the SRW App User’s Guide.
If the desired variable is already available in the UPP code, then the user can simply add that variable to the postcntrl.xml file and remake the postxconfig-NT.txt file that the UPP reads. Please note that some variables may be dependent on the model and/or physics used.
If the desired variable is not already available in the UPP code, it can be added following the instructions for adding a new variable in the UPP User’s Guide.
There are a few possible reasons why a requested variable might not appear in the UPP output:
- The variable may be dependent on the model.
- Certain variables are dependent on the model configuration. For example, if a variable depends on a particular physics suite, it may not appear in the output when a different physics suite is used.
- The requested variable may depend on output from a different field that was not included in the model output.
If the user suspects that the UPP failed (e.g., no UPP output was produced or console output includes an error message like mv: cannot stat `GFSPRS.GrbF00`: No such file or directory), the best way to diagnose the issue is to consult the UPP runtime log file for errors. When using the standalone UPP with the run_upp script, this log file will be located in the postprd directory under the name upp.fHHH.out, where HHH refers to the 3-digit forecast hour being processed. When the UPP is used with the SRW App, the UPP log files can be found in the experiment directory under log/run_post_fHHH.log.
UPP output is in standard grib2 format and can be interpolated to another grid using the third-party utility wgrib2. Some basic examples can also be found in the UPP User’s Guide.
This may be a memory issue; try increasing the number of CPUs or spreading them out across nodes (e.g., increase ptiles). We also know of one version of MPI (mpich v3.0.4) that does not work with UPP. A work-around was found by modifying the UPP/sorc/ncep_post.fd/WRFPOST.f routine to change all unit 5 references (which is standard I/O) to unit 4 instead.
For re-gridding grib2 unipost output, the wgrib2 utility can be used. Complete documentation on grid specification with examples of re-gridding for all available grid definitions can be found here. The Regridding section of the UPP User’s Guide also gives examples (including an example from operations) of using wgrib2 to interpolate to various common grids.
This warning appears for some platforms/compilers because a call in the nemsio library is never used or referenced for a serial build. This is just a warning and should not hinder a successful build of UPP or negatively impact your UPP run.
This error message is displayed when using more recent versions of the wgrib2 utility on files for forecast hour zero that contain accumulated or time-averaged fields. This is due to the newer versions of wgrib2 no longer allowing for the n parameter to be zero or empty. Users should consider using a separate control file (e.g., postcntrl_gfs_f00.xml) for forecast hour zero that does not include accumulated or time-averaged fields, since they are zero anyway. Users can also continue to use an older version of wgrib2; v2.0.4 is the latest known version that does not result in this error.
