[develop] Integrate smoke/dust capability of main_aqm into develop (#…

…1185)

* Integrate the smoke and dust capability of the main-aqm branch into the develop branch of the UFS SRW App.
   * This capability works on Hera, Orion, Hercules, and Gaea-C6.
* A we2e test for smoke/dust is added
* A sample configuration YAML file config.smoke_dust.yaml is added to the ush directory
* Update the hash of the UFS Weather Model with 3a5e52e where the change of the RRFS production branch is included.
* Update the hash of UPP with the release/srw-v3.0.0 branch in the NOAA-EPIC fork of UPP.

---------

Co-authored-by: Chan-hoo Jeon <[email protected]>
Co-authored-by: michael.lueken <[email protected]>

Externals.cfg

@@ -1,9 +1,9 @@
 [ufs_utils]
 protocol = git
-repo_url = https://github.com/ufs-community/UFS_UTILS
+repo_url = https://github.com/NOAA-EPIC/UFS_UTILS
 # Specify either a branch name or a hash but not both.
-#branch = develop
-hash = 57bd832
+#branch = release/srw-v3.0.0
+hash = 1ee0fee
 local_path = sorc/UFS_UTILS
 required = True
 
@@ -12,7 +12,7 @@ protocol = git
 repo_url = https://github.com/ufs-community/ufs-weather-model
 # Specify either a branch name or a hash but not both.
 #branch = develop
-hash = 5324d64
+hash = 3a5e52e
 local_path = sorc/ufs-weather-model
 required = True
 

devbuild.sh

@@ -239,6 +239,9 @@ if [ "${BUILD_CONDA}" = "on" ] ; then
   if ! conda env list | grep -q "^srw_graphics\s" ; then
     mamba env create -n srw_graphics --file graphics_environment.yml
   fi
+  if ! conda env list | grep -q "^srw_sd\s" ; then
+    mamba env create -n srw_sd --file sd_environment.yml
+  fi
   if [ "${APPLICATION}" = "ATMAQ" ]; then
     if ! conda env list | grep -q "^srw_aqm\s" ; then
       mamba env create -n srw_aqm --file aqm_environment.yml

doc/TechDocs/ush/modules.rst

@@ -29,4 +29,9 @@ ush
    set_leadhrs
    set_predef_grid_params
    setup
+   smoke_dust_add_smoke
+   smoke_dust_fire_emiss_tools
+   smoke_dust_generate_fire_emissions
+   smoke_dust_hwp_tools
+   smoke_dust_interp_tools
    update_input_nml

doc/TechDocs/ush/smoke_dust_add_smoke.rst

@@ -0,0 +1,7 @@
+smoke\_dust\_add\_smoke module
+==============================
+
+.. automodule:: smoke_dust_add_smoke
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/TechDocs/ush/smoke_dust_fire_emiss_tools.rst

@@ -0,0 +1,7 @@
+smoke\_dust\_fire\_emiss\_tools module
+======================================
+
+.. automodule:: smoke_dust_fire_emiss_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/TechDocs/ush/smoke_dust_generate_fire_emissions.rst

@@ -0,0 +1,7 @@
+smoke\_dust\_generate\_fire\_emissions module
+=============================================
+
+.. automodule:: smoke_dust_generate_fire_emissions
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/TechDocs/ush/smoke_dust_hwp_tools.rst

@@ -0,0 +1,7 @@
+smoke\_dust\_hwp\_tools module
+==============================
+
+.. automodule:: smoke_dust_hwp_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/TechDocs/ush/smoke_dust_interp_tools.rst

@@ -0,0 +1,7 @@
+smoke\_dust\_interp\_tools module
+=================================
+
+.. automodule:: smoke_dust_interp_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/UsersGuide/CustomizingTheWorkflow/ConfigWorkflow.rst

@@ -236,6 +236,12 @@ These parameters are associated with the fixed (i.e., static) files. On :srw-wik
 ``FIXemis``: (Default: "")
    Path to system directory containing AQM emission data files.
 
+``FIXsmoke``: (Default: "")
+   Path to system directory containing Smoke and Dust data files.
+
+``FIXupp``: (Default: "")
+   Path to system directory containing UPP fix files.
+
 ``FIXcrtm``: (Default: "")
    Path to system directory containing CRTM fixed files. 
 
@@ -2065,6 +2071,31 @@ Non-default parameters for coupled Air Quality Modeling (AQM) tasks are set in t
 ``NEXUS_GFS_SFC_ARCHV_DIR``:  (Default: "/NCEPPROD/hpssprod/runhistory")
    Path to archive directory for gfs surface files on HPSS.
 
+
+Smoke and Dust Configuration Parameters
+=====================================
+
+Non-default parameters for Smoke and Dust tasks are set in the ``smoke_dust_parm:`` section of the ``config.yaml`` file.
+
+``DO_SMOKE_DUST``: (Default: false)
+   Flag for smoke and dust tasks.
+
+``EBB_DCYCLE``: (Default: 1)
+   Options for EBB cycle (Retro: 1, Forecast: 2).
+
+``PERSISTENCE``: (Default: true)
+   Flag for emission persistence method. If false, same day FRP is used.
+
+``COMINsmoke_default``: (Default: "")
+   Path to directory containing smoke and dust data files.
+
+``COMINrave_default``: (Default: "")
+   Path to directory containing RAVE fire data files.
+
+``SMOKE_DUST_FILE_PREFIX``: (Default: SMOKE_RRFS_data)
+   Prefix of Smoke and Dust file name used for ufs_model.
+
+
 .. _fire-parameters:
 
 Community Fire Behavior Model Parameters

