open-fdd 0.1.8__tar.gz → 0.1.9__tar.gz

{open_fdd-0.1.8/open_fdd.egg-info → open_fdd-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: open_fdd
-Version: 0.1.8
+Version: 0.1.9
 Summary: A package for fault detection and diagnosis in HVAC systems
 Home-page: https://bbartling.github.io/open-fdd/
 Author: Ben Bartling
@@ -20,6 +20,7 @@ Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: license-file
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -127,7 +128,7 @@ py -3.12 -m black .
 
 【MIT License】
 
-Copyright 2024 Ben Bartling
+Copyright 2025 Ben Bartling
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

{open_fdd-0.1.8 → open_fdd-0.1.9}/README.md

@@ -101,7 +101,7 @@ py -3.12 -m black .
 
 【MIT License】
 
-Copyright 2024 Ben Bartling
+Copyright 2025 Ben Bartling
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

open_fdd-0.1.9/open_fdd/air_handling_unit/faults/__init__.py

@@ -0,0 +1,30 @@
+"""Base module for all fault conditions in the air handling unit (AHU) module."""
+
+from open_fdd.air_handling_unit.faults.fault_condition_eight import FaultConditionEight
+from open_fdd.air_handling_unit.faults.fault_condition_eleven import (
+    FaultConditionEleven,
+)
+from open_fdd.air_handling_unit.faults.fault_condition_fifteen import (
+    FaultConditionFifteen,
+)
+from open_fdd.air_handling_unit.faults.fault_condition_five import FaultConditionFive
+from open_fdd.air_handling_unit.faults.fault_condition_four import FaultConditionFour
+from open_fdd.air_handling_unit.faults.fault_condition_fourteen import (
+    FaultConditionFourteen,
+)
+from open_fdd.air_handling_unit.faults.fault_condition_nine import FaultConditionNine
+from open_fdd.air_handling_unit.faults.fault_condition_one import FaultConditionOne
+from open_fdd.air_handling_unit.faults.fault_condition_seven import FaultConditionSeven
+from open_fdd.air_handling_unit.faults.fault_condition_six import FaultConditionSix
+from open_fdd.air_handling_unit.faults.fault_condition_sixteen import (
+    FaultConditionSixteen,
+)
+from open_fdd.air_handling_unit.faults.fault_condition_ten import FaultConditionTen
+from open_fdd.air_handling_unit.faults.fault_condition_thirteen import (
+    FaultConditionThirteen,
+)
+from open_fdd.air_handling_unit.faults.fault_condition_three import FaultConditionThree
+from open_fdd.air_handling_unit.faults.fault_condition_twelve import (
+    FaultConditionTwelve,
+)
+from open_fdd.air_handling_unit.faults.fault_condition_two import FaultConditionTwo

open_fdd-0.1.9/open_fdd/air_handling_unit/faults/fault_condition_eight.py

@@ -0,0 +1,135 @@
+import numpy as np
+import pandas as pd
+
+from open_fdd.core.base_fault import BaseFaultCondition
+from open_fdd.core.components import FaultInputColumn, InstanceAttribute
+from open_fdd.core.exceptions import InvalidParameterError, MissingColumnError
+from open_fdd.core.mixins import FaultConditionMixin
+
+INPUT_COLS = [
+    FaultInputColumn(
+        name="mat_col",
+        constant_form="MAT_COL",
+        description="Mixed air temperature",
+        unit="°F",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="sat_col",
+        constant_form="SAT_COL",
+        description="Supply air temperature",
+        unit="°F",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="economizer_sig_col",
+        constant_form="ECONOMIZER_SIG_COL",
+        description="Economizer signal",
+        unit="%",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="cooling_sig_col",
+        constant_form="COOLING_SIG_COL",
+        description="Cooling signal",
+        unit="%",
+        required=True,
+        type=float,
+    ),
+]
+
+FAULT_PARAMS = [
+    InstanceAttribute(
+        name="delta_t_supply_fan",
+        constant_form="DELTA_T_SUPPLY_FAN",
+        description="Temperature rise across supply fan",
+        unit="°F",
+        type=float,
+    ),
+    InstanceAttribute(
+        name="mix_degf_err_thres",
+        constant_form="MIX_DEGF_ERR_THRES",
+        description="Mixed air temperature error threshold",
+        unit="°F",
+        type=float,
+    ),
+    InstanceAttribute(
+        name="supply_degf_err_thres",
+        constant_form="SUPPLY_DEGF_ERR_THRES",
+        description="Supply air temperature error threshold",
+        unit="°F",
+        type=float,
+    ),
+    InstanceAttribute(
+        name="ahu_min_oa_dpr",
+        constant_form="AHU_MIN_OA_DPR",
+        description="Minimum outdoor air damper position",
+        unit="fraction",
+        type=float,
+    ),
+]
+
+
+class FaultConditionEight(BaseFaultCondition, FaultConditionMixin):
+    """Class provides the definitions for Fault Condition 8.
+    Supply air temperature and mix air temperature should
+    be approx equal in economizer mode.
+
+    py -3.12 -m pytest open_fdd/tests/ahu/test_ahu_fc8.py -rP -s
+    """
+
+    input_columns = INPUT_COLS
+    fault_params = FAULT_PARAMS
+    equation_string = (
+        "fc8_flag = 1 if |SAT - MAT - ΔT_fan| > √(εSAT² + εMAT²) "
+        "in economizer mode for N consecutive values else 0 \n"
+    )
+    description_string = (
+        "Fault Condition 8: Supply air temperature and mixed air temperature should "
+        "be approximately equal in economizer mode \n"
+    )
+    error_string = "One or more required columns are missing or None \n"
+
+    @FaultConditionMixin._handle_errors
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Apply the fault condition to the DataFrame."""
+        # Apply common checks
+        self._apply_common_checks(df)
+
+        # Get column values using accessor methods
+        mat_col = self.get_input_column("mat_col")
+        sat_col = self.get_input_column("sat_col")
+        economizer_sig_col = self.get_input_column("economizer_sig_col")
+        cooling_sig_col = self.get_input_column("cooling_sig_col")
+
+        # Get parameter values using accessor methods
+        delta_t_supply_fan = self.get_param("delta_t_supply_fan")
+        mix_degf_err_thres = self.get_param("mix_degf_err_thres")
+        supply_degf_err_thres = self.get_param("supply_degf_err_thres")
+        ahu_min_oa_dpr = self.get_param("ahu_min_oa_dpr")
+
+        # Check analog outputs [data with units of %] are floats only
+        columns_to_check = [
+            economizer_sig_col,
+            cooling_sig_col,
+        ]
+        self._apply_analog_checks(df, columns_to_check, check_greater_than_one=True)
+
+        # Perform checks
+        sat_fan_mat = abs(df[sat_col] - delta_t_supply_fan - df[mat_col])
+        sat_mat_sqrted = np.sqrt(supply_degf_err_thres**2 + mix_degf_err_thres**2)
+
+        combined_check = (
+            (sat_fan_mat > sat_mat_sqrted)
+            # Verify AHU is running in OS 3 cooling mode with minimum OA
+            & (df[economizer_sig_col] > ahu_min_oa_dpr)
+            & (df[cooling_sig_col] < 0.1)
+        )
+
+        # Set fault flag
+        self._set_fault_flag(df, combined_check, "fc8_flag")
+
+        return df

open_fdd-0.1.9/open_fdd/air_handling_unit/faults/fault_condition_eleven.py

@@ -0,0 +1,108 @@
+import numpy as np
+import pandas as pd
+
+from open_fdd.core.base_fault import BaseFaultCondition
+from open_fdd.core.components import FaultInputColumn, InstanceAttribute
+from open_fdd.core.exceptions import InvalidParameterError
+from open_fdd.core.mixins import FaultConditionMixin
+
+INPUT_COLS = [
+    FaultInputColumn(
+        name="oat_col",
+        constant_form="OAT_COL",
+        description="Outside air temperature",
+        unit="°F",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="mat_col",
+        constant_form="MAT_COL",
+        description="Mixed air temperature",
+        unit="°F",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="economizer_sig_col",
+        constant_form="ECONOMIZER_SIG_COL",
+        description="Economizer signal",
+        unit="%",
+        required=True,
+        type=float,
+    ),
+]
+
+FAULT_PARAMS = [
+    InstanceAttribute(
+        name="outdoor_degf_err_thres",
+        constant_form="OUTDOOR_DEGF_ERR_THRES",
+        description="Outdoor air temperature error threshold",
+        unit="°F",
+        type=float,
+        range=(0.0, 10.0),
+    ),
+    InstanceAttribute(
+        name="mix_degf_err_thres",
+        constant_form="MIX_DEGF_ERR_THRES",
+        description="Mixed air temperature error threshold",
+        unit="°F",
+        type=float,
+        range=(0.0, 10.0),
+    ),
+]
+
+
+class FaultConditionEleven(BaseFaultCondition, FaultConditionMixin):
+    """Class provides the definitions for Fault Condition 11.
+    Outdoor air temperature and mix air temperature should
+    be approx equal in economizer mode.
+
+    py -3.12 -m pytest open_fdd/tests/ahu/test_ahu_fc11.py -rP -s
+    """
+
+    input_columns = INPUT_COLS
+    fault_params = FAULT_PARAMS
+    equation_string = (
+        "fc11_flag = 1 if |OAT - MAT| > √(εOAT² + εMAT²) in "
+        "economizer mode for N consecutive values else 0 \n"
+    )
+    description_string = (
+        "Fault Condition 11: Outdoor air temperature and mixed air temperature "
+        "should be approximately equal in economizer mode \n"
+    )
+    error_string = "One or more required columns are missing or None \n"
+
+    @FaultConditionMixin._handle_errors
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Apply the fault condition to the DataFrame."""
+        # Apply common checks
+        self._apply_common_checks(df)
+
+        # Get column values using accessor methods
+        mat_col = self.get_input_column("mat_col")
+        oat_col = self.get_input_column("oat_col")
+        economizer_sig_col = self.get_input_column("economizer_sig_col")
+
+        # Get parameter values using accessor methods
+        mix_degf_err_thres = self.get_param("mix_degf_err_thres")
+        outdoor_degf_err_thres = self.get_param("outdoor_degf_err_thres")
+
+        # Check analog outputs [data with units of %] are floats only
+        columns_to_check = [economizer_sig_col]
+        self._apply_analog_checks(df, columns_to_check, check_greater_than_one=True)
+
+        # Perform calculations
+        abs_mat_minus_oat = abs(df[mat_col] - df[oat_col])
+        mat_oat_sqrted = np.sqrt(mix_degf_err_thres**2 + outdoor_degf_err_thres**2)
+
+        combined_check = (
+            (abs_mat_minus_oat > mat_oat_sqrted)
+            # Verify AHU is running in economizer mode
+            & (df[economizer_sig_col] > 0.9)
+        )
+
+        # Set fault flag
+        self._set_fault_flag(df, combined_check, "fc11_flag")
+
+        return df

open_fdd-0.1.9/open_fdd/air_handling_unit/faults/fault_condition_fifteen.py

@@ -0,0 +1,189 @@
+import numpy as np
+import pandas as pd
+
+from open_fdd.core.base_fault import BaseFaultCondition
+from open_fdd.core.components import FaultInputColumn, InstanceAttribute
+from open_fdd.core.exceptions import InvalidParameterError
+from open_fdd.core.mixins import FaultConditionMixin
+
+INPUT_COLS = [
+    FaultInputColumn(
+        name="htg_coil_enter_temp_col",
+        constant_form="HTG_COIL_ENTER_TEMP_COL",
+        description="Heating coil entering air temperature",
+        unit="°F",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="htg_coil_leave_temp_col",
+        constant_form="HTG_COIL_LEAVE_TEMP_COL",
+        description="Heating coil leaving air temperature",
+        unit="°F",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="cooling_sig_col",
+        constant_form="COOLING_SIG_COL",
+        description="Cooling signal",
+        unit="%",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="heating_sig_col",
+        constant_form="HEATING_SIG_COL",
+        description="Heating signal",
+        unit="%",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="economizer_sig_col",
+        constant_form="ECONOMIZER_SIG_COL",
+        description="Economizer signal",
+        unit="%",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="supply_vfd_speed_col",
+        constant_form="SUPPLY_VFD_SPEED_COL",
+        description="Supply fan VFD speed",
+        unit="%",
+        required=True,
+        type=float,
+    ),
+]
+
+FAULT_PARAMS = [
+    InstanceAttribute(
+        name="delta_t_supply_fan",
+        constant_form="DELTA_SUPPLY_FAN",
+        description="Temperature rise across supply fan",
+        unit="°F",
+        type=float,
+        range=(0.0, 5.0),
+    ),
+    InstanceAttribute(
+        name="coil_temp_enter_err_thres",
+        constant_form="COIL_TEMP_ENTER_ERR_THRES",
+        description="Coil entering air temperature error threshold",
+        unit="°F",
+        type=float,
+        range=(0.0, 10.0),
+    ),
+    InstanceAttribute(
+        name="coil_temp_leave_err_thres",
+        constant_form="COIL_TEMP_LEAV_ERR_THRES",
+        description="Coil leaving air temperature error threshold",
+        unit="°F",
+        type=float,
+        range=(0.0, 10.0),
+    ),
+    InstanceAttribute(
+        name="ahu_min_oa_dpr",
+        constant_form="AHU_MIN_OA_DPR",
+        description="Minimum outdoor air damper position",
+        unit="fraction",
+        type=float,
+        range=(0.0, 1.0),
+    ),
+]
+
+
+class FaultConditionFifteen(BaseFaultCondition, FaultConditionMixin):
+    """Class provides the definitions for Fault Condition 15.
+    Temperature rise across inactive heating coil in OS2 (economizer),
+    OS3 (economizer + mechanical cooling), and OS4 (mechanical cooling only) modes.
+    This fault checks if there is an unexpected temperature rise across the heating coil
+    when it should be inactive.
+
+    py -3.12 -m pytest open_fdd/tests/ahu/test_ahu_fc15.py -rP -s
+    """
+
+    input_columns = INPUT_COLS
+    fault_params = FAULT_PARAMS
+    equation_string = (
+        "fc15_flag = 1 if (HTG_LEAVE > HTG_ENTER + √(εENTER² + εLEAVE²) + ΔTfan) "
+        "in OS2 (economizer), OS3 (economizer + mechanical cooling), or "
+        "OS4 (mechanical cooling only) modes for N consecutive values else 0 \n"
+    )
+    description_string = (
+        "Fault Condition 15: Temperature rise across inactive heating coil "
+        "in OS2 (economizer), OS3 (economizer + mechanical cooling), and "
+        "OS4 (mechanical cooling only) modes \n"
+    )
+    error_string = "One or more required columns are missing or None \n"
+
+    @FaultConditionMixin._handle_errors
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Apply the fault condition to the DataFrame."""
+        # Apply common checks
+        self._apply_common_checks(df)
+
+        # Get column values using accessor methods
+        cooling_sig_col = self.get_input_column("cooling_sig_col")
+        heating_sig_col = self.get_input_column("heating_sig_col")
+        economizer_sig_col = self.get_input_column("economizer_sig_col")
+        supply_vfd_speed_col = self.get_input_column("supply_vfd_speed_col")
+        htg_coil_enter_temp_col = self.get_input_column("htg_coil_enter_temp_col")
+        htg_coil_leave_temp_col = self.get_input_column("htg_coil_leave_temp_col")
+
+        # Get parameter values using accessor methods
+        coil_temp_enter_err_thres = self.get_param("coil_temp_enter_err_thres")
+        coil_temp_leave_err_thres = self.get_param("coil_temp_leave_err_thres")
+        delta_t_supply_fan = self.get_param("delta_t_supply_fan")
+        ahu_min_oa_dpr = self.get_param("ahu_min_oa_dpr")
+
+        # Check analog outputs [data with units of %] are floats only
+        columns_to_check = [
+            cooling_sig_col,
+            heating_sig_col,
+            economizer_sig_col,
+            supply_vfd_speed_col,
+        ]
+        self._apply_analog_checks(df, columns_to_check, check_greater_than_one=True)
+
+        # Calculate the threshold for temperature rise, including supply fan heat
+        temp_rise_threshold = (
+            np.sqrt(coil_temp_enter_err_thres**2 + coil_temp_leave_err_thres**2)
+            + delta_t_supply_fan
+        )
+
+        # Check if there's a significant temperature rise across the heating coil
+        temp_rise = df[htg_coil_leave_temp_col] - df[htg_coil_enter_temp_col]
+        significant_temp_rise = temp_rise > temp_rise_threshold
+
+        # Check operating modes:
+        # OS2: Economizer mode (HTG = 0, CLG = 0, ECO > MIN_OA)
+        os2_mode = (
+            (df[heating_sig_col] == 0.0)
+            & (df[cooling_sig_col] == 0.0)
+            & (df[economizer_sig_col] > ahu_min_oa_dpr)
+        )
+
+        # OS3: Economizer + mechanical cooling (HTG = 0, CLG > 0, ECO > 0.9)
+        os3_mode = (
+            (df[heating_sig_col] == 0.0)
+            & (df[cooling_sig_col] > 0.0)
+            & (df[economizer_sig_col] > 0.9)
+        )
+
+        # OS4: Mechanical cooling only (HTG = 0, CLG > 0, ECO = MIN_OA)
+        os4_mode = (
+            (df[heating_sig_col] == 0.0)
+            & (df[cooling_sig_col] > 0.0)
+            & (df[economizer_sig_col] <= ahu_min_oa_dpr)
+        )
+
+        # Combine conditions:
+        # Fault occurs when there's a significant temperature rise across an inactive heating coil
+        # in OS2 (economizer), OS3 (economizer + mechanical cooling), or OS4 (mechanical cooling only) mode
+        combined_check = significant_temp_rise & (os2_mode | os3_mode | os4_mode)
+
+        # Set fault flag
+        self._set_fault_flag(df, combined_check, "fc15_flag")
+
+        return df

open_fdd-0.1.9/open_fdd/air_handling_unit/faults/fault_condition_five.py

@@ -0,0 +1,126 @@
+import pandas as pd
+
+from open_fdd.core.base_fault import BaseFaultCondition
+from open_fdd.core.components import FaultInputColumn, InstanceAttribute
+from open_fdd.core.exceptions import InvalidParameterError
+from open_fdd.core.mixins import FaultConditionMixin
+
+INPUT_COLS = [
+    FaultInputColumn(
+        name="mat_col",
+        constant_form="MAT_COL",
+        description="Mixed air temperature",
+        unit="°F",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="sat_col",
+        constant_form="SAT_COL",
+        description="Supply air temperature",
+        unit="°F",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="heating_sig_col",
+        constant_form="HEATING_SIG_COL",
+        description="Heating signal",
+        unit="%",
+        required=True,
+        type=float,
+    ),
+    FaultInputColumn(
+        name="supply_vfd_speed_col",
+        constant_form="SUPPLY_VFD_SPEED_COL",
+        description="Supply fan VFD speed",
+        unit="%",
+        required=True,
+        type=float,
+    ),
+]
+
+FAULT_PARAMS = [
+    InstanceAttribute(
+        name="mix_degf_err_thres",
+        constant_form="MIX_DEGF_ERR_THRES",
+        description="Mixed air temperature error threshold",
+        unit="°F",
+        type=float,
+        range=(0.0, 10.0),
+    ),
+    InstanceAttribute(
+        name="supply_degf_err_thres",
+        constant_form="SUPPLY_DEGF_ERR_THRES",
+        description="Supply air temperature error threshold",
+        unit="°F",
+        type=float,
+        range=(0.0, 10.0),
+    ),
+    InstanceAttribute(
+        name="delta_t_supply_fan",
+        constant_form="DELTA_T_SUPPLY_FAN",
+        description="Temperature rise across supply fan",
+        unit="°F",
+        type=float,
+        range=(0.0, 5.0),
+    ),
+]
+
+
+class FaultConditionFive(BaseFaultCondition, FaultConditionMixin):
+    """Class provides the definitions for Fault Condition 5.
+    SAT too low; should be higher than MAT in HTG MODE
+    --Broken heating valve or other mechanical issue
+    related to heat valve not working as designed
+
+    py -3.12 -m pytest open_fdd/tests/ahu/test_ahu_fc5.py -rP -s
+    """
+
+    input_columns = INPUT_COLS
+    fault_params = FAULT_PARAMS
+    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"
+    )
+    description_string = (
+        "Fault Condition 5: SAT too low; should be higher than MAT in HTG MODE, "
+        "potential broken heating valve or mechanical issue \n"
+    )
+    error_string = "One or more required columns are missing or None \n"
+
+    @FaultConditionMixin._handle_errors
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Apply the fault condition to the DataFrame."""
+        # Apply common checks
+        self._apply_common_checks(df)
+
+        # Get column values using accessor methods
+        supply_vfd_speed_col = self.get_input_column("supply_vfd_speed_col")
+        heating_sig_col = self.get_input_column("heating_sig_col")
+        sat_col = self.get_input_column("sat_col")
+        mat_col = self.get_input_column("mat_col")
+
+        # Get parameter values using accessor methods
+        supply_degf_err_thres = self.get_param("supply_degf_err_thres")
+        mix_degf_err_thres = self.get_param("mix_degf_err_thres")
+        delta_t_supply_fan = self.get_param("delta_t_supply_fan")
+
+        # Check analog outputs [data with units of %] are floats only
+        columns_to_check = [supply_vfd_speed_col, heating_sig_col]
+        self._apply_analog_checks(df, columns_to_check, check_greater_than_one=True)
+
+        # Perform checks
+        sat_check = df[sat_col] + supply_degf_err_thres
+        mat_check = df[mat_col] - mix_degf_err_thres + delta_t_supply_fan
+
+        combined_check = (
+            (sat_check <= mat_check)
+            & (df[heating_sig_col] > 0.01)
+            & (df[supply_vfd_speed_col] > 0.01)
+        )
+
+        # Set fault flag
+        self._set_fault_flag(df, combined_check, "fc5_flag")
+
+        return df