5.1. July 2020 CAPE Case

The July 2020 CAPE case is an atmosphere-only forecast run at C48 resolution with 127 vertical levels. It is set to run a 24-hour forecast from 2020-07-23 at 0z using the FV3_GFS_v16 physics suite and default values from the WM’s default_vars.sh export_fv3_v16 function.

The original July 2020 CAPE case illustrated a shortcoming of the Global Forecast System (GFS) v16 — low Convective Available Potential Energy (CAPE) predictions during summertime (Sun et al. [SHB+24]). Sun et al. [SHB+24] (2024) used this case study to investigate the low CAPE bias in the GFS and determined that “the GFS simulates smaller surface latent heat flux and larger surface sensible heat flux than the observations” due to “slightly drier-than-observed soil moisture” within the offline Global Data Assimilation System (GDAS) initial conditions used in the study. This resulted in less latent heat and moisture being fed back to the lower levels of the atmosphere and ultimately changed the overall vertical profile of the atmosphere, which lowered CAPE values relative to the older GFS v15.2.

The UFS WM and its subcomponents have undergone signficant changes since the original July 2020 CAPE case study was posted and since Sun et al. [SHB+24]’s experiment, so the current GFS v16 CAPE bias may have shifted. However, users may still wish to run this case and then experiment with different (potentially user-generated) initial conditions, a coupled land surface model (LSM), or other factors to explore elements that improve or worsen CAPE bias. Additionally, Sun et al. [SHB+24]’s findings only apply to this case study, so users may wish to expand their research to include other warm-season cases.

5.1.1. Obtaining Data for the July 2020 CAPE Case

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.1.1.1. User-Generated Data

Attention

The following instructions apply only to users with access to HPSS on RDHPCS. In the future, there are plans to expand options for access to raw initial conditions data for other users.

Users who have access to HPSS can generate initial conditions (ICs) for a particular forecast case (date) and resolution by downloading the raw GFS data and converting it to the appropriate resolution using the the UFS_UTILS gdas_init utility. gdas_init pulls the input data required by chgres_cube from HPSS and then runs the chgres_cube utility to create coldstart initial conditions for the desired resolution and number of vertical levels. Users who already have access to raw GFS ICs can use just the chgres_cube utility to perform the conversion on their existing data. Users may wish to refer to the UFS_UTILS User’s Guide for more information.

Note

In order to generate all necessary configuration, data, input, and fix files to run a configuration similar to the July 2020 CAPE case for another date (still C48 resolution), the user first needs to run the base ufs_test.sh script for the default July 2020 CAPE case as described in Section 5.1.2.5.

To generate coldstart ICs via the UFS_UTILS gdas_init/chgres_cube utilities on an RDHPCS with HPSS access (e.g., Ursa), the user can run the following commands:

git clone https://github.com/ufs-community/UFS_UTILS.git
cd UFS_UTILS/fix
./link_fixdirs.sh emc <platform>
cd ..
./build_all.sh
cd util/gdas_init

where <platform> is ursa.

Then, users will need to edit the config file to:

  • Set paths for data extraction and converted files (EXTRACT_DIR and OUTDIR, respectively)

  • Set yy/mm/dd/hh to desired forecast start time +6 hours

  • Set CDUMP to gfs to generate GFS ICs

  • Set LEVS to 128

  • Set EXTRACT_DATA to yes (unless data is already staged in EXTRACT_DIR)

  • Set CRES_HIRES to desired resolution for coldstart files (e.g., C192)

These variables are documented in more detail in the UFS_UTILS gdas_init documentation.

In the machine-specific driver (e.g., driver.ursa.sh), users will need to set PROJECT_CODE to an account that the user can use for submitting batch jobs.

After configuring the utility, users can run the driver script:

./driver.<platform>.sh

