1.3. Components

The Land DA System assembles a variety of modeling, data assimilation, pre-processing, and workflow components. These components are documented within this User’s Guide and supported through the GitHub Discussions forum.

1.3.1. Modeling Components

1.3.1.1. The UFS Weather Model (WM)

The Unified Forecast System (UFS) Weather Model (WM) is a prognostic model that can be used for short- and medium-range research and operational forecasts. In addition to its use in NOAA’s operational forecast systems, the UFS WM is used in public UFS application releases, such as the most recent Land DA System and Short-Range Weather (SRW) Application releases. The WM assembles a variety of modeling components, including the FV3 atmospheric model, the Noah-MP land surface model (LSM), and the data atmosphere (DATM) model from the Community Data Models for Earth Predictive Systems (CDEPS) component. A User’s Guide for the UFS WM can be accessed here.

1.3.1.1.1. The FV3 Atmospheric Model

The UFS WM’s atmospheric model is the Finite-Volume Cubed-Sphere (FV3) dynamical core (ufsatm). The dynamical core is the computational part of a model that solves the equations of fluid motion. The Land DA System currently uses only the C96 resolution with 127 vertical levels. Additional information about the FV3 dynamical core can be found in the scientific documentation, the technical documentation, and on the NOAA Geophysical Fluid Dynamics Laboratory (GFDL) website.

1.3.1.1.1.1. Model Physics

The Common Community Physics Package (CCPP), described here, supports interoperable atmospheric physics and land surface model options. Atmospheric physics are a set of numerical methods describing small-scale processes such as clouds, turbulence, radiation, and their interactions. A full scientific description of CCPP v7.0.0 parameterizations and suites can be found in the CCPP Scientific Documentation, and CCPP technical aspects are described in the CCPP Technical Documentation.

1.3.1.1.2. Noah-MP

The UFS Land DA System has been updated to build and run the UFS Noah-MP land component of the UFS Weather Model. The land component makes use of a National Unified Operational Prediction Capability (NUOPC) cap to interface with a coupled modeling system. This Noah-MP NUOPC cap is able to create an ESMF multi-tile grid by reading in a mosaic grid file. For the domain, the FMS initializes reading and writing of the cubed-sphere tiled output. Then, the Noah-MP land component reads static information and initial conditions (e.g., surface albedo) and interpolates the data to the date of the simulation. The solar zenith angle is calculated based on the time information.

In its original form, the offline Noah-MP LSM is a stand-alone, uncoupled model used to execute land surface simulations. In this traditional uncoupled mode, near-surface atmospheric forcing data are required as input forcing. This LSM simulates soil moisture (both liquid and frozen), soil temperature, skin temperature, snow depth, snow water equivalent (SWE), snow density, canopy water content, and the energy flux and water flux terms of the surface energy balance and surface water balance.

Noah-MP uses:

  • a big-leaf approach with a separated vegetation canopy accounting for vegetation effects on surface energy and water balances,

  • a modified two-stream approximation scheme to include the effects of vegetation canopy gaps that vary with solar zenith angle and the canopy 3-D structure on radiation transfer,

  • a 3-layer physically-based snow model

  • a more permeable frozen soil by separating a grid cell into a permeable fraction and impermeable fraction,

  • a simple groundwater model with a TOPMODEL-based runoff scheme, and

  • a short-term leaf phenology model.

Noah-MP LSM enables a modular framework for diagnosing differences in process representation, facilitating ensemble forecasts and uncertainty quantification, and choosing process presentations appropriate for the application. Noah-MP developers designed multiple parameterization options for leaf dynamics, radiation transfer, stomatal resistance, soil moisture stress factor for stomatal resistance, aerodynamic resistance, runoff, snowfall, snow surface albedo, supercooled liquid water in frozen soil, and frozen soil permeability.