environment.yml

@@ -6,3 +6,4 @@ dependencies:
   - pylint=2.17*
   - pytest=7.2*
   - uwtools=2.3*
+  - sphinx=7.4.0*

jobs/JSRW_PREPSTART

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+
+#
+#-----------------------------------------------------------------------
+#
+# This script runs prepstart to update IC files for Smoke/Dust
+#
+#-----------------------------------------------------------------------
+#
+date
+export PS4='+ $SECONDS + '
+#
+#-----------------------------------------------------------------------
+#
+# Source the variable definitions file and the bash utility functions.
+#
+#-----------------------------------------------------------------------
+#
+. ${USHdir}/source_util_funcs.sh
+for sect in user nco platform workflow global smoke_dust_parm ; do
+  source_yaml ${GLOBAL_VAR_DEFNS_FP} ${sect}
+done
+set -xue
+#
+#-----------------------------------------------------------------------
+#
+# Get the full path to the file in which this script/function is located 
+# (scrfunc_fp), the name of that file (scrfunc_fn), and the directory in
+# which the file is located (scrfunc_dir).
+#
+#-----------------------------------------------------------------------
+#
+scrfunc_fp=$( $READLINK -f "${BASH_SOURCE[0]}" )
+scrfunc_fn=$( basename "${scrfunc_fp}" )
+scrfunc_dir=$( dirname "${scrfunc_fp}" )
+#
+#-----------------------------------------------------------------------
+#
+# Print message indicating entry into script.
+#
+#-----------------------------------------------------------------------
+#
+print_info_msg "
+========================================================================
+Entering script:  \"${scrfunc_fn}\"
+In directory:     \"${scrfunc_dir}\"
+
+This is the J-job script for the task that copies or fetches RAVE fire
+emission data files from disk, or HPSS.
+========================================================================"
+#
+#-----------------------------------------------------------------------
+#
+# Define job and jobid by default for rocoto
+#
+#-----------------------------------------------------------------------
+#
+WORKFLOW_MANAGER="${WORKFLOW_MANAGER:-rocoto}"
+if [ "${WORKFLOW_MANAGER}" = "rocoto" ]; then
+  if [ "${SCHED}" = "slurm" ]; then
+    job=${SLURM_JOB_NAME}
+    pid=${SLURM_JOB_ID}
+  elif [ "${SCHED}" = "pbspro" ]; then
+    job=${PBS_JOBNAME}
+    pid=${PBS_JOBID}
+  else
+    job="task"
+    pid=$$
+  fi
+  jobid="${job}.${PDY}${cyc}.${pid}"
+fi
+#
+#-----------------------------------------------------------------------
+#
+# Create a temp working directory (DATA) and cd into it.
+#
+#-----------------------------------------------------------------------
+#
+export DATA="${DATA:-${DATAROOT}/${jobid}}"
+mkdir -p $DATA
+cd $DATA
+#
+#-----------------------------------------------------------------------
+#
+# Define NCO environment variables and set COM type definitions.
+#
+#-----------------------------------------------------------------------
+#
+export NET="${NET:-${NET_default}}"
+export RUN="${RUN:-${RUN_default}}"
+
+[[ "$WORKFLOW_MANAGER" = "rocoto" ]] && export COMROOT=$COMROOT
+if [ "${MACHINE}" = "WCOSS2" ]; then
+  export COMIN="${COMIN:-$(compath.py -o ${NET}/${model_ver})}"
+  export COMOUT="${COMOUT:-$(compath.py -o ${NET}/${model_ver}/${RUN}.${PDY}/${cyc}${SLASH_ENSMEM_SUBDIR})}"
+else
+  export COMIN="${COMIN:-${COMROOT}/${NET}/${model_ver}}"
+  export COMOUT="${COMOUT:-${COMROOT}/${NET}/${model_ver}/${RUN}.${PDY}/${cyc}${SLASH_ENSMEM_SUBDIR}}"
+fi
+
+mkdir -p ${COMOUT}
+
+# Create a teomporary share directory
+export DATA_SHARE="${DATA_SHARE:-${DATAROOT}/DATA_SHARE/${PDY}${cyc}}"
+mkdir -p ${DATA_SHARE}
+
+# Run setpdy to initialize PDYm and PDYp variables
+export cycle="${cycle:-t${cyc}z}"
+setpdy.sh
+. ./PDY
+#
+#-----------------------------------------------------------------------
+#
+# Set sub-cycle and ensemble member names in file/diectory names
+#
+#-----------------------------------------------------------------------
+#
+if [ ${subcyc} -ne 0 ]; then
+  export cycle="t${cyc}${subcyc}z"
+fi
+if [ $(boolify "${DO_ENSEMBLE}") = "TRUE" ] && [ ! -z ${ENSMEM_INDX} ]; then
+  export dot_ensmem=".mem${ENSMEM_INDX}"
+else
+  export dot_ensmem=
+fi
+#
+#-----------------------------------------------------------------------
+#
+# Call the ex-script for this J-job.
+#
+#-----------------------------------------------------------------------
+#
+export pgmout="${DATA}/OUTPUT.$$"
+env
+
+${SCRIPTSdir}/exsrw_prepstart.sh
+export err=$?; err_chk
+
+if [ -e "$pgmout" ]; then
+  cat $pgmout
+fi
+#
+#-----------------------------------------------------------------------
+#
+# Whether or not working directory DATA should be kept.
+#
+#-----------------------------------------------------------------------
+#
+if [ "${KEEPDATA}" = "NO" ]; then
+  rm -rf ${DATA}
+fi
+date
+