open-fdd 0.1.0__py3-none-any.whl

open_fdd/__init__.py

@@ -0,0 +1,39 @@
+"""
+open-fdd/                # Repository root
+├── open_fdd/            # Python package root
+│   ├── __init__.py
+│   ├── air_handling_unit/
+│   │   ├── __init__.py
+│   │   ├── faults/
+│   │   │   ├── __init__.py
+│   │   │   ├── helper_utils.pya
+│   │   │   ├── fault_condition.py
+│   │   │   ├── fault_condition_one.py
+│   │   │   ├── fault_condition_two.py
+│   │   │   └── ... # other fault conditions
+│   │   ├── examples/
+│   │   ├── reports/
+│   │   │   ├── __init__.py
+│   │   │   ├── base_report.py
+│   │   │   ├── report_fc1.py
+│   │   │   ├── report_fc2.py
+│   │   │   └── ... # other reports
+│   │   └── images/
+│   │       ├── fc1_definition.png
+│   │       ├── fc2_definition.png
+│   │       └── ... # other images
+│   ├── black_box/
+│   │   └── ... # subject to change being experimental
+├── tests/
+│   ├── __init__.py
+│   ├── air_handling_unit/
+│   │   ├── __init__.py
+│   │   ├── test_ahu_fc1.py
+│   │   ├── test_ahu_fc2.py
+│   │   └── ... # other tests
+├── setup.py
+├── README.md
+├── LICENSE
+└── requirements.txt
+
+"""

open_fdd/air_handling_unit/faults/fault_condition.py

@@ -0,0 +1,49 @@
+import pandas.api.types as pdtypes
+from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+import sys
+
+
+class FaultCondition:
+    """Parent class for Fault Conditions. Methods are inherited to all children."""
+
+    def set_attributes(self, dict_):
+        """Passes dictionary into initialization of class instance, then uses the attributes called out below in
+        attributes_dict to set only the attributes that match from dict_.
+
+        :param dict_: dictionary of all possible class attributes (loaded from config file)
+        """
+        for attribute in self.__dict__:
+            upper = attribute.upper()
+            value = dict_[upper]
+            self.__setattr__(attribute, value)
+
+    def troubleshoot_cols(self, df):
+        """print troubleshoot columns mapping
+
+        :param df:
+        :return:
+        """
+        print("Troubleshoot mode enabled - not removing helper columns")
+        for col in df.columns:
+            print(
+                "df column: ",
+                col,
+                "- max: ",
+                df[col].max(),
+                "- col type: ",
+                df[col].dtypes,
+            )
+            sys.stdout.flush()
+
+    def check_analog_pct(self, df, columns):
+        """check analog outputs [data with units of %] are floats only
+
+        :param columns:
+        :return:
+        """
+        helper = HelperUtils()
+        for col in columns:
+            if not pdtypes.is_float_dtype(df[col]):
+                df = helper.convert_to_float(df, col)
+            if df[col].max() > 1.0:
+                raise TypeError(helper.float_max_check_err(col))

open_fdd/air_handling_unit/faults/fault_condition_eight.py

