5.3. Idealized, Regional Tropical Cyclone Case

The idealized, regional tropical cyclone case is derived from the I-HAFS configuration (Wang et al. [WWW+24]) and is designed to support controlled studies of tropical cyclone dynamics and forecast development. It uses the FV3_HAFS_v1_thompson_nonsst physics suite, which is documented in the DTC UFS HAFS v1 Scientific Documentation. The configuration used in this case 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.

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.

5.3.1. Obtaining Data for HSD Cases

Data for the HSD cases is already staged on Tier-1 platforms at the INPUTDATA_ROOT* locations listed in baseline_setup.yaml. However, users on any platform can download the data directly from the HTF data bucket using wget.

wget https://noaa-ufs-htf-pds.s3.amazonaws.com/develop-20260212/HSD_fix_files_and_case_data.tar.gz
tar xvfz HSD_fix_files_and_case_data.tar.gz

5.3.2. 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.

5.3.2.1. Clone the Repository

To start, recursively clone the repository:

git clone --recursive -b develop https://github.com/ufs-community/ufs-weather-model.git
cd ufs-weather-model

After cloning, users may save (or “export”) the path to the UFS WM in an environment variable:

export UFS_WM=$PWD

Although this step is optional, users may find it convenient when navigating between directories. This documentation will use ${UFS_WM} to refer to the path to the ufs-weather-model directory, but users may choose to type out the full path instead.

5.3.2.2. Machine Configuration

The HSD cases are configured to be run on NOAA Tier-1 platforms, and the configuration files for each platform are located at:

${UFS_WM}/tests-dev/machine_config/machine_<PLATFORM>.config

where <PLATFORM> corresponds to the name of the platform. These configuration files load the necessary Python and Rocoto modules for each platform. Users generally do not need to make any changes to these files.

5.3.2.3. 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:

FH_MAX=3

Change to:

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:

WLCLK=00:30

Change to something like:

WLCLK=480

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

5.3.2.4. Running tests

Users can launch tests from the ${UFS_WM}/tests-dev directory with the following command:

cd ${UFS_WM}/tests-dev
./ufs_test.sh -a <ACCOUNT> [-s] [-c] -k -r -n "<CASE_NAME> <COMPILER>"

where:

  • <ACCOUNT>: Account/project number for batch jobs.

  • <CASE_NAME>: Name of the test case (e.g., 2020_CAPE, baroclinic_wave, aquaplanet, or tropical_cyclone).

  • <COMPILER>: Compiler used for the tests (intel or gnu).

Command-line Options:

  • -s: Syncs scripts from ./ufs-wm/tests to ./ufs-wm/tests-dev (only required on the first run)

  • -c: Creates a new baseline (necessary until idealized case baselines are staged in the UFS_WM_RT directory).

  • -k: Keeps runtime directories after test completion

  • l: Runs test cases listed in a YAML file

  • -m: Compares against existing baseline results (baseline must exist)

  • -n: Runs a single test case

  • -r: Uses Rocoto workflow manager

Note

After the initial run of ufs_test.sh with the -s option, users do not need to use -s again unless they subsequently alter files inside of tests-dev/test_cases. If files have changed, the user will need to rerun ufs_test.sh with -s or work from a fresh clone so that everything is properly copied via -s.

5.3.2.4.1. Example:

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

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

5.3.2.5. Checking Results

When the test case finishes running, users should see console output that includes a SUCCESS message. For example:

Performing Cleanup...
REGRESSION TEST RESULT: SUCCESS
+ echo 'ufs_test.sh finished'
ufs_test.sh finished
+ cleanup
++ awk '{print $2}'
+ PID_LOCK=2133541
+ [[ 2133541 == \2\1\3\3\5\4\1 ]]
+ rm -rf /scratch2/NAGAPE/epic/User.Name/ufs-weather-model/tests-dev/lock
+ [[ false == true ]]
+ trap 0
+ exit

Compilation and model run directories can be accessed in the local repository via the run_dir softlink, which points to the actual FV3_RT directory. Each test generates atm*.nc and sfc*.nc files at specified forecast hour intervals.

Users can view progress of compile or model run phases by using the tail -f <file> command or vi/vim on the err or out files in the run_dir/compile* or run_dir/<case_name> directories.

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

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

Note

Once the tests run successfully with the -c option (baseline created), users can compare future test results with the newly created baseline using -m instead of -c.

For further test management, users may save the test directory location in an environment variable:

export UFS_WM_TEST=/path/to/expt_dirs/ufs_test