Skip to content

Documentation for running Idealized TC case and tutorial for adding cases to the HSD framework #2746

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jdkublnick wants to merge 8 commits into from
Closed

Documentation for running Idealized TC case and tutorial for adding cases to the HSD framework #2746

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f9ff72d
Adding Idealized TC case run instructions
May 21, 2025
8fb28df
Instructions for adding a test case to HSD framework
May 21, 2025
4b3b86b
Format update
May 21, 2025
98193d0
Minor format update
May 21, 2025
c76ad2e
Title update
May 21, 2025
b2c3c7f
Resolving Camerons Feedback
May 22, 2025
8df519c
Format update
May 22, 2025
8d0cc20
Adding in case details to introduction
May 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions doc/UsersGuide/source/AddingHSDCase.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
.. _add-hsd-case:

*******************************************************************
General Guidelines for Adding a Test Case to the UFS HSD Framework
*******************************************************************

A user wishing to add a test case to the Unified Forecast System (UFS) Hierarchical System Development (HSD) framework via the ``tests-dev`` directory will generally adhere to the following procedure to ensure the proper integration of the test case inside the UFS Weather Model (WM).

After selecting the case of interest (e.g., idealized case, model improvement, process/phenomenon/component isolation, etc.), the user can either utilize an existing model configuration (e.g., ``ATM``, ``S2S``, ``S2SWA``, ``HAFSW``) if the case can make use of a pre-existing model configuration or bring in their own executable. However, if a new model configuration is needed, the code changes necessary to introduce the new model configuration/executable are the responsibility of the user to add to the UFS-WM. Therefore, the process to introduce a new model configuration is beyond the scope of this document.

For the cases currently in the UFS HSD, only the atmospheric model is utilized, and the ``ATM`` model configuration option is used. This is called at compile time in the CMake build system command with ``-DAPP=ATM``. A tropical cyclone case (currently in development) will utilize the ``HAFSW`` model configuration (i.e., ``-DAPP=HAFSW``). Therefore, cases that can utilize the ``ATM`` or ``HAFSW`` model configurations serve as good starting points.

================================
General Steps to Add a Test Case
================================

To add a test case to be run with ``ufs_test.sh`` in ``tests-dev``, the user must update ``ufs_test.yaml``. The new case should be added under the ``tests:`` section of the model configuration that corresponds to the specific model configuration/executable it will be run with.

For example, to add an “atmosphere-only” case using “FV3” and the “Intel” compiler, users would add their new test case name in the ``ufs_test.yaml`` file by updating the ``tests:`` section under ``atm_dyn32_intel`` configuration. For these new test cases, set the ``project`` option to ``test_case`` and ``baseline`` option to ``True``. For an Intel example, please refer to ``2020_CAPE`` and ``baroclinic_wave`` test cases under ``ufs_test.yaml#L108``. Users can also add a GNU-based test (see where the ``baroclinic_wave`` test was added).

A test case file corresponding to each of these new HSD test cases needs to be added under:

https://github.com/ufs-community/ufs-weather-model/tree/develop/tests-dev/test_cases/tests/

This test case file exports model, I/O, resource settings, and several other parameters to the ``ufs_test.sh`` workflow and sets the CCPP suite, input namelist, model configuration, diagnostic table, field table, and ``FV3_run`` files that will be used in conjunction with the HSD test cases. Refer to Section 5, *Configuration Files*, for details on updating the configuration files corresponding to these HSD test cases.

=====================
Model Compile Options
=====================

Model compile options are set in ``ufs_test.yaml``. Default compile options are set in the ``options`` section (e.g., model mode such as ``ATM``), CCPP suites, etc. Users can add compile options here. If a physics suite needs to be added for the case, it should be added to the ``CCPP_SUITES`` section of the compile options.

In addition to setting the model compile options, users should consider which compiler they wish their model to be built with. Intel and GNU options are generally supported in the UFS-WM. To enable compilation of the model with both Intel and GNU, ensure that the new HSD test case is added under the appropriate section in both the Intel and GNU components of the ``ufs_test.yaml`` file.

========
Physics
========

UFS-WM supports options from the CCPP. Users can select a suite to use for their case that properly captures the physical processes and parametrizations required for the specific scientific case. The suite should be included in the compile options (see section *Model Compile Options*) and can be exported in the test case file. This is then added to the case's input namelist file, if it is a dynamic variable.

Users can bring in their own physics suites, but would need to submit a PR to the CCPP repository before this can be incorporated into the UFS-WM.

===========
Input Data
===========

