Skip to content

Commit

Permalink
[release/public-v2.0.0]: Documentation Updates (#155)
Browse files Browse the repository at this point in the history 
* Update ConfigWorkflow.rst

added new variables for workflow entities

* Update ConfigWorkflow.rst

added definitions for new variables

* Update ConfigWorkflow.rst

added in specific info for hercules

* update Intro

* add plotting instructions/note

* update links to UFS website

* update Introduction

* format model explanation

* update intro

* Update ConfigWorkflow.rst

added new variables for the WE2E update

* update tech overview

* minor updates/hints for running land da

* update tech overview

* Update doc/source/CustomizingTheWorkflow/ConfigWorkflow.rst

Co-authored-by: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com>

* Update doc/source/CustomizingTheWorkflow/ConfigWorkflow.rst

Co-authored-by: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com>

* Update doc/source/CustomizingTheWorkflow/ConfigWorkflow.rst

Co-authored-by: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com>

* Update doc/source/CustomizingTheWorkflow/ConfigWorkflow.rst

Co-authored-by: Gillian Petro <96886803+gspetro-NOAA@users.noreply.github.com>

* misc updates

* misc updates

* misc updates throughout; add FAQ

* misc updates; we2e note

* factor out module load statements; misc other updates

* update Model ch

* add doc-snippets; misc edits

* update FAQ

* edit load-env

* add EXP_BASEDIR mention

* add uw template/renamed XML info

* update B/R ch w/parm_xml.yaml refs

* misc updates, WE2E_VAV, etc.

* update FAQ

* update Config ch

* misc updates

* update container name

* update container ch

* misc minor updates

* update container & testing chs

* add container testing info

* minor Tech Overview edits

* misc minor edits

* add links to ignore

* add container CTest caveat

* update LETKF wording

---------

Co-authored-by: Brandon Selbig <156852197+selbigmtnwx23@users.noreply.github.com>
  • Loading branch information
@gspetro-NOAA @selbigmtnwx23
gspetro-NOAA and selbigmtnwx23 authored Oct 29, 2024
1 parent 597c38d commit a7e90a9
Show file tree
Hide file tree
Showing 16 changed files with 366 additions and 234 deletions.
6 changes: 3 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

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://ufs.epic.noaa.gov/.

The UFS includes [multiple applications](https://ufscommunity.org/science/aboutapps/) that support different forecast durations and spatial domains. This repository hosts the source code for the UFS Land Data Assimilation (DA) System. Land DA is an offline version of the Noah Multi-Physics (Noah-MP) land surface model (LSM) used in the UFS Weather Model (WM). Its data assimilation framework uses the Joint Effort for Data assimilation Integration (JEDI) software stack, which includes the Object-Oriented Prediction System (OOPS) for the data assimilation algorithm, the Interface for Observation Data Access (IODA) for observation formatting and processing, and the Unified Forward Operator (UFO) for comparing model forecasts and observations.
The UFS includes [multiple applications](https://ufs.epic.noaa.gov/applications/) that support different forecast durations and spatial domains. This repository hosts the source code for the UFS Land Data Assimilation (DA) System. Land DA is an offline version of the Noah Multi-Physics (Noah-MP) land surface model (LSM) used in the UFS Weather Model (WM). Its data assimilation framework uses the Joint Effort for Data assimilation Integration (JEDI) software stack, which includes the Object-Oriented Prediction System (OOPS) for the data assimilation algorithm, the Interface for Observation Data Access (IODA) for observation formatting and processing, and the Unified Forward Operator (UFO) for comparing model forecasts and observations.

The offline Noah-MP LSM is a standalone, uncoupled model used to execute land surface simulations. In this traditional uncoupled mode, near-surface atmospheric forcing data is 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. Its data assimilation framework applies the Local Ensemble Transform Kalman Filter-Optimal Interpolation (LETKF-OI) algorithm to combine the state-dependent background error derived from an ensemble forecast with the observations and their corresponding uncertainties to produce an analysis ensemble (Hunt et al., 2007).

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 development branch of the Land DA System is continually evolving as the system undergoes open development. The latest Land DA release (v1.2.0) represents a snapshot of this continuously evolving system.

The Land DA System User's Guide associated with the development branch is at: https://land-da-workflow.readthedocs.io/en/develop/, while the guide specific to the Land DA v1.2.0 release can be found at: https://land-da-workflow.readthedocs.io/en/release-public-v1.2.0/. Users may download data for use with the most recent release from the [Land DA data bucket](https://registry.opendata.aws/noaa-ufs-land-da/). The [Land DA Docker Hub](https://hub.docker.com/r/noaaepic/ubuntu20.04-intel-landda) hosts Land DA containers. These containers package the Land DA System together with all its software dependencies for an easier experience building and running Land DA.
The Land DA System User's Guide associated with the development branch is at: https://land-da-workflow.readthedocs.io/en/develop/, while the guide specific to the Land DA v2.0.0 release can be found at: https://land-da-workflow.readthedocs.io/en/release-public-v2.0.0/. Users may download data for use with the most recent release from the [Land DA data bucket](https://registry.opendata.aws/noaa-ufs-land-da/). The [Land DA Docker Hub](https://hub.docker.com/r/noaaepic/ubuntu22.04-intel21.10-landda) hosts Land DA containers. These containers package the Land DA System together with all its software dependencies for an easier experience building and running Land DA.

For any publications based on work with the UFS Offline Land Data Assimilation System, please include a citation to the DOI below:

UFS Development Team. (2023, Dec. 11). Unified Forecast System (UFS) Land Data Assimilation (DA) System (Version v1.2.0). Zenodo. https://doi.org/10.5281/zenodo.7675721
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

3 changes: 0 additions & 3 deletions doc/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,6 @@ help:

.PHONY: help Makefile linkcheck

help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

doc:
make clean
$(MAKE) linkcheck
Expand Down
62 changes: 37 additions & 25 deletions doc/source/BackgroundInfo/Introduction.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,32 @@ This User's Guide provides guidance for running the Unified Forecast System
the Joint Effort for Data assimilation Integration (:term:`JEDI`) software. Currently, the offline UFS Land DA System only works with snow data.
Thus, this User's Guide focuses primarily on the snow DA process.

Since the |latestr| release, the following capabilities have been added to the Land DA System:
The following improvements have been made to the Land DA System ahead of the |latestr| release:

* Added cycled run capability (:land-wflow-repo:`PR #101 <pull/101/>`)
* Provide automated run option using cron (:land-wflow-repo:`PR #110 <pull/110>`)
* Added analysis plotting task (:land-wflow-repo:`PR #107 <pull/107>`)
* Provided automated run option using cron (:land-wflow-repo:`PR #110 <pull/110>`)
* Incorporated `Unified Workflow Tools <https://github.com/ufs-community/uwtools>`_:

* Added Rocoto tool to produce the Rocoto workflow XML file from a YAML configuration file (:land-wflow-repo:`PR #47 <pull/47>`)
* Added template tool to render a configuration file from a template (:land-wflow-repo:`PR #153 <pull/153>`)
* Added plotting options:

* Analysis plotting task (:land-wflow-repo:`PR #107 <pull/107>`)
* Plotting option for forecast task restart files (:land-wflow-repo:`PR #149 <pull/149>`)
* Time-history plots (:land-wflow-repo:`PR #151 <pull/151>`)
* Extended and updated container support (:land-wflow-repo:`PR #85 <pull/85>` and :land-wflow-repo:`PR #147 <pull/147>`)
* Ported ``land-DA_workflow`` to Hercules (:land-wflow-repo:`PR #133 <pull/133>`)
* Added prerequisites for workflow end-to-end (WE2E) testing capability (:land-wflow-repo:`PR #131 <pull/131>`)
* Upgraded to JEDI Skylab v7.0 (:land-wflow-repo:`PR #92 <pull/92/>`)
* Upgraded to spack-stack v1.6.0 (:land-wflow-repo:`PR #102 <pull/102>`)
* Extended container support (:land-wflow-repo:`PR #85 <pull/85>`)
* Updated directory structure for NCO compliance (:land-wflow-repo:`PR #75 <pull/75>`)
* Updated directory structure for NCO compliance (e.g., :land-wflow-repo:`PR #75 <pull/75>`)
* Added platform test to CTest & updated version of UFS WM (:land-wflow-repo:`PR #146 <pull/146>`)
* Removed land driver from CTest (:land-wflow-repo:`PR #123 <pull/123>`)
* Removed land-driver and vector2tile (:land-wflow-repo:`PR #129 <pull/129>`)
* Removed land driver and vector2tile (:land-wflow-repo:`PR #129 <pull/129>`)

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. (2023, December 11). Unified Forecast System (UFS) Land Data Assimilation (DA) System (Version v1.2.0). Zenodo. https://doi.org/10.5281/zenodo.7675721

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

Organization
**************
Expand All @@ -39,9 +49,9 @@ Background Information
Building, Running, and Testing the Land DA System
===================================================

* :numref:`Chapter %s: Land DA Workflow <BuildRunLandDA>` explains how to build and run the Land DA System on :ref:`Level 1 <LevelsOfSupport>` systems (currently Hera and Orion).
* :numref:`Chapter %s: Land DA Workflow <BuildRunLandDA>` explains how to build and run the Land DA System on :ref:`Level 1 <LevelsOfSupport>` systems (currently Hera, Orion, and Hercules).
* :numref:`Chapter %s: Containerized Land DA Workflow <Container>` explains how to build and run the containerized Land DA System on non-Level 1 systems.
* :numref:`Chapter %s: Testing the Land DA Workflow <TestingLandDA>` explains how to run the Land DA CTests.
* :numref:`Chapter %s: Testing the Land DA Workflow <TestingLandDA>` explains how to run Land DA System tests.

Customizing the Workflow
=========================
Expand All @@ -63,11 +73,11 @@ User Support and Documentation
Questions
==========

The Land DA System's `GitHub Discussions <https://github.com/ufs-community/land-DA_workflow/discussions/categories/q-a>`__ 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.
The Land DA System's `GitHub Discussions <https://github.com/ufs-community/land-DA_workflow/discussions/categories/q-a>`_ 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, MacOS, Linux)
* 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-v1.1.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
Expand All @@ -86,8 +96,8 @@ Feature Requests and Enhancements

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

#. File a `GitHub Issue <https://github.com/ufs-community/land-DA_workflow/issues/new>`__ and add (or request that a code manager add) the ``EPIC Support Requested`` label.
#. Post a request for a feature or enhancement in the `Enhancements <https://github.com/ufs-community/land-DA_workflow/discussions/categories/enhancements>`__ category of GitHub Discussions. These feature requests will be forwarded to the Earth Prediction Innovation Center (`EPIC <https://epic.noaa.gov/>`__) management team for prioritization and eventual addition to the Land DA System.
#. File a `GitHub Issue <https://github.com/ufs-community/land-DA_workflow/issues/new>`_ and add (or request that a code manager add) the ``EPIC Support Requested`` label.
#. Post a request for a feature or enhancement in the `Enhancements <https://github.com/ufs-community/land-DA_workflow/discussions/categories/enhancements>`_ category of GitHub Discussions. These feature requests will be forwarded to the Earth Prediction Innovation Center (`EPIC <https://epic.noaa.gov/>`_) management team for prioritization and eventual addition to the Land DA System.
#. Email the request to support.epic@noaa.gov.


Expand All @@ -99,10 +109,10 @@ Background Information
Unified Forecast System (UFS)
===============================

The UFS is a community-based, coupled, comprehensive Earth modeling system. It includes `multiple applications <https://ufscommunity.org/science/aboutapps/>`__ that support different forecast durations and spatial domains. NOAA's operational model suite for numerical weather prediction (:term:`NWP`) is quickly transitioning to the UFS from many different modeling systems.
The UFS is a community-based, coupled, comprehensive Earth modeling system. It includes :ufs:`multiple applications <applications>` that support different forecast durations and spatial domains. NOAA's operational model suite for numerical weather prediction (:term:`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 :term:`Weather Enterprise` (including
government, industry, and academia). For more information about the UFS, visit the `UFS Portal <https://ufscommunity.org/>`__.
government, industry, and academia). For more information about the UFS, visit the :ufs:`UFS Portal <>`.


.. _NoahMP:
Expand All @@ -112,22 +122,24 @@ Noah-MP

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 :term:`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
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 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 (:term:`NCEP`) operational weather and climate prediction models. This collaborative effort continues with participation from entities such as NCAR, NCEP, NASA, and university groups.

Noah-MP has been implemented in the UFS via the :term:`CCPP` physics package and
is currently being tested for operational use in GFSv17 and RRFS v2. Additionally, the UFS Weather Model now contains a Noah-MP land component. Noah-MP has
Expand Down
Loading

0 comments on commit a7e90a9

Please sign in to comment.