Merge PR #403 (Generate monthly mass tables in benchmarks)

This merge brings PR #403 (Generate monthly mass tables in 1-yr
benchmarks; Generate mass tables at beginning & end of 1-month
benchmarks, by @yantosca) into the GCPy 1.7.0 development stream.

PR #403 does the following:

1. Adds convenience function datetime64_to_str in gcpy/date_time.py

2. Modifies make_benchmark_mass_tables and create_benchmark_mass_tables
   to accept "ref_hdr_label" and "dev_hdr_label" arguments instead of
   a single "label" argument.  These are used to pass date strings
   for Ref & Dev to be printed in the file header.

3. Generates mass tables at the start and end of each 1-month benchmark
   period.

4. Generates mass tables at the start of each month (as well as the
   ending date) of 1-year benchmarks.

5. Adds a newline character before printing "Ref species database",
   for more readable logfile output.

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Author: yantosca

CHANGELOG.md

@@ -21,6 +21,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Added constant `SPECIES_DATABASE` to `gcpy/benchmark/modules/benchmark_utils.py`
 - Added manual garbage collection in `create_regridders`, `compare_single_level`, and `compare_zonal_mean` functions.
 - Added helpful tips to the `gcpy/benchmark/benchmark.slurm.sh` script
+- Added function `datetime64_to_str` to `gcpy/date_time.py`
+- Added keyword arguments `ref_hdr_label` and `dev_hdr_label` to `make_benchmark_mass_tables`
 
 ### Changed
 - Modified criteria for terminating read of log files in `benchmark_scrape_gcclassic_timers.py` to avoid being spoofed by  output that is attached by Intel VTune
@@ -51,6 +53,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Optimized the algorithm to generate `varlist` in `make_benchmark_conc_plots`.  Also truncated datasets to only contain variables in `varlist`.
 - Updated `make_benchmark_aod_plots` to include column AOD plots for DSTbin1..DSTbin7 species
 - Updated `benchmark/modules/aod_species.py` with metadata for DSTbin1..DSTbin7 species
+- Updated `make_benchmark_mass_tables` and `create_global_mass_table` to allow Ref and Dev to have different dates if so chosen
+- Updated `run_benchmark.py` to generate mass tables at start and end of the simulation
+- Updated `run_1yr_fullchem_benchmark.py` and `run_1yr_tt_benchmark.py` to generate mass tables at the 1st day of each month from Jan 2019 thru Jan 2020
 
 ### Fixed
 - Fixed grid area calculation scripts of `grid_area` in `gcpy/gcpy/cstools.py`
@@ -66,6 +71,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Removed `.load()` statements from xarray Datasets to improve performance
 - Removed `paths:spcdb_dir` YAML tag in benchmark configuration files
 - Removed `st_Ox` from `benchmark_categories.yml`; this species is no longer used in TransportTracers simulations
+- Removed keyword argument `label` from `make_benchmark_mass_tables`
 
 ## [1.6.2] - 2025-06-12
 ### Added

gcpy/benchmark/modules/benchmark_funcs.py