The Noah-MP LSM has evolved through community efforts to pursue and refine a modern-era LSM suitable for use in the National Centers for Environmental Prediction (NCEP) operational weather and climate prediction models. This collaborative effort continues with participation from entities such as NCAR, NCEP, NASA, and university groups.

The UFS Weather Model now contains a Noah-MP land component, which is used as the land component in the Land DA System. Details about the model’s physical parameterizations can be found in Niu et al. [NYM+11] (2011), and a full description of the model is available in the Community Noah-MP Land Surface Modeling System Technical Description Version 5.0.

1.3.2. Data Assimilation

The Joint Effort for Data assimilation Integration (JEDI) is a unified and versatile data assimilation (DA) system for Earth system prediction that can be run on a variety of platforms. JEDI is developed by the Joint Center for Satellite Data Assimilation (JCSDA) and partner agencies, including NOAA. In the Land DA System, JEDI software can be used to perform snow data assimilation using GHCN, IMS, or SFCSNO data with LETKF-OI or 3D-Var algorithms. Recently, the Land DA System added the capability to perform soil moisture data assimilation via JEDI with SMAP or SMOPS data.

The Land DA System uses several JEDI components, including:

  • The Object-Oriented Prediction System (OOPS) for the data assimilation algorithm

  • The Interface for Observation Data Access (IODA) for the observation formatting and processing

  • The Unified Forward Operator (UFO) for comparing model forecasts and observations

  • The System Agnostic Background Error Representation (SABER) for computing and manipulating the background error covariance matrix

  • The VAriable DErivation Repository (VADER) for producing new variables from known variables

These three components (and others) are conveniently packaged and provided via JCSDA’s jedi-bundle. Users must build/install jedi-bundle prior to using the Land DA System if they are not working on a Level 1 platform; jedi-bundle does not come packaged in the Land DA System. Users are encouraged to visit the JEDI Documentation for more information.

1.3.2.1. apply_incr.fd

The Land DA System’s apply_incr submodule points to NOAA PSL’s land-apply_jedi_incr repository. This repository contains code to add the DA increment generated by JEDI to the sfc_data restart file. A DA increment, or analysis increment, is the difference between what the model predicted and what the DA objective analysis computes as the best fit between the model state and the observations. Replacing the model state directly with the objective analysis can cause artificial shocks that will propagate through the system, so DA systems require code that slowly moves the model state towards the analysis by applying part of the increment at a time as the new forecast steps forward in time.

1.3.3. Pre-Processing/Data Conversion

The Land DA System makes use of various data pre-processing and conversion tools so that users have options for different input data sources and different Land DA configurations.

1.3.3.1. UFS_UTILS

The Land DA System includes the UFS_UTILS pre-processing software chgres_cube to convert the raw external model data into initial conditions files in netCDF format. These are needed as input to the FV3 component for the coldstart ATML configuration. Additional information about the UFS pre-processing utilities can be found in the UFS_UTILS Technical Documentation and in the UFS_UTILS Scientific Documentation.

1.3.3.2. calcfIMS.fd/land-SCF_proc

The Land DA System includes the calcfIMS.fd submodule, which points to the land surface processing repository (NOAA-EPIC/land-SFC_proc). This repository is forked from NOAA-PSL/land-SFC_proc, where the code was originally developed. It primarily consists of code for processing IMS ASCII files on the UFS model grid. As described in the repository’s README.md file, the code requires IMS ASCII files and a resolution-specific IMS index file as input. As output, the code generates (1) snow cover fraction over land on the UFS model grid, and (2) snow depth (derived from the IMS snow cover fraction, using an inversion of the Noah model snow depletion curve).

1.3.3.3. IODA Converters