@@ -0,0 +1,67 @@
+import pandas as pd
+import numpy as np
+from open_fdd.air_handling_unit.faults.fault_condition import FaultCondition
+from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+import sys
+
+
+class FaultConditionEight(FaultCondition):
+    """Class provides the definitions for Fault Condition 8.
+    Supply air temperature and mix air temperature should
+    be approx equal in economizer mode.
+    """
+
+    def __init__(self, dict_):
+        self.delta_t_supply_fan = float
+        self.mix_degf_err_thres = float
+        self.supply_degf_err_thres = float
+        self.ahu_min_oa_dpr = float
+        self.mat_col = str
+        self.sat_col = str
+        self.economizer_sig_col = str
+        self.cooling_sig_col = str
+        self.troubleshoot_mode = bool  # default should be False
+        self.rolling_window_size = int
+
+        self.set_attributes(dict_)
+
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        if self.troubleshoot_mode:
+            self.troubleshoot_cols(df)
+
+        # Check analog outputs [data with units of %] are floats only
+        columns_to_check = [
+            self.economizer_sig_col,
+            self.cooling_sig_col,
+        ]
+
+        self.check_analog_pct(df, columns_to_check)
+
+        df["sat_fan_mat"] = abs(
+            df[self.sat_col] - self.delta_t_supply_fan - df[self.mat_col]
+        )
+        df["sat_mat_sqrted"] = np.sqrt(
+            self.supply_degf_err_thres**2 + self.mix_degf_err_thres**2
+        )
+
+        df["combined_check"] = (
+            (df["sat_fan_mat"] > df["sat_mat_sqrted"])
+            & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
+            & (df[self.cooling_sig_col] < 0.1)
+        )
+
+        # Rolling sum to count consecutive trues
+        rolling_sum = (
+            df["combined_check"].rolling(window=self.rolling_window_size).sum()
+        )
+        # Set flag to 1 if rolling sum equals the window size
+        df["fc8_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
+
+        if self.troubleshoot_mode:
+            print("Troubleshoot mode enabled - not removing helper columns")
+            sys.stdout.flush()
+            del df["sat_fan_mat"]
+            del df["sat_mat_sqrted"]
+            del df["combined_check"]
+
+        return df

open_fdd/air_handling_unit/faults/fault_condition_eleven.py

@@ -0,0 +1,68 @@
+import pandas as pd
+import numpy as np
+from open_fdd.air_handling_unit.faults.fault_condition import FaultCondition
+from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+import sys
+
+
+class FaultConditionEleven(FaultCondition):
+    """Class provides the definitions for Fault Condition 11.
+    Outside air temperature too low for 100% outdoor
+    air cooling in economizer cooling mode.
+
+    Economizer performance fault
+    """
+
+    def __init__(self, dict_):
+        self.delta_t_supply_fan = float
+        self.outdoor_degf_err_thres = float
+        self.supply_degf_err_thres = float
+        self.sat_setpoint_col = str
+        self.oat_col = str
+        self.cooling_sig_col = str
+        self.economizer_sig_col = str
+        self.troubleshoot_mode = bool  # default False
+        self.rolling_window_size = int
+
+        self.set_attributes(dict_)
+
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        if self.troubleshoot_mode:
+            self.troubleshoot_cols(df)
+
+        # Check analog outputs [data with units of %] are floats only
+        columns_to_check = [
+            self.economizer_sig_col,
+            self.cooling_sig_col,
+        ]
+        self.check_analog_pct(df, columns_to_check)
+
+        df["oat_plus_oaterror"] = df[self.oat_col] + self.outdoor_degf_err_thres
+        df["satsp_delta_saterr"] = (
+            df[self.sat_setpoint_col]
+            - self.delta_t_supply_fan
+            - self.supply_degf_err_thres
+        )
+
+        df["combined_check"] = (
+            (df["oat_plus_oaterror"] < df["satsp_delta_saterr"])
+            # verify ahu is running in OS 3 clg mode in 100 OA
+            & (df[self.cooling_sig_col] > 0.01)
+            & (df[self.economizer_sig_col] > 0.9)
+        )
+
+        # Rolling sum to count consecutive trues
+        rolling_sum = (
+            df["combined_check"].rolling(window=self.rolling_window_size).sum()
+        )
+        # Set flag to 1 if rolling sum equals the window size
+        df["fc11_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
+
+        if self.troubleshoot_mode:
+            print("Troubleshoot mode enabled - not removing helper columns")
+            sys.stdout.flush()
+            del df["oat_plus_oaterror"]
+            del df["satsp_delta_saterr"]
+            del df["combined_check"]
+
+        return df

open_fdd/air_handling_unit/faults/fault_condition_fifteen.py

@@ -0,0 +1,90 @@
+import pandas as pd
+import numpy as np
+from open_fdd.air_handling_unit.faults.fault_condition import FaultCondition
+from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+import sys
+
+
+class FaultConditionFifteen(FaultCondition):
+    """Class provides the definitions for Fault Condition 15.
+    Temperature rise across inactive heating coi.
+    Requires coil leaving temp sensor.
+    """
+
+    def __init__(self, dict_):
+        self.delta_supply_fan = float
+        self.coil_temp_enter_err_thres = float
+        self.coil_temp_leav_err_thres = float
+        self.htg_coil_enter_temp_col = str
+        self.htg_coil_leave_temp_col = str
+        self.ahu_min_oa_dpr = float
+        self.cooling_sig_col = str
+        self.heating_sig_col = str
+        self.economizer_sig_col = str
+        self.supply_vfd_speed_col = str
+        self.troubleshoot_mode = bool  # default to False
+        self.rolling_window_size = int
+
+        self.set_attributes(dict_)
+
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        if self.troubleshoot_mode:
+            self.troubleshoot_cols(df)
+
+        # Check analog outputs [data with units of %] are floats only
+        columns_to_check = [
+            self.economizer_sig_col,
+            self.cooling_sig_col,
+            self.heating_sig_col,
+            self.supply_vfd_speed_col,
+        ]
+        self.check_analog_pct(df, columns_to_check)
+
+        # Create helper columns
+        df["htg_delta_temp"] = (
+            df[self.htg_coil_leave_temp_col] - df[self.htg_coil_enter_temp_col]
+        )
+
+        df["htg_delta_sqrted"] = (
+            np.sqrt(
+                self.coil_temp_enter_err_thres**2 + self.coil_temp_leav_err_thres**2
+            )
+            + self.delta_supply_fan
+        )
+
+        df["combined_check"] = (
+            (
+                (df["htg_delta_temp"] >= df["htg_delta_sqrted"])
+                # verify AHU is in OS2 only free cooling mode
+                & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
+                & (df[self.cooling_sig_col] < 0.1)
+            )
+            | (
+                (df["htg_delta_temp"] >= df["htg_delta_sqrted"])
+                # OS4 AHU state clg @ min OA
+                & (df[self.cooling_sig_col] > 0.01)
+                & (df[self.economizer_sig_col] == self.ahu_min_oa_dpr)
+            )
+            | (
+                (df["htg_delta_temp"] >= df["htg_delta_sqrted"])
+                # verify AHU is running in OS 3 clg mode in 100 OA
+                & (df[self.cooling_sig_col] > 0.01)
+                & (df[self.economizer_sig_col] > 0.9)
+            )
+        )
+
+        # Rolling sum to count consecutive trues
+        rolling_sum = (
+            df["combined_check"].rolling(window=self.rolling_window_size).sum()
+        )
+        # Set flag to 1 if rolling sum equals the window size
+        df["fc15_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
+
+        if self.troubleshoot_mode:
+            print("Troubleshoot mode enabled - not removing helper columns")
+            sys.stdout.flush()
+            del df["htg_delta_temp"]
+            del df["htg_delta_sqrted"]
+            del df["combined_check"]
+
+        return df

open_fdd/air_handling_unit/faults/fault_condition_five.py

@@ -0,0 +1,68 @@
+import pandas as pd
+import pandas.api.types as pdtypes
+from open_fdd.air_handling_unit.faults.fault_condition import FaultCondition
+from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+import sys
+
+
+class FaultConditionFive(FaultCondition):
+    """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
+    """
+
+    def __init__(self, dict_):
+        self.mix_degf_err_thres = float
+        self.supply_degf_err_thres = float
+        self.delta_t_supply_fan = float
+        self.mat_col = str
+        self.sat_col = str
+        self.heating_sig_col = str
+        self.supply_vfd_speed_col = str
+        self.troubleshoot_mode = bool  # default to False
+        self.rolling_window_size = int
+
+        self.set_attributes(dict_)
+
+    # fault only active if fan is running and htg vlv is modulating
+    # OS 1 is heating mode only fault
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        if self.troubleshoot_mode:
+            self.troubleshoot_cols(df)
+
+        # check analog outputs [data with units of %] are floats only
+        columns_to_check = [self.supply_vfd_speed_col, self.heating_sig_col]
+
+        for col in columns_to_check:
+            self.check_analog_pct(df, [col])
+
+        df["sat_check"] = df[self.sat_col] + self.supply_degf_err_thres
+        df["mat_check"] = (
+            df[self.mat_col] - self.mix_degf_err_thres + self.delta_t_supply_fan
+        )
+
+        df["combined_check"] = (
+            (df["sat_check"] <= df["mat_check"])
+            # this is to make fault only active in OS1 for htg mode only
+            # and fan is running. Some control programming may use htg
+            # vlv when AHU is off to prevent low limit freeze alarms
+            & (df[self.heating_sig_col] > 0.01)
+            & (df[self.supply_vfd_speed_col] > 0.01)
+        )
+
+        # Rolling sum to count consecutive trues
+        rolling_sum = (
+            df["combined_check"].rolling(window=self.rolling_window_size).sum()
+        )
+        # Set flag to 1 if rolling sum equals the window size
+        df["fc5_flag"] = (rolling_sum == self.rolling_window_size).astype(int)
+
+        if self.troubleshoot_mode:
+            print("Troubleshoot mode enabled - not removing helper columns")
+            sys.stdout.flush()
+            del df["mat_check"]
+            del df["sat_check"]
+            del df["combined_check"]
+
+        return df

open_fdd/air_handling_unit/faults/fault_condition_four.py

@@ -0,0 +1,93 @@
+import pandas as pd
+from open_fdd.air_handling_unit.faults.fault_condition import FaultCondition
+from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+import sys
+
+
+class FaultConditionFour(FaultCondition):
+    """Class provides the definitions for Fault Condition 4.
+
+    This fault flags excessive operating states on the AHU
+    if its hunting between heating, econ, econ+mech, and
+    a mech clg modes. The code counts how many operating
+    changes in an hour and will throw a fault if there is
+    excessive OS changes to flag control sys hunting.
+
+    """
+
+    def __init__(self, dict_):
+        self.delta_os_max = float
+        self.ahu_min_oa_dpr = float
+        self.economizer_sig_col = str
+        self.heating_sig_col = str
+        self.cooling_sig_col = str
+        self.supply_vfd_speed_col = str
+        self.troubleshoot_mode = bool  # default to False
+
+        self.set_attributes(dict_)
+
+    # adds in these boolean columns to the dataframe
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        if self.troubleshoot_mode:
+            self.troubleshoot_cols(df)
+
+        # check analog outputs [data with units of %] are floats only
+        columns_to_check = [
+            self.economizer_sig_col,
+            self.heating_sig_col,
+            self.cooling_sig_col,
+            self.supply_vfd_speed_col,
+        ]
+
+        for col in columns_to_check:
+            self.check_analog_pct(df, [col])
+
+        print("=" * 50)
+        print("Warning: The program is in FC4 and resampling the data")
+        print("to compute AHU OS state changes per hour")
+        print("to flag any hunting issue")
+        print("and this usually takes a while to run...")
+        print("=" * 50)
+
+        sys.stdout.flush()
+
+        # AHU htg only mode based on OA damper @ min oa and only htg pid/vlv modulating
+        df["heating_mode"] = (
+            (df[self.heating_sig_col] > 0)
+            & (df[self.cooling_sig_col] == 0)
+            & (df[self.supply_vfd_speed_col] > 0)
+            & (df[self.economizer_sig_col] == self.ahu_min_oa_dpr)
+        )
+
+        # AHU econ only mode based on OA damper modulating and clg htg = zero
+        df["econ_only_cooling_mode"] = (
+            (df[self.heating_sig_col] == 0)
+            & (df[self.cooling_sig_col] == 0)
+            & (df[self.supply_vfd_speed_col] > 0)
+            & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
+        )
+
+        # AHU econ+mech clg mode based on OA damper modulating for cooling and clg pid/vlv modulating
+        df["econ_plus_mech_cooling_mode"] = (
+            (df[self.heating_sig_col] == 0)
+            & (df[self.cooling_sig_col] > 0)
+            & (df[self.supply_vfd_speed_col] > 0)
+            & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
+        )
+
+        # AHU mech mode based on OA damper @ min OA and clg pid/vlv modulating
+        df["mech_cooling_only_mode"] = (
+            (df[self.heating_sig_col] == 0)
+            & (df[self.cooling_sig_col] > 0)
+            & (df[self.supply_vfd_speed_col] > 0)
+            & (df[self.economizer_sig_col] == self.ahu_min_oa_dpr)
+        )
+
+        # Fill non-finite values with zero or drop them
+        df = df.fillna(0)
+
+        df = df.astype(int)
+        df = df.resample("60min").apply(lambda x: (x.eq(1) & x.shift().ne(1)).sum())
+
+        df["fc4_flag"] = df[df.columns].gt(self.delta_os_max).any(axis=1).astype(int)
+        return df

open_fdd/air_handling_unit/faults/fault_condition_fourteen.py

@@ -0,0 +1,80 @@
+import pandas as pd
+import numpy as np
+from open_fdd.air_handling_unit.faults.fault_condition import FaultCondition
+from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+import operator
+import sys
+
+
+class FaultConditionFourteen(FaultCondition):
+    """Class provides the definitions for Fault Condition 14.
+    Temperature drop across inactive cooling coil.
+    Requires coil leaving temp sensor.
+    """
+
+    def __init__(self, dict_):
+        self.delta_t_supply_fan = float
+        self.coil_temp_enter_err_thres = float
+        self.coil_temp_leav_err_thres = float
+        self.clg_coil_enter_temp_col = str
+        self.clg_coil_leave_temp_col = str
+        self.ahu_min_oa_dpr = float
+        self.cooling_sig_col = str
+        self.heating_sig_col = str
+        self.economizer_sig_col = str
+        self.supply_vfd_speed_col = str
+        self.troubleshoot_mode = bool  # default to False
+        self.rolling_window_size = int
+
+        self.set_attributes(dict_)
+
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        if self.troubleshoot_mode:
+            self.troubleshoot_cols(df)
+
+        # Check analog outputs [data with units of %] are floats only
+        columns_to_check = [
+            self.economizer_sig_col,
+            self.cooling_sig_col,
+            self.heating_sig_col,
+            self.supply_vfd_speed_col,
+        ]
+        self.check_analog_pct(df, columns_to_check)
+
+        # Create helper columns
+        df["clg_delta_temp"] = (
+            df[self.clg_coil_enter_temp_col] - df[self.clg_coil_leave_temp_col]
+        )
+
+        df["clg_delta_sqrted"] = (
+            np.sqrt(
+                self.coil_temp_enter_err_thres**2 + self.coil_temp_leav_err_thres**2
+            )
+            + self.delta_t_supply_fan
+        )
+
+        df["combined_check"] = operator.or_(
+            (df["clg_delta_temp"] >= df["clg_delta_sqrted"])
+            # verify AHU is in OS2 only free cooling mode
+            & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
+            & (df[self.cooling_sig_col] < 0.1),  # OR
+            (df["clg_delta_temp"] >= df["clg_delta_sqrted"])
+            # verify AHU is running in OS 1 at near full heat
+            & (df[self.heating_sig_col] > 0.0) & (df[self.supply_vfd_speed_col] > 0.0),
+        )
+
+        # Rolling sum to count consecutive trues
+        rolling_sum = (
+            df["combined_check"].rolling(window=self.rolling_window_size).sum()
+        )
+        # Set flag to 1 if rolling sum equals the window size
+        df["fc14_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
+
+        if self.troubleshoot_mode:
+            print("Troubleshoot mode enabled - not removing helper columns")
+            sys.stdout.flush()
+            del df["clg_delta_temp"]
+            del df["clg_delta_sqrted"]
+            del df["combined_check"]
+
+        return df

open_fdd/air_handling_unit/faults/fault_condition_nine.py

@@ -0,0 +1,68 @@
+import pandas as pd
+import numpy as np
+from open_fdd.air_handling_unit.faults.fault_condition import FaultCondition
+from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+import sys
+
+
+class FaultConditionNine(FaultCondition):
+    """Class provides the definitions for Fault Condition 9.
+    Outside air temperature too high in free cooling without
+    additional mechanical cooling in economizer mode.
+    """
+
+    def __init__(self, dict_):
+        self.delta_t_supply_fan = float
+        self.outdoor_degf_err_thres = float
+        self.supply_degf_err_thres = float
+        self.ahu_min_oa_dpr = float
+        self.sat_setpoint_col = str
+        self.oat_col = str
+        self.cooling_sig_col = str
+        self.economizer_sig_col = str
+        self.troubleshoot_mode = bool  # default should be False
+        self.rolling_window_size = int
+
+        self.set_attributes(dict_)
+
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        if self.troubleshoot_mode:
+            self.troubleshoot_cols(df)
+
+        # Check analog outputs [data with units of %] are floats only
+        columns_to_check = [
+            self.economizer_sig_col,
+            self.cooling_sig_col,
+        ]
+        self.check_analog_pct(df, columns_to_check)
+
+        # Create helper columns
+        df["oat_minus_oaterror"] = df[self.oat_col] - self.outdoor_degf_err_thres
+        df["satsp_delta_saterr"] = (
+            df[self.sat_setpoint_col]
+            - self.delta_t_supply_fan
+            + self.supply_degf_err_thres
+        )
+
+        df["combined_check"] = (
+            (df["oat_minus_oaterror"] > df["satsp_delta_saterr"])
+            # verify AHU is in OS2 only free cooling mode
+            & (df[self.economizer_sig_col] > self.ahu_min_oa_dpr)
+            & (df[self.cooling_sig_col] < 0.1)
+        )
+
+        # Rolling sum to count consecutive trues
+        rolling_sum = (
+            df["combined_check"].rolling(window=self.rolling_window_size).sum()
+        )
+        # Set flag to 1 if rolling sum equals the window size
+        df["fc9_flag"] = (rolling_sum >= self.rolling_window_size).astype(int)
+
+        if self.troubleshoot_mode:
+            print("Troubleshoot mode enabled - not removing helper columns")
+            sys.stdout.flush()
+            del df["oat_minus_oaterror"]
+            del df["satsp_delta_saterr"]
+            del df["combined_check"]
+
+        return df