Merge pull request #44 from zsarnoczay/master

azs - several formatting updates and refactoring & a bugfix in water autopop

.gitignore

@@ -35,4 +35,5 @@ __pycache__
 /.emacs.desktop.lock
 /pelicun/coverage.xml
 .cov2emacs.log
-flycheck*.py
+flycheck*.py
+/notes/

pelicun/__init__.py

@@ -43,8 +43,10 @@
 
 __version__ = '3.3.2'
 
-__copyright__ = ("Copyright (c) 2018 Leland Stanford "
-                 "Junior University and The Regents "
-                 "of the University of California")
+__copyright__ = (
+    "Copyright (c) 2018 Leland Stanford "
+    "Junior University and The Regents "
+    "of the University of California"
+)
 
 __license__ = "BSD 3-Clause License"

pelicun/assessment.py

@@ -90,13 +90,15 @@ def __init__(self, config_options=None):
 
         self.options = base.Options(config_options, self)
 
-        self.unit_conversion_factors = base.parse_units(
-            self.options.units_file)
+        self.unit_conversion_factors = base.parse_units(self.options.units_file)
 
         self.log = self.options.log
 
-        self.log.msg(f'pelicun {pelicun_version} | \n',
-                     prepend_timestamp=False, prepend_blank_space=False)
+        self.log.msg(
+            f'pelicun {pelicun_version} | \n',
+            prepend_timestamp=False,
+            prepend_blank_space=False,
+        )
 
         self.log.print_system_info()
 
@@ -161,15 +163,24 @@ def repair(self):
 
     def get_default_data(self, data_name):
         """
-        Load a default data file and pass it to the user.
+        Loads a default data file by name and returns it. This method
+        is specifically designed to access predefined CSV files from a
+        structured directory path related to the SimCenter fragility
+        library.
 
         Parameters
         ----------
-        data_name: string
-            Name of the csv file to be loaded
+        data_name : str
+            The name of the CSV file to be loaded, without the '.csv'
+            extension. This name is used to construct the full path to
+            the file.
 
+        Returns
+        -------
+        pd.DataFrame
+            The DataFrame containing the data loaded from the
+            specified CSV file.
         """
-
         data_path = f'{base.pelicun_path}/resources/SimCenterDBDL/{data_name}.csv'
 
         return file_io.load_data(
@@ -185,6 +196,11 @@ def get_default_metadata(self, data_name):
         data_name: string
             Name of the json file to be loaded
 
+        Returns
+        -------
+        dict
+            Default metadata
+
         """
 
         data_path = f'{base.pelicun_path}/resources/SimCenterDBDL/{data_name}.json'
@@ -208,7 +224,7 @@ def calc_unit_scale_factor(self, unit):
 
         Returns
         -------
-        scale_factor: float
+        float
             Scale factor that convert values from unit to base unit
 
         Raises
@@ -232,8 +248,9 @@ def calc_unit_scale_factor(self, unit):
             scale_factor = unit_count * self.unit_conversion_factors[unit_name]
 
         except KeyError as exc:
-            raise KeyError(f"Specified unit not recognized: "
-                           f"{unit_count} {unit_name}") from exc
+            raise KeyError(
+                f"Specified unit not recognized: {unit_count} {unit_name}"
+            ) from exc
 
         return scale_factor
 
@@ -248,6 +265,11 @@ def scale_factor(self, unit):
         unit: str
             A unit name.
 
+        Returns
+        -------
+        float
+            Scale factor
+
         Raises
         ------
         ValueError
@@ -256,7 +278,6 @@ def scale_factor(self, unit):
         """
 
         if unit is not None:
-
             if unit in self.unit_conversion_factors:
                 scale_factor = self.unit_conversion_factors[unit]
 

pelicun/auto.py

@@ -52,26 +52,48 @@
 import importlib
 from pathlib import Path
 
-from . import base
+from pelicun import base
 
 
 def auto_populate(
     config, auto_script_path, **kwargs  # pylint: disable=unused-argument
 ):
     """
-    Automatically populates the DL configuration for a Pelicun
-    calculation.
+    Automatically populates the Damage and Loss (DL) configuration for
+    a Pelicun calculation using predefined rules.
+
+    This function modifies the provided configuration dictionary based
+    on an external Python script that defines auto-population
+    rules. It supports using built-in scripts or custom scripts
+    specified by the user.
 
     Parameters
     ----------
-    config: dict
-        Configuration dictionary with a GeneralInformation key that
-        holds another dictionary with attributes of the asset of
-        interest.
-    auto_script_path: string
-        Path pointing to a python script with the auto-population
-        rules.  Built-in scripts can be referenced using the
-        PelicunDefault/XY format where XY is the name of the script.
+    config : dict
+        A configuration dictionary with a 'GeneralInformation' key
+        that holds another dictionary with attributes of the asset of
+        interest. This dictionary is modified in-place with
+        auto-populated values.
+    auto_script_path : str
+        The path pointing to a Python script with the auto-population
+        rules. Built-in scripts can be referenced using the
+        'PelicunDefault/XY' format where 'XY' is the name of the
+        script.
+
+    Returns
+    -------
+    tuple
+        A tuple containing two items:
+        1. Updated configuration dictionary including new 'DL' key
+        with damage and loss information.
+        2. A dictionary of component quantities (CMP) derived from the
+        auto-population process.
+
+    Raises
+    ------
+    ValueError
+        If the configuration dictionary does not contain necessary
+        asset information under 'GeneralInformation'.
     """
 
     # try to get the AIM attributes