open-fdd 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

open_fdd/air_handling_unit/faults/fault_condition.py

@@ -3,6 +3,8 @@ import pandas.api.types as pdtypes
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
 import sys
 
+"""see __init__.py for fault classes"""
+
 
 class MissingColumnError(Exception):
     """Custom exception raised when a required column is missing or None."""
@@ -12,6 +14,14 @@ class MissingColumnError(Exception):
         super().__init__(self.message)
 
 
+class InvalidParameterError(Exception):
+    """Custom exception raised when a parameter is not valid (e.g., not a float)."""
+
+    def __init__(self, message):
+        self.message = message
+        super().__init__(self.message)
+
+
 class FaultCondition:
     """Parent class for Fault Conditions. Methods are inherited to all children."""
 
@@ -36,11 +46,7 @@ class FaultCondition:
             raise MissingColumnError(f"Missing required columns: {missing_columns}")
 
     def troubleshoot_cols(self, df):
-        """print troubleshoot columns mapping
-
-        :param df:
-        :return:
-        """
+        """Print troubleshoot columns mapping."""
         print("Troubleshoot mode enabled - not removing helper columns")
         for col in df.columns:
             print(
@@ -54,11 +60,7 @@ class FaultCondition:
             sys.stdout.flush()
 
     def check_analog_pct(self, df, columns):
-        """check analog outputs [data with units of %] are floats only
-
-        :param columns:
-        :return:
-        """
+        """Check analog outputs [data with units of %] are floats only."""
         helper = HelperUtils()
         for col in columns:
             if not pdtypes.is_float_dtype(df[col]):

open_fdd/air_handling_unit/faults/fault_condition_eight.py

@@ -26,6 +26,20 @@ class FaultConditionEight(FaultCondition):
         self.troubleshoot_mode = bool  # default should be False
         self.rolling_window_size = int
 
+        self.equation_string = (
+            "fc8_flag = 1 if |SAT - MAT - ΔT_fan| > √(εSAT² + εMAT²) "
+            "in economizer mode for N consecutive values else 0 \n"
+        )
+        self.description_string = (
+            "Fault Condition 8: Supply air temperature and mixed air temperature should "
+            "be approximately equal in economizer mode \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the mixed air temperature, supply air temperature, "
+            "economizer signal, and cooling signal \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
+
         self.set_attributes(dict_)
 
         # Set required columns specific to this fault condition
@@ -36,9 +50,31 @@ class FaultConditionEight(FaultCondition):
             self.cooling_sig_col,
         ]
 
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
+        )
+
     def get_required_columns(self) -> str:
         """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionEight: {', '.join(self.required_columns)}"
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
+        )
 
     def apply(self, df: pd.DataFrame) -> pd.DataFrame:
         try:
@@ -88,4 +124,4 @@ class FaultConditionEight(FaultCondition):
         except MissingColumnError as e:
             print(f"Error: {e.message}")
             sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_eleven.py

@@ -25,6 +25,20 @@ class FaultConditionEleven(FaultCondition):
         self.troubleshoot_mode = bool  # default False
         self.rolling_window_size = int
 
+        self.equation_string = (
+            "fc11_flag = 1 if OAT < (SATSP - ΔT_fan - εSAT) in "
+            "economizer cooling mode for N consecutive values else 0 \n"
+        )
+        self.description_string = (
+            "Fault Condition 11: Outside air temperature too low for 100% outdoor air cooling "
+            "in economizer cooling mode (Economizer performance fault) \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the supply air temperature setpoint, outside air temperature, "
+            "cooling signal, and economizer signal \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
+
         self.set_attributes(dict_)
 
         # Set required columns specific to this fault condition
@@ -35,9 +49,31 @@ class FaultConditionEleven(FaultCondition):
             self.economizer_sig_col,
         ]
 
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
+        )
+
     def get_required_columns(self) -> str:
         """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionEleven: {', '.join(self.required_columns)}"
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
+        )
 
     def apply(self, df: pd.DataFrame) -> pd.DataFrame:
         try:
@@ -87,4 +123,4 @@ class FaultConditionEleven(FaultCondition):
         except MissingColumnError as e:
             print(f"Error: {e.message}")
             sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_fifteen.py

@@ -28,6 +28,20 @@ class FaultConditionFifteen(FaultCondition):
         self.troubleshoot_mode = bool  # default to False
         self.rolling_window_size = int
 
+        self.equation_string = (
+            "fc15_flag = 1 if ΔT_coil >= √(εcoil_enter² + εcoil_leave²) + ΔT_fan "
+            "in inactive heating coil mode for N consecutive values else 0 \n"
+        )
+        self.description_string = (
+            "Fault Condition 15: Temperature rise across inactive heating coil "
+            "detected, requiring coil leaving temperature sensor \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the heating coil entering temperature, heating coil leaving temperature, "
+            "cooling signal, heating signal, economizer signal, and supply fan VFD speed \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
+
         self.set_attributes(dict_)
 
         # Set required columns specific to this fault condition
@@ -40,9 +54,31 @@ class FaultConditionFifteen(FaultCondition):
             self.supply_vfd_speed_col,
         ]
 
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
+        )
+
     def get_required_columns(self) -> str:
         """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionFifteen: {', '.join(self.required_columns)}"
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
+        )
 
     def apply(self, df: pd.DataFrame) -> pd.DataFrame:
         try:
@@ -113,4 +149,4 @@ class FaultConditionFifteen(FaultCondition):
         except MissingColumnError as e:
             print(f"Error: {e.message}")
             sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_five.py

@@ -26,6 +26,20 @@ class FaultConditionFive(FaultCondition):
         self.troubleshoot_mode = bool  # default to False
         self.rolling_window_size = int
 
+        self.equation_string = (
+            "fc5_flag = 1 if (SAT + εSAT <= MAT - εMAT + ΔT_supply_fan) and "
+            "(heating signal > 0) and (VFDSPD > 0) for N consecutive values else 0 \n"
+        )
+        self.description_string = (
+            "Fault Condition 5: SAT too low; should be higher than MAT in HTG MODE, "
+            "potential broken heating valve or mechanical issue \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the mixed air temperature, supply air temperature, "
+            "heating signal, and supply fan VFD speed \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
+
         self.set_attributes(dict_)
 
         # Set required columns specific to this fault condition
@@ -36,9 +50,31 @@ class FaultConditionFive(FaultCondition):
             self.supply_vfd_speed_col,
         ]
 
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
+        )
+
     def get_required_columns(self) -> str:
         """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionFive: {', '.join(self.required_columns)}"
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
+        )
 
     def apply(self, df: pd.DataFrame) -> pd.DataFrame:
         try:
@@ -84,4 +120,4 @@ class FaultConditionFive(FaultCondition):
         except MissingColumnError as e:
             print(f"Error: {e.message}")
             sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_four.py

@@ -26,6 +26,17 @@ class FaultConditionFour(FaultCondition):
         self.supply_vfd_speed_col = str
         self.troubleshoot_mode = bool  # default to False
 