The Land DA System accepts GHCN, IMS, or SFCSNO data as input for snow DA and SMAP or SMOPS data as input for soil moisture DA. The prep_data task then converts these data from their original format into the format needed by JEDI’s UFO and OOPS components for data assimilation (see Workflow Tasks). The Interface for Observation Data Access (IODA) is the component of JEDI that handles data processing for the data assimilation system (see DA Components for more). The land-DA_workfow/ush directory contains scripts (e.g., ghcn_snod2ioda.py and imsfv3_scf2ioda.py) that convert input data to a JEDI-formatted NetCDF file using IODA. The calcfIMS executable mentioned above is an intermediate converter that converts the raw ASCII files to NetCDF format before performing additional JEDI formatting.

1.3.3.4. tile2tile_converter

The tile2tile_converter is a built-in tool that handles the conversion of variable names between the Land DA System’s two main components: the UFS WM’s land model (Noah-MP) and JEDI. Table 1.4 indicates which variables are mismatched between Noah-MP and JEDI.

Table 1.4 Mismatched Variable Names

tile2tile_converter Name

Description

Land model (Noah-MP)

JEDI (sfc_data)

swe

Snow water equivalent

weasd

sheleg / weasdl

snow_depth

Snow depth over land

snwdph

snwdph / snodl

The tile2tile_converter changes the variable names in two workflow tasks:

  • In the pre_anal task, it changes from the variable names of UFS Weather Model Noah-MP component to those of JEDI.

  • In the post_anal task, it changes from the variable names of JEDI to those of the UFS WM Noah-MP component.

See Section 2.1.5.1: Workflow Tasks for more information on these workflow tasks.

1.3.4. Workflow

The Land DA System has a portable, CMake-based build system that packages together the components necessary for running the end-to-end Land DA System, including:

  • The UFS Weather Model (particularly its FV3, Noah-MP, and CDEPS components)

  • Data processing software (e.g., UFS_UTILS, tile2tile_converter, IODA converters)

  • Configuration tools (JEDI Configuration Builder, Unified Workflow Tools)

Additional libraries necessary for the Land DA System must be installed separately via spack-stack and jedi-bundle unless users are working on a supported platform or using a container. Once built, users can generate a Rocoto-based workflow that will run each task in the proper sequence (see Chapter 4.1 or the Rocoto documentation for more information on Rocoto and workflow management). The workflow makes use of several configuration tools:

The Land DA System allows users to configure various elements of the workflow. For example, users can modify the start and end cycles for the experiment, the cycling frequency, and the duration of each forecast. It also allows for configuration of other elements of the workflow, such as the data assimilation algorithm. More information on configurable variables is available in Section 3.1.

1.3.4.1. JEDI Configuration Builder (JCB)

The JEDI Configuration Builder (JCB) is a python package used to assemble information on JEDI algorithms (e.g., letkf-oi, 3dvar) and data assimilation types (e.g., snow, marine, atmosphere) into one convenient YAML file for use in data assimilation applications. The jcb-algorithms repository contains YAML algorithm files (e.g., LETKF-OI, 3DVar) for JCB; these files contain the high-level configuration structure that is prescribed by the JEDI data assimilation system. The jcb-gdas repository contains information for different types of analysis (e.g., snow, marine, atmosphere). For more information, see Section 3.3.2: JCB.

1.3.4.2. Unified Workflow (UW) Tools (uwtools)

uwtools is a modern, open-source Python package that helps automate common tasks needed for many standard numerical weather prediction (NWP) workflows. It also provides drivers to automate the configuration and execution of UFS components, providing flexibility, interoperability, and usability to various UFS applications. The Unified Workflow (UW) tools are accessible from both a command-line interface (CLI) and a Python API. The CLI automates many core NWP workflow functions; the API supports all CLI operations and additionally provides access to in-memory objects to facilitate more novel use cases. These options allow users to integrate the package into pre-existing bash and Python scripts, in addition to providing some handy tools for use in day-to-day work with NWP systems. The uwtools Rocoto tool has been incorporated into the Land DA System to generate and validate the Rocoto XML file used to run the workflow tasks. More details about UW tools can be found in the uwtools GitHub repository and in the UW Documentation.