From 0853eec4adfcbac05a4bec43f334234d17372906 Mon Sep 17 00:00:00 2001
From: Edward Hartnett <38856240+edwardhartnett@users.noreply.github.com>
Date: Thu, 10 Oct 2024 12:20:21 -0600
Subject: [PATCH 1/2] docs for chgres_cold2fv3.py (#519)

---
 docs/requirements.txt  |  3 +--
 ush/chgres_cold2fv3.py | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 2f34e05ab..817841744 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -2,7 +2,6 @@ sphinxcontrib-bibtex
 sphinx_rtd_theme
 docutils==0.16
 numpy
-xarray
-matplotlib
 netCDF4
+xarray
 matplotlib
diff --git a/ush/chgres_cold2fv3.py b/ush/chgres_cold2fv3.py
index b8de4011f..2dd7e10d1 100755
--- a/ush/chgres_cold2fv3.py
+++ b/ush/chgres_cold2fv3.py
@@ -1,3 +1,13 @@
+"""The purpose of this code is to convert a cold start file from
+chgres_cube into a FV3 warm start (restart) file, enabling data
+blending operators that require a warm start format. The code performs
+essential transformations, including wind rotation and vertical
+remapping of atmospheric scalars and winds, ensuring the cold start
+data aligns with the FV3 model's restart format. Reason: The global 6
+h background from chgres_cube is a cold start and must be converted to
+a warm start file to be able to blend with the 1 h EnKF restarts.
+
+"""
 import numpy as np
 from netCDF4 import Dataset
 import remap_dwinds
@@ -6,6 +16,29 @@
 import sys
 
 def nan_check(arr, name, check_id):
+    """NAN check function.
+
+    This function checks a given array for NaN (Not a Number) values,
+    counts the total number of NaNs, and prints their indices if any
+    are found. It helps identify problematic data in the array that
+    may disrupt further processing.
+
+    After all nan_checks are done, if there is at least one nan then
+    the code fails. I put a note right after the vertical remapping of
+    the wind that says "Perform a NaN check - sometimes will get NaNs
+    at this point". I don't think it should fail. I think it was more
+    of an issue in development and I kept the check there just to be
+    safe.
+
+    Parameters:
+    arr: numpy array to be checked for NaN values.
+    name: string used to label the array in the output for identification.
+    check_id: integer or string identifier to differentiate between multiple checks in the output.
+
+    Returns:
+    nan_count: integer representing the total number of NaN values found in the array.
+
+    """
     nan_count = 0
     nan_count = np.sum(np.isnan(arr))
     print(f"coldstartwinds({check_id}) nan_count({name}): {nan_count}")

From 50d55f65116e1ea46bd86357d715f9230a1cc411 Mon Sep 17 00:00:00 2001
From: Edward Hartnett <38856240+edwardhartnett@users.noreply.github.com>
Date: Thu, 10 Oct 2024 13:06:06 -0600
Subject: [PATCH 2/2] documentation for blending_fv3.py (#517)

* added docs to blending_fv3.py
* added requirements
---------
---
 docs/requirements.txt |  1 +
 ush/blending_fv3.py   | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 817841744..c0691fdcb 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -3,5 +3,6 @@ sphinx_rtd_theme
 docutils==0.16
 numpy
 netCDF4
+raymond
 xarray
 matplotlib
diff --git a/ush/blending_fv3.py b/ush/blending_fv3.py
index 374d6ea0f..41d9e56cf 100755
--- a/ush/blending_fv3.py
+++ b/ush/blending_fv3.py
@@ -1,9 +1,42 @@
+"""This script performs blending between regional and global weather
+forecast model restarts using the Fortran module raymond. The Raymond
+filter is a sixth-order tangent low-pass implicit filter and can be
+controlled via the cutoff length scale (Lx).
+
+"""
 import numpy as np
 from netCDF4 import Dataset
 import raymond
 import sys
 
 def check_file_nans(test_nc, vars_fg, vars_bg, name):
+    """Check for NaN values in specified variables of a netCDF file.
+
+    This function iterates over a list of variables and checks for NaN values in the provided
+    netCDF file. It prints the count of NaNs found for each variable and indicates whether
+    any NaNs were detected.
+
+    Again, if there are any NaNs found, I wanted to catch that here
+    instead of later when the model is running. I don't think there is
+    any reason to expect NaNs.
+
+    Parameters:
+    test_nc: Dataset
+    The test netCDF file containing the variables to be checked for NaN values.
+    vars_fg: list of str
+    A list of variable names from the regional model (foreground) to check.
+    vars_bg: list of str
+    A corresponding list of variable names from the global model (background) to check.
+    name: str
+    A string representing the context (e.g., 'glb' for global or 'reg' for regional)
+    to identify the source of the variables being checked.
+
+    Returns:
+    bool
+    Returns True if any NaN values are found in the specified variables;
+    otherwise, returns False.
+
+    """
     nans = False
     for (var_fg, var_bg) in zip(vars_fg, vars_bg):
         i = vars_fg.index(var_fg)
@@ -20,6 +53,11 @@ def check_file_nans(test_nc, vars_fg, vars_bg, name):
         return nans
 
 def err_check(err):
+    """
+    Check for error.
+
+    err: Error code.
+    """
     if err > 0:
         print(f"An error ocurred in {sys.argv[0]}. Blending failed!!!")
         print(f"err={err}")