These steps will (1) pull raw GFS data from HPSS into EXTRACT_DIR and then (2) convert the raw data to coldstart ICs (placed in OUTDIR/gfs.YYYYMMDD/HH/model_data/atmos/input). The converted coldstart ICs can then be used as input data for certain UFS WM regression tests (RTs) of corresponding model resolution and configuration (e.g., C48 GFS coldstart data in the control_c48.v2.sfc RT).

Note

Note that since 6/4/24, the develop branch of UFS_UTILS generates only version 2 (v2) surface (sfc) files via gdas_init and chgres_cube. Therefore, successful integration of the converted coldstart files has only been achieved using the recently added v2.sfc WM RTs (see e.g., control_c48.v2.sfc and PRs #2005 and #1977). Since the v2 surface files are significantly different from the v1 surface file format, the user may need to re-configure the higher resolution test case to ensure that fix files, physics suite, and other input data used are consistent with v2 surface files.

5.1.2. Running the July 2020 CAPE Case

This section explains how to run the July 2020 CAPE case described above using the ufs_test.sh script.

5.1.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.1.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.1.2.3. Test Configuration

The July 2020 CAPE case can be run as-is without adjusting the configuration. Users may also choose to run a similar configuration for a different date or the same July 2020 CAPE case at a higher resolution.

5.1.2.3.1. Different Date

Users may choose to run a similar UFS WM configuration for different dates with user-generated ICs (see Section 5.1.1.1 for instructions on downloading this data from HPSS). In this case, users will need to copy the gfs*.nc and sfc*.nc files from OUTDIR/gfs.YYYYMMDD/HH/model_data/atmos/input into the INPUT directory of a UFS WM run directory. (The run directory is set in ${UFS_WM}/tests-dev/machine_config/create_xml.py as ${PTMP}/${USER}/FV3_RT/rt_${pid} for HSD cases.) Note that this will only work when the run directory uses ICs of the same resolution.

Additionally, users will need to adjust the model start time in the model_configure file. For example:

start_year:              2019
start_month:             06
start_day:               15
start_hour:              06
start_minute:            0
start_second:            0
nhours_fcst:             24
fhrot:                   0
...

5.1.2.3.2. Different Resolution

If users choose to run the July 2020 CAPE case at higher resolutions, they can generate GFS ICs at C192, C384, or C768 resolutions following the instructions above. However, they will also need to ensure that the experiment configuration files (i.e., ${UFS_WM}/tests-dev/test_cases/tests/2020_CAPE and ${UFS_WM}/tests-dev/test_cases/exp_conf/2020_CAPE), input namelist, physics suites, and fv3_conf/*.IN file are consistent and configured properly for their desired resolution. Configurations at these higher resolutions are untested, and users can expect to do significant troubleshooting to make them work.

When changing resolution, it is recommended that users view the control_c192, control_c384, or control_c768 test files as a starting point. Those test files will provide guidance on variable settings and model_configure/input namelist settings. Additionally, users will need to ensure that the FV3_RUN file (named 2020_CAPE.IN for the 2020_CAPE experiment) points to the correct input data. Users can modify the parm/fv3_conf files associated with the sample control_* tests to enable use of v2 surface data (as in the control_c48.v2.sfc or 2020_CAPE cases). Any new or modified test file, input namelist, or *.IN file should be placed in the appropriate directory in tests-dev/exp_conf so that the files are correctly propagated into the tests-dev directory when invoking the -s argument with ufs_test.sh.

Attention

Although it is possible to adjust the July 2020 CAPE case to run at non-default resolutions, this is unsupported functionality. Users may experiment with the capability but will need to commit to significant troubleshooting/experimentation to run the case at those resolutions.

5.1.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.1.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.1.2.5.1. Examples

A user with access to the epic account can run the 2020_CAPE test case with the intel compiler on an RDHPCS where they have access using the following command:

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

5.1.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.1.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 2020_CAPE_intel case, run:

tail -f ${UFS_WM}/tests-dev/run_dir/2020_CAPE_intel/err
tail -f ${UFS_WM}/tests-dev/run_dir/2020_CAPE_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