7. Air Quality Modeling (Online-CMAQ)
The standard SRW App distribution uses the uncoupled version of the UFS Weather Model (atmosphere-only). However, users have the option to use a coupled version of the SRW App that includes the standard distribution (atmospheric model) plus the Air Quality Model (AQM).
The AQM is a UFS Application that dynamically couples the Community Multiscale Air Quality (CMAQ) model with the UFS Weather Model (WM) through the NUOPC Layer to simulate temporal and spatial variations of atmospheric compositions (e.g., ozone and aerosol compositions). The CMAQ model, treated as a column chemistry model, updates concentrations of chemical species (e.g., ozone and aerosol compositions) at each integration time step. The transport terms (e.g., advection and diffusion) of all chemical species are handled by the UFS WM as tracers.
Although this chapter is the primary documentation resource for running the AQM configuration, users may need to refer to Chapter 4 and Chapter 5 for additional information on building and running the SRW App, respectively.
These instructions should work smoothly on Hera and WCOSS2, but users on other systems may need to make additional adjustments.
7.1. Quick Start Guide (AQM/Online-CMAQ)
7.1.1. Download the Code
develop branch of the authoritative SRW App repository:
git clone -b develop https://github.com/ufs-community/ufs-srweather-app cd ufs-srweather-app
Note that the latest hash of the
develop branch might not be tested with the sample scripts of for AQM. To check out the stable (verified) version for AQM/online-CMAQ, users can check out hash
git checkout ff6f103
This hash will then check out the following hashes (as of 03/08/2023) of the external components, which are specified in
Users may replace the hashes above with different ones if they prefer. For example, users can comment out the hash line and uncomment the branch line with a new
repo_url address to use a different branch for development. In the example below, the
ufs-weather-model repository URL has been changed to check out code from a user’s personal fork rather than from the authoritative UFS repository.
repo_url = https://github.com/chan-hoo/ufs-weather-model branch = feature/for_example #hash = ff6f103
7.1.2. Checkout Externals
Along with the components detailed in Chapter 8, the AQM version of the SRW App pulls in the externals listed in Table 7.1. Users must run the
checkout_externals script to collect (or “check out”) the individual components of the SRW App (AQM version) from their respective GitHub repositories.
7.1.3. Build the SRW App with AQM
On Hera and WCOSS2, users can build the SRW App AQM binaries with the following command:
./devbuild.sh -p=<machine> -a=ATMAQ
-a argument indicates the configuration/version of the application to build.
Building the SRW App with AQM on other machines, including other Level 1 platforms, is not currently guaranteed to work, and users may have to make adjustments to the modulefiles for their system.
7.1.4. Load the
Load the python environment for the workflow:
# On WCOSS2 (do not run on other systems): source ../versions/run.ver.wcoss2 # On all systems (including WCOSS2): module use /path/to/ufs-srweather-app/modulefiles module load wflow_<machine>
wcoss2. The workflow should load on other platforms listed under the
MACHINE variable in Section 11.1, but users may need to adjust other elements of the process when running on those platforms.
If the console outputs a message, the user should run the commands specified in the message. For example, if the output says:
Please do the following to activate conda: > conda activate regional_workflow
then the user should run
conda activate regional_workflow. Otherwise, the user can continue with configuring the workflow.
7.1.5. Configure and Experiment
Users will need to configure their experiment by setting parameters in the
config.yaml file. To start, users can copy a default experiment setting into
cd ush cp config.aqm.community.yaml config.yaml
Users may prefer to copy the
config.aqm.nco.realtime.yaml for a default “nco” mode experiment instead.
Additional sample configuration files can be found in the
online-cmaq branch of Chan-Hoo Jeon’s (NOAA/NCEP/EMC)
ufs-srweather-app repository fork on GitHub.
Users will need to change the
ACCOUNT variables in
config.yaml to match their system. They may also wish to adjust other experiment settings. For more information on each task and variable, see Chapter 11.
Users may also wish to change cron-related parameters in
config.yaml. In the
config.aqm.community.yaml file, which was copied into
config.yaml, cron is used for automatic submission and resubmission of the workflow:
workflow: USE_CRON_TO_RELAUNCH: true CRON_RELAUNCH_INTVL_MNTS: 3
This means that cron will submit the launch script every 3 minutes. Users may choose not to submit using cron or to submit at a different frequency. Note that users should create a crontab by running
crontab -e the first time they use cron.
7.1.6. Generate the Workflow
Generate the workflow:
7.1.7. Run the Workflow
USE_CRON_TO_RELAUNCH is set to true in
config.yaml (see Section 7.1.5), the workflow will run automatically. If it was set to false, users must submit the workflow manually from the experiment directory:
cd <EXPT_BASEDIR>/<EXPT_SUBDIR> ./launch_FV3LAM_wflow.sh
Repeat the launch command regularly until a SUCCESS or FAILURE message appears on the terminal window. See Section 11.3.2 for more on the
Users may check experiment status from the experiment directory with either of the following commands:
# Check the experiment status (best for cron jobs) rocotostat -w FV3LAM_wflow.xml -d FV3LAM_wflow.db -v 10 # Check the experiment status and relaunch the workflow (for manual jobs) ./launch_FV3LAM_wflow.sh; tail -n 40 log.launch_FV3LAM_wflow