The user is responsible for generating, staging, and properly pointing all configuration files to the appropriate input data for the specific HSD test case (e.g., initial/boundary conditions, restart files, etc.). Input data copying from fixed directories on RHDPCS platforms into the test case run directory is handled in the workflow via the ``FV3_run`` file, so this file should include lines to copy the necessary data into the run directory.

- Input data such as ICs/BCs should be copied into the ``INPUT`` directory of the run directory.
- Restart files (for warm starts) should be copied into the ``RESTART`` directory.

Input data can be generated via ``UFS_UTILS`` or the user’s own scripts, as long as it matches the format/variable structure required by the UFS-WM component(s) that the HSD test case will utilize (e.g., for atmosphere-only cases, GFS data such as ``gfs.*.nc``, ``sfc*.nc``, ``orog*.nc``, and gridding files are required).

=====================
Configuration Files
=====================

Input namelist, model configure, UFS configuration, diagnostic table, and field tables should be added in conjunction with the HSD test case. At minimum, a namelist and ``FV3_run`` file should be included that is appropriate for the test case. The ``FV3_run`` file is used by the workflow to read in exported values from the tests file and properly stage input/restart data and fix files.

Default model configurations, UFS configurations, diagnostic table, and field tables may be used, but the user should confirm that these are appropriate for their specific HSD test case. Users may reference other UFS-WM regression test files and namelists, model configurations, UFS configurations, diagnostic/field tables, and ``FV3_run`` files for help in setting up their own files.

- Namelists, model configuration, diagnostic/field tables, and UFS configuration files should be added to:

https://github.com/ufs-community/ufs-weather-model/tree/develop/tests-dev/test_cases/parm

- The ``FV3_run`` file should go in:

https://github.com/ufs-community/ufs-weather-model/tree/develop/tests-dev/test_cases/exp_conf

============
Fix Files
============

The user is responsible for staging all fix files needed for the case. The ``FV3_run`` file should include lines to copy the necessary fix files from fixed directories on RHDPCS into the HSD test case run directory.

See ``*.IN`` files in:

https://github.com/ufs-community/ufs-weather-model/tree/develop/tests-dev/test_cases/exp_conf

or:

https://github.com/ufs-community/ufs-weather-model/blob/develop/tests/fv3_conf/control_run.IN

for examples of how this is done.

==========================
Running the Test Case
==========================

With the test case added to ``ufs_test.yaml``, all necessary configuration files in place, any source code changes made to relevant subcomponents, and input and fix file data staged, the user should be able to perform a test run of their case from the ``tests-dev`` directory using:

.. code-block:: console

./ufs_test.sh -a <account> -s -r -c -n "<test_name> <compiler_option>"
3 changes: 3 additions & 0 deletions doc/UsersGuide/source/HSD.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,15 @@ Although the UFS Weather Model (WM) can be run in any of several configurations,

CAPE2020
baroclinic_wave
IdealizedTC
AddingHSDCase
HSDcontainer

Currently, users can find information on running the following HSD cases:

* The :ref:`July 2020 CAPE Case <cape-2020>`
* The :ref:`Baroclinic Instability Case <baroclinic-wave>`
* The :ref:`Idealized, Regional Tropical Cyclone Case <idealized-tc>`

For a full list of supported WM configurations, view the `rt.conf <https://github.com/ufs-community/ufs-weather-model/blob/develop/tests/rt.conf>`_ file.

Expand Down
122 changes: 122 additions & 0 deletions doc/UsersGuide/source/IdealizedTC.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
.. role:: raw-html(raw)
:format: html

.. _idealized-tc:

**************************************
Idealized, Regional Tropical Cyclone Case
**************************************

The idealized, regional tropical cyclone case is derived from the I-HAFS configuration (:cite:t:`Wang2024`) and is designed to support controlled studies of tropical cyclone dynamics and forecast development. This configuration removes real-world data assimilation and ocean coupling, focusing solely on atmospheric forecasts using idealized inputs.

The case is configured to run at 4-km resolution, with 81 vertical levels. The forecast is initialized on 24 August 2019, and initial/lateral boundary conditions are provided for up to a five-day forecast duration. Initial and lateral boundary conditions (ICs/LBCs) are derived from a large-scale, idealized global FV3-based atmospheric forecast. The initial vortex is constructed using the Reed and Jablonowski (2011) method, introducing a weak, balanced storm into an environment favorable for rapid intensification.

This idealized test case uses components derived from the I-HAFS configuration, but within the UFS HSD framework the workflow is simplified. The following capabilities are available to users running this case:

