Added docstring

Author: corink21

jobs/tools/camchem_ic_lbc_reggrid.py

@@ -4,22 +4,44 @@
 from os.path import join
 from netCDF4 import Dataset
 from .nc_operations import VariableCreator, VariableCopier, DimensionCopier
-from datetime import datetime
 from .. import tools
 
-#######################################################################
-## Script for roducing IC and LBC on regular grid from CAM-Chem output.
-##
-## Author: Corina Keller (Empa).
-#######################################################################
-
 
 def process_ic(file_path_in, file_path_out, ic_datetime, aero_dict, prefix):
     """
-    Copy chem and aerosol fields for specified dates (no unit transformation).
-    Splitting of aerosols into modes.
+    Generate initial condition (IC) NetCDF files from CAM-Chem output.
+
+    This function copies chemical and aerosol fields for a specified datetime 
+    from an input CAM-Chem NetCDF file. Aerosol fields can be split into 
+    different modes. 
+    No unit transformation is performed.
+
+    Parameters
+    ----------
+    file_path_in : str
+        Path to the input directory containing CAM-Chem NetCDF files.
+    file_path_out : str
+        Path to the output directory where IC files will be saved.
+    ic_datetime : datetime.datetime
+        Datetime for the IC to process.
+    aero_dict : dict
+        Dictionary specifying how aerosol variables should be split into modes 
+        and their corresponding fractions. 
+        Format: `{aerosol_var_name: {mode_name: split_fraction, ...}, ...}`.
+    prefix : str
+        Filename prefix for input and output NetCDF files.
+
+    Returns
+    -------
+    None
+
+    Notes
+    -----
+    - Input files are expected to follow the naming convention: `{prefix}%Y%m%d%H.nc`.
+    - Output files are saved as `{prefix}%Y%m%d%H_ic.nc`.
+    - Variables not present in `aero_dict` are copied directly.
+    - Aerosol variables are split according to the fractions defined in `aero_dict`.
     """
-    #ic_datetime = datetime.strptime(ic_date, '%Y-%m-%d %H:%M:%S')
 
     in_template = prefix + '%Y%m%d%H.nc'
     outname_template = prefix + '%Y%m%d%H_ic.nc'
@@ -81,17 +103,58 @@ def process_ic(file_path_in, file_path_out, ic_datetime, aero_dict, prefix):
 
 def process_lbc(file_path_in, file_path_out, start_time, end_time, inc, prefix,
                 suffix, nameformat, var_mw_dict, aero_dict):
-    """ 
-    Unit transformation [mol/mol] --> [kg/kg] for chem fields.
-    Splitting, renaming and unit transformation [kg/kg] --> [ug/kg] for aerosols.
     """
-    # Files in the input folder
-    #files = [f for f in os.listdir(file_path) if f.startswith('camchem_') and f.endswith('.nc')]
-    #for file in files:
+    Generate lateral boundary condition (LBC) NetCDF files from CAM-Chem output.
+
+    This function processes CAM-Chem NetCDF files and produces LBC files with 
+    appropriate unit transformations. 
+    Chemical fields are converted from [mol/mol] to [kg/kg], while aerosol fields 
+    are split into modes and converted from [kg/kg] to [μg/kg]. 
+
+    Parameters
+    ----------
+    file_path_in : str
+        Path to the input directory containing CAM-Chem NetCDF files.
+    file_path_out : str
+        Path to the output directory where LBC files will be saved.
+    start_time : datetime.datetime
+        Start datetime for the LBC processing range.
+    end_time : datetime.datetime
+        End datetime for the LBC processing range.
+    inc : int
+        Time increment in hours between consecutive files to process.
+    prefix : str
+        Filename prefix used for both input and output files.
+    suffix : str
+        Filename suffix used for both input and output files (e.g., '.nc').
+    nameformat : str
+        Datetime format string used in the filenames (e.g., '%Y%m%d%H').
+    var_mw_dict : dict
+        Dictionary mapping chemical variable names to their molecular weights 
+        for unit conversion. Format: `{var_name: molecular_weight, ...}`.
+    aero_dict : dict
+        Dictionary specifying how aerosol variables should be split into modes 
+        and their corresponding fractions. 
+        Format: `{aerosol_var_name: {mode_name: split_fraction, ...}, ...}`.
+
+    Returns
+    -------
+    None
+
+    Notes
+    -----
+    - Input files are iterated over using specified increments between `start_time` 
+      and `end_time`.
+    - Chemical fields are converted from [mol/mol] to [kg/kg] using the molecular 
+      weight of air (28.96 g/mol) and the variable-specific molecular weight.
+    - Aerosol fields are split into modes and converted from [kg/kg] to [μg/kg].
+    - Essential variables like coordinates and pressure are copied directly
+    - Output files are saved with `_lbc` appended to the original filename.
+    """
+
     for time in tools.iter_hours(start_time, end_time, inc):
 
         # -- Extract datetime information from the filename
-        #datetime_str = file.split('_')[1].split('.')[0]
         in_file = os.path.join(file_path_in,
                                time.strftime(prefix + nameformat + suffix))
         with Dataset(in_file, 'r') as ds:

jobs/tools/camchem_interpolation.py

@@ -19,8 +19,27 @@
 
 
 def time_intpl(file_path, prefix):
-    """ Interpolation of chemistry fields with respect to time variable.
+    
     """
+    Interpolate chemistry fields with respect to time between consecutive NetCDF files.
+
+    This function generates new NetCDF files at intermediate times between existing
+    CAM-Chem output files. Takes the arithmetic mean of chemical and surface pressure 
+    fields and creates interpolated 'time' and 'datesec' variables.
+
+    Parameters
+    ----------
+    file_path : str
+        Path to the directory containing the input NetCDF files.
+    prefix : str
+        Filename prefix for identifying the input NetCDF files to interpolate.
+
+    Returns
+    -------
+    None
+
+    """
+        
     files = sorted([f for f in os.listdir(file_path) if f.startswith(prefix)])
 
     for i in range(len(files) - 1):
