From 5ae5382dcaa0768c72b75f45a82558ce63fb12e1 Mon Sep 17 00:00:00 2001
From: Edward Hartnett <38856240+edwardhartnett@users.noreply.github.com>
Date: Wed, 9 Oct 2024 07:42:40 -0600
Subject: [PATCH] Add documentation to ush/HWP_tools.py (#515)

---
 docs/requirements.txt |  7 +++++-
 ush/HWP_tools.py      | 52 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 7be32f526..2f34e05ab 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,8 @@
 sphinxcontrib-bibtex
 sphinx_rtd_theme
-docutils==0.16
\ No newline at end of file
+docutils==0.16
+numpy
+xarray
+matplotlib
+netCDF4
+matplotlib
diff --git a/ush/HWP_tools.py b/ush/HWP_tools.py
index 39aaa4d84..21bedc720 100755
--- a/ush/HWP_tools.py
+++ b/ush/HWP_tools.py
@@ -1,3 +1,8 @@
+"""
+This file provides Hourly Wildfire Potential (HWP) tools.
+
+"""
+
 import numpy as np
 import os
 import datetime as dt
@@ -7,6 +12,14 @@
 import fnmatch
 
 def check_restart_files(hourly_hwpdir, fcst_dates):
+    """Check the restart files.
+
+    Args:
+         hourly_hwpdir: the directory where the RESTART data is copied (nwges/HOURLY_HWP)
+         fcst_dates: Forecast dates
+    Returns:
+         lists of hours with and without available RESTART files
+    """
     hwp_avail_hours = []
     hwp_non_avail_hours = []
 
@@ -25,6 +38,29 @@ def check_restart_files(hourly_hwpdir, fcst_dates):
     return(hwp_avail_hours, hwp_non_avail_hours)
 
 def copy_missing_restart(nwges_dir, hwp_non_avail_hours, hourly_hwpdir):
+    """Check the restart files.
+
+    The script loops through hwp_non_avail_hours (missing files in
+    nwges/HOURLY_HWP) and determines if an alternative RESTART file in
+    nwges/fcst_fv3lam/RESTART is available instead. If so, it is
+    appended to restart_avail_hours.
+
+    Args:
+         nwges_dir: holds the boundary, INPUT, and RESTART files (e.g,
+         described here:
+         [ufs-community/ufs-srweather-app#654](https://github.com/ufs-community/ufs-srweather-app/issues/654))
+         The use of NWGES is a bit of a legacy variable name in
+         production. It is often used to define a directory holding
+         DA-relevant files (such as first guess and analysis files)
+         outside of the main COM output directory.
+         hwp_non_avail_hours: a list of hours without available RESTART files
+         hourly_hwpdir: the directory where the RESTART data is copied (nwges/HOURLY_HWP)
+    Returns:
+         list of::
+         - restart_avail_hours
+         - restart_nonavail_hours_test which is a subset of hwp_non_avail_hours.
+
+    """
     restart_avail_hours = []
     restart_nonavail_hours_test = []
 
@@ -79,6 +115,22 @@ def copy_missing_restart(nwges_dir, hwp_non_avail_hours, hourly_hwpdir):
     return(restart_avail_hours, restart_nonavail_hours_test)
 
 def process_hwp(fcst_dates, hourly_hwpdir, cols, rows, intp_dir, rave_to_intp):
+    """Check the restart files.
+
+    Args:
+         fcst_dates: a list of forecasts (for production/ops/ebb=2, it is {current_day - 25 hours: current_day-1hours}, for ebb=1, it is current_day:current_day+24 hours)
+         hourly_hwpdir: the directory where the RESTART data is copied (nwges/HOURLY_HWP)
+         cols: hard coded dimension for the RRFS_NA_3km and RRFS_CONUS_3km domains:: cols = 2700 if predef_grid == 'RRFS_NA_3km' else 1092
+         rows: hard coded dimension for the RRFS_NA_3km and RRFS_CONUS_3km domains:: rows = 3950 if predef_grid == 'RRFS_NA_3km' else 1820
+         intp_dir: the working directory for smoke processing (${CYCLE_DIR}/process_smoke)
+         rave_to_intp: a string based on the grid name:: rave_to_intp = predef_grid+"intp"
+    Returns:
+         list of::
+         - average (through time) of HWP_AVE in the available RESTART files
+         - hwp_ave_arr converted to an xarray DataArray
+         - the total precipitation vector (totprcp) reshaped to the 2D grid
+         - totprcp_ave_arr converted to an xarray DataArray
+    """
     hwp_ave = [] 
     totprcp = np.zeros((cols*rows))
     var1, var2 = 'rrfs_hwp_ave', 'totprcp_ave'