Updated documentationfor some files

Author: sudhanvalalit

src/slmemulator/SLM.py

@@ -133,7 +133,7 @@ def SLM(X, dt, error_threshold=1e-4, max_r=None):
         # Using original X (log-transformed) for comparison
         current_error = np.max(np.abs(X - Xdmd_current_original_vars))
 
-        print(f"Testing r={r_current}: Max absolute error = {current_error:.6f}")
+        # print(f"Testing r={r_current}: Max absolute error = {current_error:.6f}")
 
         if current_error <= error_threshold:
             r_optimal = r_current
@@ -193,7 +193,7 @@ def solve_tov(fileName, tidal=False, parametric=False, mseos=True):
 
     Returns:
         dataArray (array): Data array containing radii, central pressure
-            and mass.
+            and mass (includes tidal deformability k_2 if set to true).
     """
     # Get current paths from the config module
     paths = get_paths()

src/slmemulator/cleanData.py

@@ -7,6 +7,7 @@
 import shutil
 import sys
 from pathlib import Path
+from typing import Optional
 
 # Import default subdirectory names from config for consistent cleanup targets
 from slmemulator.config import (
@@ -16,8 +17,11 @@
     DEFAULT_TEST_DATA_SUBDIR_NAME,
     DEFAULT_TRAIN_DATA_SUBDIR_NAME,
     DEFAULT_PLOTS_SUBDIR_NAME,
+    DEFAULT_VAL_DATA_SUBDIR_NAME,
 )
 
+__all__ = ["clean_directory"]
+
 # List of common cleanup targets (directories and file extensions)
 cleanup_targets = [
     "__pycache__",  # directory for compiled Python bytecode
@@ -31,13 +35,41 @@
 ]
 
 
-def clean_directory(directory: str = None):
+def clean_directory(directory: Optional[str] = None) -> None:
     """
-    Cleans up specified files and directories within a given directory.
+    Recursively cleans a specified directory by removing common project artifacts
+    and specific, code-generated subdirectories.
+
+    The function targets temporary files (by extension) and removes specific
+    directories generated during modeling, plotting, and data processing.
+
+    Parameters
+    ----------
+    directory : str, optional
+        The path to the directory to clean. If :obj:`None`, the function 
+        defaults to cleaning the **current working directory** (:func:`os.getcwd`).
+
+    Returns
+    -------
+    None
+        The function modifies the filesystem but does not return a value.
+
+    Notes
+    -----
+    The cleanup process recursively deletes:
+    
+    1. **Files** matching extensions defined in the global ``cleanup_targets`` 
+       (e.g., ``.pyo``, ``.pyc``).
+    2. **Directories** matching names in the global ``cleanup_targets`` (e.g., 
+       ``__pycache__``).
+    3. **Specific Subdirectories** generated by the code, including those named by 
+       the global default constants: ``DEFAULT_EOS_FILES_SUBDIR_NAME``, 
+       ``DEFAULT_RESULTS_SUBDIR_NAME``, ``DEFAULT_PLOTS_SUBDIR_NAME``, 
+       and subdirectories related to data splitting (train/validation/test).
 
-    Parameters:
-    directory (str): The path to the directory to clean. Defaults to the
-                     current working directory if None.
+    The traversal is performed from bottom-to-top (:attr:`os.walk` with 
+    ``topdown=False``) to allow for safe recursive directory removal 
+    using :func:`shutil.rmtree`.
     """
     if directory is None:
         directory = os.getcwd()
@@ -58,6 +90,7 @@ def clean_directory(directory: str = None):
         DEFAULT_TOV_DATA_SUBDIR_NAME,
         DEFAULT_TEST_DATA_SUBDIR_NAME,
         DEFAULT_TRAIN_DATA_SUBDIR_NAME,
+        DEFAULT_VAL_DATA_SUBDIR_NAME,
         DEFAULT_PLOTS_SUBDIR_NAME,
     ]
 

src/slmemulator/config.py

@@ -2,6 +2,12 @@
 import os
 from pathlib import Path
 import importlib.resources as pkg_resources
+from typing import Dict, List, Optional
+
+__all__ = [
+    "get_paths",
+    "create_necessary_dirs",
+]
 
 # Define the project root based on config.py's location.
 # This assumes config.py is in src/SLM/, so it goes up three levels
@@ -18,6 +24,7 @@
 DEFAULT_TOV_DATA_SUBDIR_NAME = "TOV_data"
 DEFAULT_TEST_DATA_SUBDIR_NAME = "testData" # This is the base for test/QEOS/pSLM
 DEFAULT_TRAIN_DATA_SUBDIR_NAME = "trainData"
+DEFAULT_VAL_DATA_SUBDIR_NAME = "valData"
 DEFAULT_DOCS_SUBDIR_NAME = "docs"
 DEFAULT_TESTS_SUBDIR_NAME = "tests"
 DEFAULT_TUTORIALS_SUBDIR_NAME = "Tutorials"
@@ -33,25 +40,52 @@
 
 
 def get_paths(
-    output_base_dir: Path = None,
+    output_base_dir: Optional[Path] = None,
     eos_name: str = "MSEOS",
     is_parametric_run: bool = True,
     include_slm_paths: bool = True,
-) -> dict:
+) -> Dict[str, Path]:
     """
