1.2.1. Quick Start Guide

This chapter provides a brief summary of how to build and run the SRW Application. The steps will run most smoothly on Level 1 systems. Users should expect to reference other chapters of this User’s Guide, particularly Section 1.2.3: Building the SRW App and Section 1.2.4: Running the SRW App, for additional explanations regarding each step.

1.2.1.1. Install the Prerequisite Software Stack

SRW App users who are not working on a Level 1 platform will need to install the prerequisite software stack via spack-stack or HPC-Stack prior to building the SRW App on a new machine. Users can find installation instructions in the spack-stack documentation or the HPC-Stack documentation. The steps will vary slightly depending on the user’s platform, but detailed instructions for a variety of platforms are available in the documentation. Users may also post questions in the ufs-community Discussions tab.

Once spack-stack or HPC-Stack has been successfully installed, users can move on to building the SRW Application.

Attention

Most SRW App Level 1 systems have shifted to spack-stack from HPC-Stack (with the exception of Derecho). Spack-stack is a Spack-based method for installing UFS prerequisite software libraries. Currently, spack-stack is the software stack validated by the UFS Weather Model (WM) for running regression tests. UFS applications and components are also shifting to spack-stack from HPC-Stack but are at various stages of this transition. Although users can still build and use HPC-Stack, the UFS WM no longer uses HPC-Stack for validation, and support for this option is being deprecated.

1.2.1.2. Building and Running the UFS SRW Application

For a detailed explanation of how to build and run the SRW App on any supported system, see Section 1.2.3: Building the SRW App and Section 1.2.4: Running the SRW App. Figure 1.1 outlines the steps of the build process. The overall procedure for generating an experiment is shown in Figure 1.2, with the scripts to generate and run the workflow shown in red. An overview of the required steps appears below. However, users can expect to access other referenced sections of this User’s Guide for more detail.

Clone the SRW App from GitHub:
git clone -b develop https://github.com/ufs-community/ufs-srweather-app.git
Check out the external repositories:
cd ufs-srweather-app
./manage_externals/checkout_externals
Set up the build environment and build the executables:
./devbuild.sh --platform=<machine_name>
where <machine_name> is replaced with the name of the user’s platform/system. Valid values include: derecho | gaea | hera | hercules | jet | linux | macos | noaacloud | orion | wcoss2

For additional details, see Section 1.2.3.4.1, or view Section 1.2.3.4.2 to try the CMake build approach instead.
Users on a Level 2-4 system must download and stage data (both the fix files and the IC/LBC files) according to the instructions in Section 1.3.2.3. Standard data locations for Level 1 systems appear in Table 1.10.
Load the python environment for the workflow. Users on Level 2-4 systems will need to use one of the existing wflow_<platform> modulefiles (e.g., wflow_macos) and adapt it to their system. Then, run:
source /path/to/ufs-srweather-app/etc/lmod-setup.sh <platform>
module use /path/to/ufs-srweather-app/modulefiles
module load wflow_<platform>
where <platform> refers to a valid machine name (see Section 1.3.1.1). After loading the workflow, users should follow the instructions printed to the console. For example, if the output says:
Please do the following to activate conda:
   > conda activate srw_app
then the user should run conda activate srw_app to activate the workflow environment.
Configure the experiment:

Copy the contents of the sample experiment from config.community.yaml to config.yaml:
cd ush
cp config.community.yaml config.yaml
Users will need to open the config.yaml file and adjust the experiment parameters in it to suit the needs of their experiment (e.g., date, grid, physics suite). At a minimum, users need to modify the MACHINE parameter. In most cases, users will need to specify the ACCOUNT parameter and the location of the experiment data (see Section 1.2.4.1 for Level 1 system default locations).

For example, a user on Gaea might adjust or add the following fields to run the 12-hr “out-of-the-box” case on Gaea using prestaged system data and cron to automate the workflow:
user:
  MACHINE: gaea
  ACCOUNT: hfv3gfs
workflow:
  EXPT_SUBDIR: run_basic_srw
  USE_CRON_TO_RELAUNCH: true
  CRON_RELAUNCH_INTVL_MNTS: 3
task_get_extrn_ics:
  USE_USER_STAGED_EXTRN_FILES: true
  EXTRN_MDL_SOURCE_BASEDIR_ICS: /lustre/f2/dev/role.epic/contrib/UFS_SRW_data/v2p2/input_model_data/FV3GFS/grib2/${yyyymmddhh}
task_get_extrn_lbcs:
  USE_USER_STAGED_EXTRN_FILES: true
  EXTRN_MDL_SOURCE_BASEDIR_LBCS: /lustre/f2/dev/role.epic/contrib/UFS_SRW_data/v2p2/input_model_data/FV3GFS/grib2/${yyyymmddhh}
Users on a different system would update the machine, account, and data paths accordingly. Additional changes may be required based on the system and experiment. More detailed guidance is available in Section 1.2.4.3.2.2. Parameters and valid values are listed in Section 1.3.1.
Generate the experiment workflow.
./generate_FV3LAM_wflow.py
Run the workflow from the experiment directory ($EXPTDIR). By default, the path to this directory is ${EXPT_BASEDIR}/${EXPT_SUBDIR} (see Section 1.3.1.3.2 for more detail). There are several methods for running the workflow, which are discussed in Section 1.2.4.4. Most require the Rocoto Workflow Manager. For example, if the user automated the workflow using cron, run:
cd $EXPTDIR
rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10
The user can resubmit the rocotostat command as needed to check the workflow progress.

If the user has Rocoto but did not automate the workflow using cron, run:
cd $EXPTDIR
./launch_FV3LAM_wflow.sh
To (re)launch the workflow and check the experiment’s progress, run:
./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow
The workflow must be relaunched regularly and repeatedly until the log output includes a Workflow status: SUCCESS message indicating that the experiment has finished.

Optionally, users may configure their own grid or vertical levels instead of using a predefined grid and default set of vertical levels. Users can also plot the output of their experiment(s) or run verification tasks using METplus.