+        self.equation_string = (
+            "fc4_flag = 1 if excessive mode changes (> δOS_max) occur "
+            "within an hour across heating, econ, econ+mech, mech clg, and min OA modes \n"
+        )
+        self.description_string = "Fault Condition 4: Excessive AHU operating state changes detected (hunting behavior) \n"
+        self.required_column_description = (
+            "Required inputs are the economizer signal, supply fan VFD speed, "
+            "and optionally heating and cooling signals \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
+
         self.set_attributes(dict_)
 
         # Set required columns, making heating and cooling optional
@@ -40,9 +51,30 @@ class FaultConditionFour(FaultCondition):
         if self.cooling_sig_col:
             self.required_columns.append(self.cooling_sig_col)
 
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
+        )
+
     def get_required_columns(self) -> str:
         """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionFour: {', '.join(self.required_columns)}"
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
+        )
 
     def apply(self, df: pd.DataFrame) -> pd.DataFrame:
         try:
@@ -133,4 +165,4 @@ class FaultConditionFour(FaultCondition):
         except MissingColumnError as e:
             print(f"Error: {e.message}")
             sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_fourteen.py

@@ -29,6 +29,20 @@ class FaultConditionFourteen(FaultCondition):
         self.troubleshoot_mode = bool  # default to False
         self.rolling_window_size = int
 
+        self.equation_string = (
+            "fc14_flag = 1 if ΔT_coil >= √(εcoil_enter² + εcoil_leave²) + ΔT_fan "
+            "in inactive cooling coil mode for N consecutive values else 0 \n"
+        )
+        self.description_string = (
+            "Fault Condition 14: Temperature drop across inactive cooling coil "
+            "detected, requiring coil leaving temperature sensor \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the cooling coil entering temperature, cooling coil leaving temperature, "
+            "cooling signal, heating signal, economizer signal, and supply fan VFD speed \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
+
         self.set_attributes(dict_)
 
         # Set required columns specific to this fault condition
@@ -41,9 +55,31 @@ class FaultConditionFourteen(FaultCondition):
             self.supply_vfd_speed_col,
         ]
 
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
+        )
+
     def get_required_columns(self) -> str:
         """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionFourteen: {', '.join(self.required_columns)}"
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
+        )
 
     def apply(self, df: pd.DataFrame) -> pd.DataFrame:
         try:
@@ -104,4 +140,4 @@ class FaultConditionFourteen(FaultCondition):
         except MissingColumnError as e:
             print(f"Error: {e.message}")
             sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_nine.py

@@ -26,6 +26,20 @@ class FaultConditionNine(FaultCondition):
         self.troubleshoot_mode = bool  # default should be False
         self.rolling_window_size = int
 
+        self.equation_string = (
+            "fc9_flag = 1 if OAT > (SATSP - ΔT_fan + εSAT) "
+            "in free cooling mode for N consecutive values else 0 \n"
+        )
+        self.description_string = (
+            "Fault Condition 9: Outside air temperature too high in free cooling mode "
+            "without additional mechanical cooling in economizer mode \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the supply air temperature setpoint, outside air temperature, "
+            "cooling signal, and economizer signal \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
+
         self.set_attributes(dict_)
 
         # Set required columns specific to this fault condition
@@ -36,9 +50,31 @@ class FaultConditionNine(FaultCondition):
             self.economizer_sig_col,
         ]
 
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
+        )
+
     def get_required_columns(self) -> str:
         """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionNine: {', '.join(self.required_columns)}"
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
+        )
 
     def apply(self, df: pd.DataFrame) -> pd.DataFrame:
         try:
@@ -89,4 +125,4 @@ class FaultConditionNine(FaultCondition):
         except MissingColumnError as e:
             print(f"Error: {e.message}")
             sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_one.py

@@ -22,6 +22,13 @@ class FaultConditionOne(FaultCondition):
         self.troubleshoot_mode = bool  # default should be False
         self.rolling_window_size = int
 
+        self.equation_string = "fc1_flag = 1 if (DSP < DPSP - εDSP) and (VFDSPD >= VFDSPD_max - εVFDSPD) for N consecutive values else 0 \n"
+        self.description_string = (
+            "Fault Condition 1: Duct static too low at fan at full speed \n"
+        )
+        self.required_column_description = "Required inputs are the duct static pressure, setpoint, and supply fan VFD speed \n"
+        self.error_string = f"One or more required columns are missing or None \n"
+
         self.set_attributes(dict_)
 
         # Set required columns specific to this fault condition manually
@@ -31,9 +38,31 @@ class FaultConditionOne(FaultCondition):
             self.duct_static_setpoint_col,
         ]
 
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
+        )
+
     def get_required_columns(self) -> str:
-        """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionOne: {', '.join(self.required_columns)}"
+        """called from IPython to print out"""
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
+        )
 
     def apply(self, df: pd.DataFrame) -> pd.DataFrame:
         try:
@@ -69,13 +98,15 @@ class FaultConditionOne(FaultCondition):
             if self.troubleshoot_mode:
                 print("Troubleshoot mode enabled - not removing helper columns")
                 sys.stdout.flush()