@@ -160,15 +179,25 @@ def date_from_days_since_ref(days_since_ref, ref_date):
 
 def extract_timeslice(in_file, out_file_template, spec_intpl, ref_date):
     """
-    - Extract a time slice from the input NetCDF file.
-    - Adjust longitude from [0, 360) to (-180, 180].
-
-    Parameters:
-    - in_file (str): Path to the input NetCDF file containing data for each time step.
-    - out_file_template (str): Template for the output NetCDF file name with strftime placeholder.
-    - spec_intpl (list): List with species to be copied from in_file.
-
-    Returns:
+    Extract a single time slice from a NetCDF file and adjust longitudes.
+
+    Copies selected species and metadata from an input NetCDF file into a new
+    NetCDF file for each time step. 
+    Longitudes are adjusted from [0, 360) to [-180, 180).
+
+    Parameters
+    ----------
+    in_file : str
+        Path to the input NetCDF file.
+    out_file_template : str
+        Template string for the output filename.
+    spec_intpl : list of str
+        List of chemical species to extract from the input file.
+    ref_date : str
+        Reference date (YYYY-MM-DD HH:MM:SS) used to convert time variables.
+
+    Returns
+    -------
     None
     """
 
@@ -325,6 +354,26 @@ def extract_timeslice(in_file, out_file_template, spec_intpl, ref_date):
 
 
 def log_intpl_timeslice(pres_m, pres, var_data):
+    """
+    Perform vertical interpolation of chemical data using log-pressure weighting.
+
+    For each chemistry level, the two nearest meteorological levels are identified
+    and a logarithmic interpolation is applied.
+
+    Parameters
+    ----------
+    pres_m : ndarray
+        Pressure on meteorological levels (Pa).
+    pres : ndarray
+        Pressure on chemical levels (Pa).
+    var_data : ndarray
+        Chemical field data to interpolate.
+
+    Returns
+    -------
+    ndarray
+        Interpolated chemical field on meteorological levels.
+    """
     pres_m_flipped = np.flip(pres_m, axis=0)
     pres_flipped = np.flip(pres, axis=0)
     var_data_flipped = np.flip(var_data, axis=0)
@@ -375,8 +424,24 @@ def log_intpl_timeslice(pres_m, pres, var_data):
 
 
 def hybrid_pressure_interpolation(in_ds, out_ds, var_name, time_indices):
-    """Perform vertical interpolation of 'var_name'. 
-    The interpolation is linear with the log pressure.
+    """
+    Interpolate chemical variable vertically using log-pressure interpolation.
+
+    Parameters
+    ----------
+    in_ds : netCDF4.Dataset
+        Input dataset containing the chemical variable.
+    out_ds : netCDF4.Dataset
+        Output dataset with meteorological levels.
+    var_name : str
+        Name of the chemical variable to interpolate.
+    time_indices : list of int
+        Time indices to process in the datasets.
+
+    Returns
+    -------
+    ndarray
+        Array of vertically interpolated variable on meteorological levels.
     """
     # Pressure on vertical levels of meteo data
     pres_m = out_ds['pres_m'][:]
@@ -398,19 +463,33 @@ def hybrid_pressure_interpolation(in_ds, out_ds, var_name, time_indices):
 
 def vert_intpl(chem_filename, meteo_filename, out_filename, spec, start_chunk,
                end_chunk, ref_date):
-    """Perform vertical interpolation of atmospheric chemical fields using meteorological data.
-    
-    Parameters:
-    - chem_filename (str): Path to the netCDF file containing atmospheric chemical data.
-    - meteo_filename (str): Path to the netCDF file containing meteorological data.
-    - out_filename (str): Path to the output netCDF file for interpolated data.
-    - species (list): List of chemical species names to be interpolated.
-    - start_chunk (datetime object): Start of simulation time.
-    - end_chunk (datetime object): End of simulation time.
-
-    Returns:
+    """
+    Perform vertical interpolation of chemical fields using meteorological data.
+
+    This function interpolates chemical species from their CAM-Chem vertical levels
+    onto the hybrid sigma-pressure levels of the meteorological dataset.
+
+    Parameters
+    ----------
+    chem_filename : str
+        Path to the NetCDF file containing chemical data.
+    meteo_filename : str
+        Path to the NetCDF file containing meteorological data.
+    out_filename : str
+        Path for the output NetCDF file with interpolated results.
+    spec : list of str
+        List of chemical species to interpolate.
+    start_chunk : datetime.datetime
+        Start of the simulation time window to process.
+    end_chunk : datetime.datetime
+        End of the simulation time window to process.
+    ref_date : str
+        Reference date (YYYY-MM-DD HH:MM:SS) used to convert time variables.
+
+    Returns
+    -------
     None
-
+    
     """
 
     with Dataset(chem_filename, 'r') as c_ds, Dataset(meteo_filename,