ufs-community · jkbk2004 · May 23, 2025 · Apr 7, 2025 · Apr 7, 2025 · Apr 8, 2025
diff --git a/doc/UsersGuide/source/AddingHSDCase.rst b/doc/UsersGuide/source/AddingHSDCase.rst
@@ -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>"
diff --git a/doc/UsersGuide/source/HSD.rst b/doc/UsersGuide/source/HSD.rst
@@ -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.
 

diff --git a/doc/UsersGuide/source/IdealizedTC.rst b/doc/UsersGuide/source/IdealizedTC.rst
@@ -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
diff --git a/doc/UsersGuide/source/doc-snippets/hsd_run_tests.rst b/doc/UsersGuide/source/doc-snippets/hsd_run_tests.rst
@@ -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:**

diff --git a/doc/UsersGuide/source/references.bib b/doc/UsersGuide/source/references.bib
@@ -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},
+}
+
diff --git a/tests-dev/baseline_setup.yaml b/tests-dev/baseline_setup.yaml
@@ -47,9 +47,9 @@ gaeac6:
   PTMP: /gpfs/f6/${ACCNR}/proj-shared/${USER}/RT_RUNDIR
   RUNDIR_ROOT:
   SCHEDULER: slurm
-  INPUTDATA_ROOT: /gpfs/f5/epic/world-shared/UFS-WM_RT/NEMSfv3gfs/input-data-20250507
-  INPUTDATA_ROOT_WW3: /gpfs/f5/epic/world-shared/UFS-WM_RT/NEMSfv3gfs/input-data-20250507/WW3_input_data_20250225
-  INPUTDATA_ROOT_BMIC: /gpfs/f5/epic/world-shared/UFS-WM_RT/NEMSfv3gfs/BM_IC-20220207
+  INPUTDATA_ROOT: /gpfs/f6/bil-fire8/world-shared/role.epic/UFS-WM_RT/NEMSfv3gfs/input-data-20250507
+  INPUTDATA_ROOT_WW3: /gpfs/f6/bil-fire8/world-shared/role.epic/UFS-WM_RT/NEMSfv3gfs/input-data-20250507/WW3_input_data_20250225
+  INPUTDATA_ROOT_BMIC: /gpfs/f6/bil-fire8/world-shared/role.epic/UFS-WM_RT/NEMSfv3gfs/BM_IC-20220207
 derecho:
   QUEUE: main
   COMPILE_QUEUE: main

diff --git a/tests-dev/create_xml.py b/tests-dev/create_xml.py
@@ -9,7 +9,7 @@ def rocoto_create_entries(RTPWD,MACHINE_ID,INPUTDATA_ROOT,INPUTDATA_ROOT_WW3,INP
 
     Args:
         RTPWD (str): Baseline directory
-        MACHINE_ID (str): Machine ID i.e., Hera, Gaea, Jet, etc.
+        MACHINE_ID (str): Machine ID i.e., Hera, GaeaC6, Jet, etc.
         INPUTDATA_ROOT (str): Input data directory
         INPUTDATA_ROOT_WW3 (str): WW3 input data directory
         INPUTDATA_ROOT_BMIC (str): BMIC input data directory
@@ -48,7 +48,7 @@ def rocoto_create_compile_task(MACHINE_ID,COMPILE_ID,ROCOTO_COMPILE_MAXTRIES,MAK
     """Generate and append compile task into Rocoto XML file
 
     Args:
-        MACHINE_ID (str): Machine ID i.e., Hera, Gaea, Jet, etc.
+        MACHINE_ID (str): Machine ID i.e., Hera, GaeaC6, Jet, etc.
         COMPILE_ID (str): Compile identifier e.g., s2swa_intel
         ROCOTO_COMPILE_MAXTRIES (str): Max attempts for compile
         MAKE_OPT (str): Make build options
@@ -65,17 +65,17 @@ def rocoto_create_compile_task(MACHINE_ID,COMPILE_ID,ROCOTO_COMPILE_MAXTRIES,MAK
     if ( MACHINE_ID == 'orion'): BUILD_WALLTIME="01:00:00"
     if ( MACHINE_ID == 'hercules'): BUILD_WALLTIME="01:00:00"
     if ( MACHINE_ID == 's4' ):   BUILD_WALLTIME="01:00:00"
-    if ( MACHINE_ID == 'gaea' ): BUILD_WALLTIME="01:00:00"
+    if ( MACHINE_ID == 'gaeac6' ): BUILD_WALLTIME="01:00:00"
     compile_task = f"""  <task name="compile_{COMPILE_ID}" maxtries="{ROCOTO_COMPILE_MAXTRIES}">
     <command>&PATHRT;/run_compile.sh &PATHRT; &RUNDIR_ROOT; "{MAKE_OPT}" {COMPILE_ID} 2>&amp;1 | tee &LOG;/compile_{COMPILE_ID}.log</\
 command>
     <jobname>compile_{COMPILE_ID}</jobname>
     <account>{ACCNR}</account>
     <queue>{COMPILE_QUEUE}</queue>
 """
-    if ( MACHINE_ID == 'gaea' ):
+    if ( MACHINE_ID == 'gaeac6' ):
         compile_task+=f"""    <native>--clusters=es</native>
-    <partition>eslogin_c5</partition>
+    <partition>eslogin_c6</partition>
 """
         PARTITION= ""
     if ( PARTITION != "" and MACHINE_ID != "hera" ):
@@ -230,7 +230,7 @@ def make_loghead(ACCNR,MACHINE_ID,RUNDIR_ROOT,RTPWD,REGRESSIONTEST_LOG):
 
     Args:
         ACCNR (str): Account to run the job with
-        MACHINE_ID (str): Machine ID i.e. Hera, Gaea, Jet, etc.
+        MACHINE_ID (str): Machine ID i.e. Hera, GaeaC6, Jet, etc.
         RUNDIR_ROOT (str): Test run directory
         RTPWD (str): Baseline directory
         REGRESSIONTEST_LOG (str): Regression Test log filename