-                del df["static_check_"]
-                del df["fan_check_"]
-                del df["combined_check"]
+
+            # Optionally remove temporary columns
+            df.drop(
+                columns=["static_check_", "fan_check_", "combined_check"], inplace=True
+            )
 
             return df
 
         except MissingColumnError as e:
             print(f"Error: {e.message}")
             sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_seven.py

@@ -22,6 +22,20 @@ class FaultConditionSeven(FaultCondition):
         self.troubleshoot_mode = bool  # default to False
         self.rolling_window_size = int
 
+        self.equation_string = (
+            "fc7_flag = 1 if SAT < (SATSP - εSAT) in full heating mode "
+            "and VFD speed > 0 for N consecutive values else 0 \n"
+        )
+        self.description_string = (
+            "Fault Condition 7: Supply air temperature too low in full heating mode "
+            "with heating valve fully open \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the supply air temperature, supply air temperature setpoint, "
+            "heating signal, and supply fan VFD speed \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
+
         self.set_attributes(dict_)
 
         # Set required columns specific to this fault condition
@@ -32,9 +46,31 @@ class FaultConditionSeven(FaultCondition):
             self.supply_vfd_speed_col,
         ]
 
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
+        )
+
     def get_required_columns(self) -> str:
         """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionSeven: {', '.join(self.required_columns)}"
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
+        )
 
     def apply(self, df: pd.DataFrame) -> pd.DataFrame:
         try:
@@ -75,4 +111,4 @@ class FaultConditionSeven(FaultCondition):
         except MissingColumnError as e:
             print(f"Error: {e.message}")
             sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+            raise e

open_fdd/air_handling_unit/faults/fault_condition_six.py

@@ -41,6 +41,21 @@ class FaultConditionSix(FaultCondition):
         self.troubleshoot_mode = bool  # default should be False
         self.rolling_window_size = int
 
+        self.equation_string = (
+            "fc6_flag = 1 if |OA_frac_calc - OA_min| > airflow_err_thres "
+            "in non-economizer modes, considering htg and mech clg OS \n"
+        )
+        self.description_string = (
+            "Fault Condition 6: Issues detected with OA fraction calculation or AHU "
+            "not maintaining design air flow in non-economizer conditions \n"
+        )
+        self.required_column_description = (
+            "Required inputs are the supply fan air volume, mixed air temperature, "
+            "outside air temperature, return air temperature, and VFD speed. "
+            "Optional inputs include economizer signal, heating signal, and cooling signal \n"
+        )
+        self.error_string = f"One or more required columns are missing or None \n"
+
         self.set_attributes(dict_)
 
         # Set required columns specific to this fault condition
@@ -55,9 +70,31 @@ class FaultConditionSix(FaultCondition):
             self.cooling_sig_col,
         ]
 
+        # Check if any of the required columns are None
+        if any(col is None for col in self.required_columns):
+            raise MissingColumnError(
+                f"{self.error_string}"
+                f"{self.equation_string}"
+                f"{self.description_string}"
+                f"{self.required_column_description}"
+                f"{self.required_columns}"
+            )
+
+        # Ensure all required columns are strings
+        self.required_columns = [str(col) for col in self.required_columns]
+
+        self.mapped_columns = (
+            f"Your config dictionary is mapped as: {', '.join(self.required_columns)}"
+        )
+
     def get_required_columns(self) -> str:
         """Returns a string representation of the required columns."""
-        return f"Required columns for FaultConditionSix: {', '.join(self.required_columns)}"
+        return (
+            f"{self.equation_string}"
+            f"{self.description_string}"
+            f"{self.required_column_description}"
+            f"{self.mapped_columns}"
+        )
 
     def apply(self, df: pd.DataFrame) -> pd.DataFrame:
         try:
@@ -141,4 +178,4 @@ class FaultConditionSix(FaultCondition):
         except MissingColumnError as e:
             print(f"Error: {e.message}")
             sys.stdout.flush()
-            raise e  # Re-raise the exception so it can be caught by pytest
+            raise e