1.1. Introduction

1.1.1. Unified Forecast System (UFS)

The UFS is a community-based, coupled, comprehensive Earth modeling system. It includes multiple applications that support different forecast durations and spatial domains. NOAA’s operational model suite for numerical weather prediction (NWP) is quickly transitioning to the UFS from many different modeling systems. The UFS is designed to enable 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.

1.1.2. The Land DA System

This User’s Guide provides guidance for running the Unified Forecast System (UFS) Land Data Assimilation (DA) System. Land DA uses the Noah Multi-Physics (Noah-MP) land surface model (LSM) from the UFS Weather Model (WM), which can be coupled with an active atmospheric component (FV3) or the WM data atmosphere component (DATM) if desired. Its data assimilation framework uses the Joint Effort for Data assimilation Integration (JEDI) software. Currently, the UFS Land DA System only works with snow data. Thus, this User’s Guide focuses primarily on the snow DA process.

The following improvements have been made to the Land DA System since the v2.0.0 release:

  • Support for a new coupling option — LND (Noah-MP) and ATM (FV3) — (PR #171)

  • Addition of 3DVar to JEDI algorithm (PR #187)

  • Integration of JEDI Configuration Builder (JCB) into Land DA System (PR #182)

  • Creation of JEDI configuration/input files (PR #182) for LETKF (PR #190) and 3DVar (PR #188) using JCB

  • Inclusion of jcb-algorithms and jcb-gdas as Land DA submodules to facilitate DA configuration with JCB (PR #179)

  • Add capability to use IMS snow observation data by converting it to NetCDF form in the prep_data workflow task (PR #222) ; improve IMS data processing capabilities (PR #224)

  • Add ERA5 forcing option for APP=LND (PR #214); improve ERA5 data processing capabilities (PR #219)

  • Port Land DA System to Gaea C6 (PR #211) and provide container support for Gaea (PR #177)

  • Enhancements to post-processing plots (PR #192)

  • Replace JEDI Skylab with GDAS-sync’d JEDI-bundle (PRs #203, #209)

  • Update submodule hashes (PR #200)

  • Update CCPP physics suite for APP=ATML (PR #216)

  • Add sample configuration for CADRE DA training (PR #227)

  • Update Land DA develop branch container (PR #228)

  • Jenkins CI/CD pipeline and testing improvements (PRs #174, #199, #225, #229)

  • Bug fixes, minor updates, and refactoring since the v2.0.0 release (PRs #184, #191, #195, #197, #205, #207, #217, #221, #230, #231)

The Land DA System citation is as follows and should be used when presenting results based on research conducted with the Land DA System:

UFS Development Team. (2024, October 30). Unified Forecast System (UFS) Land Data Assimilation (DA) System (Version v2.0.0). Zenodo. https://doi.org/10.5281/zenodo.13909475

1.1.2.1. Organization

This User’s Guide is organized into four sections: (1) Background Information; (2) Building, Running, and Testing the Land DA System; (3) Customizing the Workflow; and (4) Reference.

1.1.3. Background Information

  • This chapter (Introduction) provides user support information and background information on the Unified Forecast System (UFS) and the Noah-MP model.

  • Chapter 1.2 (Technical Overview) outlines prerequisites, supported systems, and directory structure.

  • Chapter 1.3 (Components) describes the components that comprise the Land DA System.

1.1.4. Building, Running, and Testing the Land DA System

1.1.5. Customizing the Workflow

1.1.6. Reference

1.1.6.1. User Support and Documentation

1.1.7. Questions

The Land DA System’s GitHub Discussions forum provides online support for UFS users and developers to post questions and exchange information. When users encounter difficulties running the Land DA System, 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, container)

  • The version of the Land DA System being used (e.g., develop, release/public-v2.0.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 or tag they are working with.) Note that the Land DA version 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., build/compilation, configuration, or forecast run)

  • Contents of relevant configuration files

  • 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

  • Run directory and code directory, if available on supported platforms

1.1.8. 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.9. Feature Requests and Enhancements

Users who want to request a feature enhancement or the addition of a new feature have a few options:

  1. File a GitHub Issue and add (or request that a code manager add) the EPIC Support Requested label.

  2. Post a request for a feature or enhancement in the Enhancements category of GitHub Discussions. These feature requests will be forwarded to the Earth Prediction Innovation Center (EPIC) management team for prioritization and eventual addition to the Land DA System.

  3. Email the request to support.epic@noaa.gov.

1.1.9.1. Disclaimer

The United States Department of Commerce (DOC) GitHub project code is provided on an “as is” basis and the user assumes responsibility for its use. DOC has relinquished control of the information and no longer has a responsibility to protect the integrity, confidentiality, or availability of the information. Any claims against the Department of Commerce stemming from the use of its GitHub project will be governed by all applicable Federal laws. Any reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise, does not constitute or imply their endorsement, recommendation, or favoring by the Department of Commerce. The Department of Commerce seal and logo, or the seal and logo of a DOC bureau, shall not be used in any manner to imply endorsement of any commercial product or activity by DOC or the United States Government.

1.1.9.2. References

[HEJKS07]

B.R. Hunt, E.J. Kostelich, and I. Szunyogh. Efficient data assimilation for spatiotemporal chaos: a local ensemble transform kalman filter. Physica D: Nonlinear Phenomena, 230(1–2):112–126, 2007. doi:10.1016/j.physd.2006.11.008.

[NYM+11]

G.-Y. Niu, Z.-L. Yang, K.E. Mitchell, F. Chen, M.B. Ek, M. Barlage, A. Kumar, K. Manning, D. Niyogi, E. Rosero, M. Tewari, and Y. Xia. Simple water balance model for estimating runoff at different spatial and temporal scales. Journal of Geophysical Research, 2011. doi:10.1029/2010JD015139.