-    Returns a dictionary of resolved paths for data input/output and other project directories.
-    All 'current' paths are dynamically set based on the provided 'eos_name'.
-
-    Args:
-        output_base_dir (Path, optional): The base directory for all generated outputs.
-        eos_name (str): The name of the Equation of State (e.g., "MSEOS", "QEOS", "APR").
-                        This name is used to create specific subdirectories. Defaults to "MSEOS".
-        is_parametric_run (bool): If True, affects result/plot/test subdirectories (pSLM vs SLM).
-        include_slm_paths (bool): If True, SLM-specific results, plots, and test directories are included.
-
-    Returns:
-        dict: A dictionary containing all relevant path configurations.
+    Generates and returns a dictionary of resolved project paths, dynamically 
+    structuring subdirectories based on the Equation of State (EOS) name and 
+    run configuration.
+
+    The function provides paths for input data, model binaries, general output,
+    and specific subdirectories for results, plots, and test data related to
+    SLM (Sparse Linear Modeling) or pSLM (parametric SLM) runs.
+
+    Parameters
+    ----------
+    output_base_dir : pathlib.Path, optional
+        The root directory where all generated project outputs (results, plots, 
+        test data) will be stored. If ``None``, the current working directory 
+        is implicitly used as the root for relative paths. Defaults to ``None``.
+    eos_name : str, optional
+        The name of the Equation of State (e.g., "MSEOS", "QEOS", "APR"). 
+        This name dictates the specific subdirectory created for the current run 
+        within the results, plots, and test directories. Defaults to "MSEOS".
+    is_parametric_run : bool, optional
+        Flag indicating if the current modeling run is using the parametric SLM 
+        (pSLM) approach. If ``True``, the output paths will typically include 
+        'pSLM'; otherwise, they'll use 'SLM'. Defaults to ``True``.
+    include_slm_paths : bool, optional
+        If ``True``, the dictionary will include the specific directories 
+        (``current_results_dir``, ``current_plots_dir``, ``current_test_dir``) 
+        related to the SLM/pSLM outputs. Defaults to ``True``.
+
+    Returns
+    -------
+    dict[str, pathlib.Path]
+        A dictionary containing all relevant path configurations. Keys include:
+
+        * ``output_base_dir``: The resolved base output path.
+        * ``data_input_dir``: Path to the general input data files.
+        * ``bin_dir``: Path to executable binaries (e.g., TOV solver).
+        * ``current_results_dir``: Directory for SLM/pSLM results for the given EOS.
+        * ``current_plots_dir``: Directory for SLM/pSLM plots for the given EOS.
+        * ``current_test_dir``: Directory for SLM/pSLM test data for the given EOS.
     """
+    
     project_root = PROJECT_ROOT
     output_data_base = output_base_dir or project_root
     src_dir = project_root / DEFAULT_SRC_SUBDIR_NAME
@@ -93,6 +127,7 @@ def get_paths(
         "user_eos_data_dir": output_data_base / DEFAULT_EOS_DATA_SUBDIR_NAME,
         "test_data_dir": output_data_base / DEFAULT_TEST_DATA_SUBDIR_NAME,
         "train_path": output_data_base / DEFAULT_TRAIN_DATA_SUBDIR_NAME,
+        "val_path": output_data_base / DEFAULT_VAL_DATA_SUBDIR_NAME,
         "generated_eos_files_dir": output_data_base / DEFAULT_EOS_FILES_SUBDIR_NAME,
 
         # Current Dynamic EOS/TOV/Generated paths
@@ -156,9 +191,35 @@ def get_paths(
     return final_paths
 
 
-def create_necessary_dirs(paths: dict, additional_dirs: list[Path] = None):
+def create_necessary_dirs(
+    paths: Dict[str, Path], 
+    additional_dirs: Optional[List[Path]] = None
+) -> None:
     """
-    Creates directories for specified output and user-managed data paths if they do not already exist.
+    Creates necessary directories specified in a dictionary and an optional list.
+
+    This function iterates through all Path objects provided in the input dictionary's
+    values and the optional list, ensuring that each directory is created if it
+    does not already exist. It uses pathlib.Path.mkdir with parents=True and
+    exist_ok=True, meaning it will create parent directories if necessary and
+    will not raise an error if the directory already exists.
+
+    Parameters
+    ----------
+    paths : dict[str, pathlib.Path]
+        A dictionary where keys are string identifiers (e.g., 'output_path') 
+        and values are :class:`pathlib.Path` objects representing the directories 
+        to be created.
+    additional_dirs : list[pathlib.Path], optional
+        An optional list of additional :class:`pathlib.Path` objects representing 
+        directories to be created (e.g., user-managed data or model directories). 
+        The default is None.
+
+    Returns
+    -------
+    None
+        The function modifies the filesystem but does not return a value.
+
     """
 
     # Define a list of keys corresponding to directories that should be created.