- FV3-based forecast integration
- Adjustable physics suites, namelist settings, and computational parameters
- Optional vortex initialization is present in I-HAFS, but not invoked in this test case
- Postprocessing and preprocessing steps (e.g., IC/LBC generation, terrain setup) are handled outside of this test case and are not included in the ``ufs-weather-model`` workflow

.. note::

While the I-HAFS system includes preprocessing to set up the forecast and nest domains and postprocessing to generate GRIB2 and ATCF output files, this UFS HSD test case **does not** perform those steps. It relies on pre-generated ICs/LBCs, which are provided as part of the test data.

The script below generates 10-m wind plots from the model's GRIB output and can create an animated GIF to visualize the tropical cyclone's evolution.

.. code-block:: console

ufs-weather-model/tests-dev/test_cases/utils/plot_tc.sh

This test case provides a simplified environment to study TC dynamics and forecast behavior. Future development plans include incorporating idealized ocean and wave modules and expanding vortex customization options.

============================
Obtaining Data for HSD Cases
============================

.. include:: ./doc-snippets/hsd_data.rst

.. _run-TC:

=================================================
Running the Idealized Tropical Cyclone Test Case
=================================================

This section explains how to run the Idealized Tropical Cyclone case described above using the ``ufs_test.sh`` script.

Clone the Repository
--------------------

.. include:: ./doc-snippets/clone_hsd.rst

Machine Configuration
----------------------

.. include:: ./doc-snippets/hsd_machine_config.rst

.. _idealized-config:

Test Configuration
-------------------

By default, the forecast length and runtime settings for this idealized tropical cyclone test case are conservative and may need adjustment to simulate a complete tropical cyclone lifecycle.

In the file:

``ufs-weather-model/tests-dev/test_cases/tests/tropical_cyclone``

the following variables can be modified:

.. code-block:: console

FH_MAX=3

Change to:

.. code-block:: console

FH_MAX=120

This sets the forecast length to 120 hours (approximately 5 days), which matches the length supported by the provided IC/LBC data.

Also, the wallclock time limit is set as:

.. code-block:: console

WLCLK=00:30

Change to something like:

.. code-block:: console

WLCLK=08:00

This allows enough time (6–8 hours recommended) for the full 120-hour simulation to run, depending on system performance.

Running tests
-------------

.. include:: ./doc-snippets/hsd_run_tests.rst

Example:
^^^^^^^^^

Users with access to the ``epic`` account can run the ``tropical_cyclone`` test case with the ``intel`` compiler on :term:`RDHPCS` where they have access using the following command:

.. code-block:: console

./ufs_test.sh -a epic -s -c -k -r -n "tropical_cyclone intel"

Checking Results
-------------------

.. include:: ./doc-snippets/hsd_check_results.rst

For example, to monitor progress or check results for the ``tropical_cyclone`` case, run:

.. code-block:: console

tail -f ${UFS_WM}/tests-dev/run_dir/tropical_cyclone_intel/err
tail -f ${UFS_WM}/tests-dev/run_dir/tropical_cyclone_intel/out

.. include:: ./doc-snippets/hsd_notes.rst
2 changes: 1 addition & 1 deletion doc/UsersGuide/source/doc-snippets/hsd_run_tests.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Launch tests from the ``${UFS_WM}/tests-dev`` directory with the following comma
where:

* ``<ACCOUNT>``: Account/project number for batch jobs.
* ``<CASE_NAME>``: Name of the test case (e.g., ``2020_CAPE`` or ``baroclinic_wave``).
* ``<CASE_NAME>``: Name of the test case (e.g., ``2020_CAPE``, ``baroclinic_wave``, or ``tropical_cyclone``).
* ``<COMPILER>``: Compiler used for the tests (``intel`` or ``gnu``).

**Command-line Options:**
Expand Down
8 changes: 8 additions & 0 deletions doc/UsersGuide/source/references.bib
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,3 +40,11 @@ @article{Jablonowski&Williamson2006
doi={https://doi.org/10.1256/qj.06.12},
year={2006},
}
@article{Wang2024,
title={An Idealized Hurricane Analysis and Forecast System (I-HAFS)},
author={Wang, Weiguo and Weng, Yonghui and Wang, Chuan-Kai and Peng, Jiayi and Liu, Bin and Zhang, Zhan},
journal={Manuscript in preparation},
url={https://wgne.net/bluebook/uploads/2024/docs/09_Wang_Weiguo_IdealizedHurricaneAnalysisForecastSystem.pdf},
year={2024},
}