5.2. Baroclinic Instability Case

The UFS WM baroclinic wave case adapts the test outlined in Jablonowski and Williamson [JW06] (2006). This test is designed to evaluate the accuracy of various atmospheric models in simulating a baroclinic wave, which commonly forms in the Northern Hemisphere and influences weather patterns. This test aims to assess how well “dry dynamical cores,” the foundational components of weather and climate models that handle air movement and temperature changes, perform in idealized conditions.

The simulation sets the model’s atmosphere to an initial steady state, designed to be a simple, realistic representation of atmospheric conditions using the adiabatic (no heat exchange) and inviscid (no friction) primitive equations. The test first checks whether each model can maintain this steady, zonal (west-to-east) state without developing any unintended changes. After verifying this, the next step is to introduce a small disturbance, or perturbation, which triggers the growth of a baroclinic wave. The wave then evolves over several simulated days, allowing the researchers to observe how accurately different models handle the wave’s development and movement.

This test provides a standard way to assess how different atmospheric models handle the development of baroclinic waves. The results help identify which models are more accurate and can serve as benchmarks for model improvement, ultimately contributing to better simulations of atmospheric behavior in weather and climate predictions.

In the UFS WM, the idealized baroclinic wave test case is an atmosphere-only, dycore-only forecast run at C192 resolution with 127 vertical levels. It uses default values from the WM’s export_fv3 function, along with default values for a tiled grid namelist (from export_tiled). These initial values are set based on values from default_vars.sh.

The test is set to run a dynamics-only 24-hour forecast from 2019-12-03 at 0z. However, it is recommended that users modify the case to run it as a 5-10 day forecast by setting the forecast length (FHMAX) to 120-240 hours in the test file (see Section 5.2.2.3 for instructions). Users will also need to update OUTPUT_FH accordingly. This ensures that users will be able to see the disturbance (wave propagation) develop, starting about 120-150 hours into the forecast.

5.2.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.2.2. Running the Baroclinic Wave Case

This section explains how to run the baroclinic wave case described above using the ufs_test.sh script.

5.2.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.2.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.2.2.3. Test Configuration

It is recommended that users adjust certain values in the baroclinic wave case. Currently, the forecast length (FHMAX) is set to 24 hours to maintain the regression testing baselines with reduced resource consumption. However, it is recommended that users run the case for 5-10 days (120-240 hours) to see the disturbance (wave propagation) develop about 120-150 hours into the forecast. To modify the case, open ${UFS_WM}/tests-dev/test_cases/tests/baroclinic_wave using vi/vim or a code editor. Then, add FHMAX and update OUTPUT_FH to extend by increments of 6 to the new FHMAX.

export FHMAX=120      # (or 240)
export OUTPUT_FH='0 6 12 18 24 30 36 42 48 54 60 66 72 78 84 90 96 102 108 114 120'

In general, it is preferable to make FHMAX a multiple of 24.

5.2.2.4. Baseline Configuration

Users may need to modify the baseline configuration file (${UFS_WM}/tests-dev/baseline_setup.yaml), which contains details on the location of staged input data, user-specific output directories, and batch job scheduling. The following variables are of particular importance:

  • dprefix: Set this value to an existing directory where the user has write permissions.

  • STMP: Directory for baseline test output (typically ${dprefix}/stmp4)

  • PTMP: Directory for runtime files (typically ${dprefix}/stmp2)

5.2.2.5. 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.2.2.5.1. Example:

Users with access to the epic account can run the baroclinic_wave 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 "baroclinic_wave intel"

5.2.2.5.2. Running Multiple Cases

To run multiple cases at once, modify ufs_test.yaml to contain only a subset of tests (e.g., 2020_CAPE, baroclinic_wave, tropical_cyclone) and use the -l argument:

./ufs_test.sh -a epic -s -c -k -r -l ufs_test.yaml

Alternatively, users may copy the sections for 2020_CAPE/ baroclinic_wave/ tropical_cyclone/ aquaplanet/ tests into a new YAML file (e.g., my_test_cases.yaml) to call via ufs_test.sh:

./ufs_test.sh -a epic -s -c -k -r -l my_test_cases.yaml

5.2.2.6. 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 baroclinic_wave case, run:

tail -f ${UFS_WM}/tests-dev/run_dir/baroclinic_wave_intel/err
tail -f ${UFS_WM}/tests-dev/run_dir/baroclinic_wave_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