@@ -377,8 +377,9 @@ def create_global_mass_table(
         devstr,
         varlist,
         met_and_masks,
-        label,
         spcdb_files,
+        ref_hdr_label="",
+        dev_hdr_label="",
         trop_only=False,
         outfilename="GlobalMass_TropStrat.txt",
         verbose=False,
@@ -405,13 +406,16 @@ def create_global_mass_table(
         met_and_masks: dict of xarray DataArray
             Dictionary containing the meterological variables and
             masks for the Ref and Dev datasets.
-        label: str
-            Label to go in the header string.  Can be used to
-            pass the month & year.
         spcdb_files : list
             Paths to species_database.yml files in Ref & Dev rundirs
 
     Keyword Args (optional):
+        ref_hdr_label : str
+            Label for Ref, placed after refstr in the file header
+            Default value: ""
+        dev_hdr_label : str
+            Label for Dev, placed after devstr in the file header
+            Default value: ""
         trop_only: bool
             Set this switch to True if you wish to print totals
             only for the troposphere.
@@ -470,11 +474,11 @@ def create_global_mass_table(
     diff_list = []
 
     # Title strings
-    title1 = f"### Global mass (Gg) {label} (Trop + Strat)"
+    title1 = f"### Global mass (Gg) (Trop + Strat)"
     if trop_only:
-        title1 = f"### Global mass (Gg) {label} (Trop only)"
-    title2 = f"### Ref = {refstr}"
-    title3 = f"### Dev = {devstr}"
+        title1 = f"### Global mass (Gg) (Trop only)"
+    title2 = f"### Ref = {refstr} {ref_hdr_label}"
+    title3 = f"### Dev = {devstr} {dev_hdr_label}"
 
     # Write a placeholder to the file that denotes where
     # the list of species with differences will be written
@@ -3533,9 +3537,10 @@ def make_benchmark_mass_tables(
         subdst=None,
         overwrite=False,
         verbose=False,
-        label="at end of simulation",
+        ref_hdr_label="",
+        dev_hdr_label="",
         ref_met_extra=None,
-        dev_met_extra=None
+        dev_met_extra=None,
 ):
     """
     Creates a text file containing global mass totals by species and
@@ -3582,6 +3587,12 @@ def make_benchmark_mass_tables(
         verbose: bool
             Set this flag to True to print extra informational output.
             Default value: False.
+        ref_hdr_label : str
+            Label for Ref, placed after refstr in the file header
+            Default value: ""
+        dev_hdr_label : str
+            Label for Dev, placed after devstr in the file header
+            Default value: ""
         ref_met_extra: str
             Path to ref Met file containing area data for use with restart files
             which do not contain the Area variable.
@@ -3749,15 +3760,19 @@ def make_benchmark_mass_tables(
         devstr,
         varlist,
         met_and_masks,
-        label,
+        spcdb_files,
+        ref_hdr_label=ref_hdr_label,
+        dev_hdr_label=dev_hdr_label,
         outfilename=mass_file,
         verbose=verbose,
-        spcdb_files=spcdb_files,
     )
 
     # ==================================================================
     # Create tropospheric mass table
     # ==================================================================
+
+    # If a file name has not been specified, then use the "filename"
+    # keyword argument.  Otherwise generate a default filename.
     if subdst is not None:
         mass_filename = f"GlobalMass_Trop_{subdst}.txt"
     else:
@@ -3770,11 +3785,12 @@ def make_benchmark_mass_tables(
         devstr,
         varlist,
         met_and_masks,
-        label,
+        spcdb_files,
+        ref_hdr_label=ref_hdr_label,
+        dev_hdr_label=dev_hdr_label,
         outfilename=mass_file,
         trop_only=True,
         verbose=verbose,
-        spcdb_files=spcdb_files,
     )
 
     # -------------------------------------------

gcpy/benchmark/modules/benchmark_utils.py

@@ -743,7 +743,7 @@ def get_species_database_files(config, ref_model, dev_model):
     if not os.path.exists(ref_spcdb_file):
         msg = f"Could not find {ref_spcdb_file}!"
         raise FileNotFoundError(msg)
-    msg = f"Ref species database: {ref_spcdb_file}"
+    msg = f"\nRef species database: {ref_spcdb_file}"
     print(msg)
 
     # Species database in the "Dev" simulation folder

gcpy/benchmark/modules/run_1yr_fullchem_benchmark.py

@@ -61,6 +61,7 @@
 from gcpy.benchmark.modules.ste_flux import make_benchmark_ste_table
 from gcpy.benchmark.modules.oh_metrics import make_benchmark_oh_metrics
 from gcpy.benchmark.modules.budget_ox import global_ox_budget
+from gcpy.date_time import datetime64_to_str
 #TODO: Peel out routines from benchmark_funcs.py into smaller
 # routines in the gcpy/benchmark/modules folder, such as these:
 from gcpy.benchmark.modules.benchmark_funcs import \
@@ -240,9 +241,13 @@ def run_benchmark(config, bmk_year_ref, bmk_year_dev):
     bmk_start_ref = np.datetime64(bmk_year_ref + "-01-01")
     bmk_end_ref = np.datetime64(f"{int(bmk_year_ref) + 1}-01-01")
     all_months_ref = np.arange(
-        bmk_start_ref, bmk_end_ref, step=np.timedelta64(1, "M"), dtype="datetime64[M]"
+        bmk_start_ref,
+        bmk_end_ref,
+        step=np.timedelta64(1, "M"),
+        dtype="datetime64[M]"
     )
     all_months_gchp_ref = all_months_ref
+    mass_table_dates_ref = np.append(all_months_ref, bmk_end_ref)
 
     # Get subset of month datetimes and seconds per month for only benchmark months
     bmk_mons_ref = all_months_ref[bmk_mon_inds]
@@ -270,6 +275,7 @@ def run_benchmark(config, bmk_year_ref, bmk_year_dev):
         bmk_start_dev, bmk_end_dev, step=np.timedelta64(1, "M"), dtype="datetime64[M]"
     )
     all_months_gchp_dev = all_months_dev
+    mass_table_dates_dev = np.append(all_months_dev, bmk_end_dev)
 
     # Get subset of month datetimes and seconds per month for only benchmark months
     bmk_mons_dev = all_months_dev[bmk_mon_inds]
@@ -668,12 +674,22 @@ def gcc_vs_gcc_mass_table(mon):
                 refpath = get_filepath(
                     gcc_vs_gcc_refrstdir,
                     "Restart",
-                    bmk_mons_ref[mon]
+                    mass_table_dates_ref[mon]
                 )
                 devpath = get_filepath(
                     gcc_vs_gcc_devrstdir,
                     "Restart",
-                    bmk_mons_dev[mon]
+                    mass_table_dates_dev[mon]
+                )
+
+                # Date strings
+                date_str_ref = datetime64_to_str(
+                    mass_table_dates_ref[mon],
+                    format_str="%Y%m%dT%H"
+                )
+                date_str_dev = datetime64_to_str(
+                    mass_table_dates_dev[mon],
+                    format_str="%Y%m%dT%H"
                 )
 
                 # Create tables
@@ -684,17 +700,18 @@ def gcc_vs_gcc_mass_table(mon):
                     gcc_vs_gcc_devstr,
                     spcdb_files,
                     dst=gcc_vs_gcc_tablesdir,
-                    subdst=bmk_mon_yr_strs_dev[mon],
-                    label=f"at 01{bmk_mon_yr_strs_dev[mon]}",
                     overwrite=True,
+                    subdst=date_str_dev,
+                    ref_hdr_label=f"at {date_str_ref}",
+                    dev_hdr_label=f"at {date_str_dev}",
                 )
 
             # Create tables in parallel
             # Turn off parallelization if n_jobs==1
             if config["options"]["n_cores"] != 1:
                 results = Parallel(n_jobs=config["options"]["n_cores"])(
                     delayed(gcc_vs_gcc_mass_table)(mon)
-                    for mon in range(bmk_n_months)
+                    for mon in range(len(mass_table_dates_dev))
                 )
             else:
                 results = []
@@ -1320,12 +1337,12 @@ def gchp_vs_gcc_mass_table(mon):
                 refpath = get_filepath(
                     gchp_vs_gcc_refrstdir,
                     "Restart",
-                    bmk_mons_dev[mon]
+                    mass_table_dates_ref[mon]
                 )
                 devpath = get_filepath(
                     gchp_vs_gcc_devrstdir,
                     "Restart",
-                    bmk_mons_dev[mon],
+                    mass_table_dates_dev[mon],
                     is_gchp=True,
                     gchp_res=config["data"]["dev"]["gchp"]["resolution"],
                     gchp_is_pre_14_0=config["data"]["dev"]["gchp"][
@@ -1344,6 +1361,16 @@ def gchp_vs_gcc_mass_table(mon):
                         "is_pre_14.0"]
                 )
 
+                # Date strings
+                date_str_ref = datetime64_to_str(
+                    mass_table_dates_ref[mon],
+                    format_str="%Y%m%dT%H"
+                )
+                date_str_dev = datetime64_to_str(
+                    mass_table_dates_dev[mon],
+                    format_str="%Y%m%dT%H"
+                )
+
                 # Create tables
                 make_benchmark_mass_tables(
                     refpath,
@@ -1352,9 +1379,10 @@ def gchp_vs_gcc_mass_table(mon):
                     gchp_vs_gcc_devstr,
                     spcdb_files,
                     dst=gchp_vs_gcc_tablesdir,
-                    subdst=bmk_mon_yr_strs_dev[mon],
-                    label=f"at 01{bmk_mon_yr_strs_dev[mon]}",
-                    overwrite=True,
+                    overwrite=True,   
+                    subdst=date_str_dev,
+                    ref_hdr_label=f"at {date_str_ref}",
+                    dev_hdr_label=f"at {date_str_dev}",
                     dev_met_extra=devareapath
                 )
 
@@ -1363,11 +1391,11 @@ def gchp_vs_gcc_mass_table(mon):
             if config["options"]["n_cores"] != 1:
                 results = Parallel(n_jobs=config["options"]["n_cores"])(
                     delayed(gchp_vs_gcc_mass_table)(mon) \
-                    for mon in range(bmk_n_months)
+                    for mon in range(len(mass_table_dates_dev))
                 )
             else:
                 results = []
-                for mon in range(bmk_n_months):
+                for mon in range(len(mass_table_dates_dev)):
                     results.append(gchp_vs_gcc_mass_table(mon))
 
         # ==================================================================
@@ -1996,7 +2024,7 @@ def gchp_vs_gchp_mass_table(mon):
                 refpath = get_filepath(
                     gchp_vs_gchp_refrstdir,
                     "Restart",
-                    bmk_mons_ref[mon],
+                    mass_table_dates_ref[mon],
                     is_gchp=True,
                     gchp_res=config["data"]["ref"]["gchp"]["resolution"],
                     gchp_is_pre_14_0=config["data"]["ref"]["gchp"][
@@ -2007,7 +2035,7 @@ def gchp_vs_gchp_mass_table(mon):
                 devpath = get_filepath(
                     gchp_vs_gchp_devrstdir,
                     "Restarts",
-                    bmk_mons_dev[mon],
+                    mass_table_dates_dev[mon],
                     is_gchp=True,
                     gchp_res=config["data"]["dev"]["gchp"]["resolution"],
                     gchp_is_pre_14_0=config["data"]["dev"]["gchp"][
@@ -2035,6 +2063,16 @@ def gchp_vs_gchp_mass_table(mon):
                         "is_pre_14.0"]
                 )
 
+                # Date strings
+                date_str_ref = datetime64_to_str(
+                    mass_table_dates_ref[mon],
+                    format_str="%Y%m%dT%H"
+                )
+                date_str_dev = datetime64_to_str(
+                    mass_table_dates_dev[mon],
+                    format_str="%Y%m%dT%H"
+                )
+
                 # Create tables
                 make_benchmark_mass_tables(
                     refpath,
@@ -2043,9 +2081,10 @@ def gchp_vs_gchp_mass_table(mon):
                     gchp_vs_gchp_devstr,
                     spcdb_files,
                     dst=gchp_vs_gchp_tablesdir,
-                    subdst=bmk_mon_yr_strs_dev[mon],
-                    label=f"at 01{bmk_mon_yr_strs_dev[mon]}",
                     overwrite=True,
+                    subdst=date_str_dev,
+                    ref_hdr_label=f"at {date_str_ref}",
+                    dev_hdr_label=f"at {date_str_dev}",
                     ref_met_extra=refareapath,
                     dev_met_extra=devareapath
                 )
@@ -2055,11 +2094,11 @@ def gchp_vs_gchp_mass_table(mon):
             if config["options"]["n_cores"] != 1:
                 results = Parallel(n_jobs=config["options"]["n_cores"])(
                     delayed(gchp_vs_gchp_mass_table)(mon) \
-                    for mon in range(bmk_n_months)
+                    for mon in range(len(mass_table_dates_dev))
                 )
             else:
                 results = []
-                for mon in range(bmk_n_months):
+                for mon in range(len(mass_table_dates_dev)):
                     results.append(gchp_vs_gchp_mass_table(mon))
 
         # ==================================================================