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

open_fdd/air_handling_unit/images/latex_generator.py

@@ -0,0 +1,175 @@
+import streamlit as st
+
+
+# On windows 10 python 3.10.6
+# py -3.10 -m streamlit run .\latex_generator.py
+
+# display Fault Equation 1
+st.title("Fault Equation 1")
+st.caption("Duct static pressure too low with fan at full speed")
+st.latex(
+    r"""
+    DSP < DPSP - eDSP \quad \text{and} \quad VFDSPD \geq 99\% - eVFDSPD
+    """
+)
+
+# Display legend
+st.markdown("Legend:")
+st.markdown("- DSP: Duct Static Pressure")
+st.markdown("- DPSP: Duct Static Pressure Setpoint")
+st.markdown("- VFDSPD: VFD Speed Reference in Percent")
+st.markdown("- eVFDSPD: VFD Speed Reference Error Threshold")
+
+
+# display Fault Equation 2
+st.title("Fault Equation 2")
+st.caption('Mix air temperature too low; should be between outside and return')
+st.latex(r'''
+    MAT_{avg} + eMAT < \min[(RAT_{avg} - eRAT), - OAT_{avg} - eOAT)]
+    ''')
+
+
+# display Fault Equation 3
+st.title("Fault Equation 3")
+st.caption('Mix air temperature too high; should be between outside and return')
+st.latex(r'''
+    MAT_{avg} - eMAT > \min[(RAT_{avg} + eRAT), - OAT_{avg} + eOAT)]
+    ''')
+
+        
+# display Fault Equation 4
+st.title("Fault Equation 4")
+st.caption('Too many AHU operating state changes due to PID hunting and/or excessive cycling during low load conditions.')
+st.latex(r'''
+    \Delta OS > \Delta OS_{max}
+    ''')
+
+
+# display Fault Equation 5
+st.title("Fault Equation 5")
+st.caption('Supply air temperature too high')
+st.latex(r'''
+    SAT_{avg} + eSAT \leq MAT_{avg} - eMAT + \Delta TSF
+    ''')
+
+
+# display Fault Equation 6
+st.title("Fault Equation 6")
+st.caption('Temperature and outside air percentage deviation from setpoints')
+st.latex(r'''
+    |\text{RAT}_{\text{avg}} - \text{OAT}_{\text{avg}}| \geq \Delta T_{\text{min}} \quad \text{and} \quad |\%OA - \%OA_{\text{min}}| > eF
+    ''')
+
+
+# display Fault Equation 7
+st.title("Fault Equation 7")
+st.caption('Supply air temperature too low and heating coil status')
+st.latex(r'''
+    \text{SAT}_{\text{avg}} < \text{SATSP} - eSAT \quad \text{and} \quad \text{HC} \geq 99\%
+    ''')
+
+# display Fault Equation 8
+st.title("Fault Equation 8")
+st.caption('Deviation between supply air temperature and mixed air temperature')
+st.latex(r'''
+    | \text{SAT}_{\text{avg}} - \Delta \text{TSF} - \text{MAT}_{\text{avg}} | > \sqrt{{eSAT}^2 + {eMAT}^2}
+    ''')
+
+
+# display Fault Equation 9
+st.title("Fault Equation 9")
+st.caption('Outside air temperature deviation from setpoint')
+st.latex(r'''
+    \text{OAT}_{\text{avg}} - eOAT > \text{SATSP} - \Delta \text{SF} + eSAT
+    ''')
+
+# display Fault Equation 10
+st.title("Fault Equation 10")
+st.caption('Temperature difference between mixed air and outside air')
+st.latex(r'''
+    | \text{MAT}_{\text{avg}} - \text{OAT}_{\text{avg}} | > \sqrt{eMAT^2 + eOAT^2}
+    ''')
+
+# display Fault Equation 11
+st.title("Fault Equation 11")
+st.caption('Outside air temperature and supply air temperature deviation')
+st.latex(r'''
+    \text{OAT}_{\text{avg}} + eOAT < \text{SATSP} - \Delta \text{TSF} - eSAT
+    ''')
+
+# display Fault Equation 12
+st.title("Fault Equation 12")
+st.caption('Supply air temperature deviation from mixed air temperature')
+st.latex(r'''
+    \text{SAT}_{\text{avg}} - eSAT - \Delta \text{TSF} \geq \text{MAT}_{\text{avg}} + eMAT
+    ''')
+
+# display Fault Equation 13
+st.title("Fault Equation 13")
+st.caption('Supply air temperature too high')
+st.latex(r'''
+    \text{SAT}_{\text{avg}} < \text{SATSP} + eSAT \quad \text{and} \quad \text{CC} \geq 99\%
+    ''')
+
+
+st.title("find_closest_weather_dates Function")
+st.caption('Finding closest weather dates based on given criteria')
+st.latex(r'''
+1. A' = \{a \in A : a < d_{test}\} \\
+2. B' = \{b \in B : b < d_{test}\} \\
+3. C = \{a \in A' : a \notin B'\} \\
+4. \text{if } |C| < 10 \text{ then remove } \max(A') \text{ and repeat step 3} \\
+5. A = A \cap C, \text{calculate } \mu(A)
+''')
+st.caption('''
+In this notation:
+- $A$ represents the "all_data" dataset.
+- $B$ represents the "suitable_baseline_no" dataset.
+- $d_{test}$ is the "test_case_date".
+- $A'$ and $B'$ are subsets of $A$ and $B$ that only include dates prior to $d_{test}$.
+- $C$ is a set of dates in $A'$ not found in $B'$.
+- $|C|$ represents the count of elements in set $C$.
+- $\max(A')$ is the latest date in $A'$.
+- $\mu(A)$ is the mean of the remaining elements in $A$ after filtering by set $C$.
+''')
+
+
+st.title("find_previous_10_days Function")
+st.caption('Finding previous 10 weekdays based on given criteria')
+st.latex(r'''
+1. A' = \{a \in A : a < d_{test}\} \\
+2. B' = \{b \in B : b < d_{test}\} \\
+3. C = \{a \in A' : a \notin B'\} \\
+4. \text{if } |C| < 10 \text{ then remove } \max(A') \text{ and repeat step 3} \\
+5. A = A \cap C
+''')
+st.caption('''
+In this notation:
+- $A$ represents the "all_data" dataset.
+- $B$ represents the "suitable_baseline_no" dataset.
+- $d_{test}$ is the "test_case_date".
+- $A'$ and $B'$ are subsets of $A$ and $B$ that only include dates prior to $d_{test}$.
+- $C$ is a set of dates in $A'$ not found in $B'$.
+- $|C|$ represents the count of elements in set $C$.
+- $\max(A')$ is the latest date in $A'$.
+''')
+
+
+st.title("calculate_power_averages Function")
+st.caption('Calculating average power for each type and time step')
+st.latex(r'''
+1. P_{type,i} = \{p : p \text{ is a power value at time step } t_i\} \quad \text{for each type and } i \in \{1,2,\dots,96\} \\
+2. A_{type,i} = \frac{1}{|P_{type,i}|}\sum_{p \in P_{type,i}} p \quad \text{for each type and } i \in \{1,2,\dots,96\}
+''')
+st.caption('''
+In this notation:
+- $P_{type,i}$ represents the set of power values at time step $t_i$ for a specific power type (main, ahu, or solar).
+- $p$ represents a power value in the set $P_{type,i}$.
+- $|P_{type,i}|$ represents the count of elements in set $P_{type,i}$.
+- $A_{type,i}$ represents the average power at time step $t_i$ for a specific power type.
+''')
+
+
+
+
+

open_fdd/air_handling_unit/reports/base_report.py

@@ -0,0 +1,47 @@
+import matplotlib.pyplot as plt
+import pandas as pd
+from io import BytesIO
+import sys
+
+class BaseReport:
+    def __init__(self, config):
+        self.config = config
+
+    def summarize_fault_times(self, df: pd.DataFrame, output_col: str) -> dict:
+        delta = df.index.to_series().diff().dt.total_seconds()
+        total_days = round(delta.sum() / 86400, 2)
+        total_hours = round(delta.sum() / 3600, 2)
+        hours_fault_mode = (delta * df[output_col]).sum() / 3600
+        percent_true = round(df[output_col].mean() * 100, 2)
+        percent_false = round((100 - percent_true), 2)
+
+        # Calculate motor runtime
+        motor_on = df[self.config['SUPPLY_VFD_SPEED_COL']].gt(.01).astype(int)
+        hours_motor_runtime = round((delta * motor_on).sum() / 3600, 2)
+
+        summary = {
+            'total_days': total_days,
+            'total_hours': total_hours,
+            'hours_fault_mode': hours_fault_mode,
+            'percent_true': percent_true,
+            'percent_false': percent_false,
+            'hours_motor_runtime': hours_motor_runtime
+        }
+        return summary
+
+    def create_hist_plot(self, df: pd.DataFrame, output_col: str):
+        df["hour_of_the_day"] = df.index.hour.where(df[output_col] == 1)
+        df = df.dropna(subset=["hour_of_the_day"])
+        print()
+        print("Time-of-day Histogram Data")
+        print(df["hour_of_the_day"])
+        print()
+        sys.stdout.flush()
+
+        fig, ax = plt.subplots(tight_layout=True, figsize=(25, 8))
+        ax.hist(df.hour_of_the_day.dropna(), bins=24)
+        ax.set_xlabel("Hour of the Day")
+        ax.set_ylabel("Frequency")
+        ax.set_title("Hour-Of-Day When Fault Flag is TRUE")
+        plt.show()
+        plt.close()

open_fdd/air_handling_unit/reports/report_fc7.py

@@ -82,7 +82,9 @@ class FaultCodeSevenReport:
         plt.close()
 
     def display_report_in_ipython(self, df: pd.DataFrame, output_col: str = "fc7_flag"):
-        print("Fault Condition 7: Supply air temperature too low in full heating mode")
+        print(
+            "Fault Condition 7: Supply air temperature too low its not making supply air temperature setpoint in full heating mode"
+        )
 
         self.create_plot(df, output_col)
 

open_fdd/tests/ahu/test_ahu_fc1.py

@@ -2,6 +2,8 @@ import pandas as pd
 import pytest
 from open_fdd.air_handling_unit.faults.fault_condition_one import FaultConditionOne
 from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
+from open_fdd.air_handling_unit.faults.fault_condition import MissingColumnError
+
 
 # Constants
 TEST_VFD_ERR_THRESHOLD = 0.05
@@ -27,6 +29,21 @@ fault_condition_params = {
 fc1 = FaultConditionOne(fault_condition_params)
 
 
+class TestMissingColumn:
+
+    def missing_col_df(self) -> pd.DataFrame:
+        data = {
+            TEST_DUCT_STATIC_COL: [0.99, 0.99, 0.99, 0.99, 0.99, 0.99],
+            # Missing TEST_SUPPLY_VFD_SPEED_COL
+            TEST_DUCT_STATIC_SETPOINT_COL: [1.0, 1.0, 1.0, 1.0, 1.0, 1.0],
+        }
+        return pd.DataFrame(data)
+
+    def test_missing_column(self):
+        with pytest.raises(MissingColumnError):
+            fc1.apply(self.missing_col_df())
+
+
 class TestNoFault:
 
     def no_fault_df(self) -> pd.DataFrame:

open_fdd/tests/ahu/test_ahu_fc4.py

@@ -1,200 +1,128 @@
 import pandas as pd
-import pytest
-from open_fdd.air_handling_unit.faults.fault_condition_four import FaultConditionFour
-from open_fdd.air_handling_unit.faults.helper_utils import HelperUtils
-from datetime import datetime, timezone
-
-"""
-To see print statements in pytest run with:
-$ py -3.12 -m pytest open_fdd/tests/ahu/test_ahu_fc4.py -rP -s
-
-Too much hunting in control system
-OS state changes greater than 7 in an hour
-"""
-
-# Constants
-DELTA_OS_MAX = 7
-AHU_MIN_OA = 0.20
-TEST_MIX_AIR_DAMPER_COL = "economizer_sig_col"
-TEST_HEATING_COIL_SIG_COL = "heating_sig_col"
-TEST_COOLING_COIL_SIG_COL = "cooling_sig_col"
-TEST_SUPPLY_VFD_SPEED_COL = "fan_vfd_speed_col"
-TEST_DATASET_ROWS = 60
-
-# Initialize FaultConditionFour with a dictionary
-fault_condition_params = {
-    "DELTA_OS_MAX": DELTA_OS_MAX,
-    "AHU_MIN_OA_DPR": AHU_MIN_OA,
-    "ECONOMIZER_SIG_COL": TEST_MIX_AIR_DAMPER_COL,
-    "HEATING_SIG_COL": TEST_HEATING_COIL_SIG_COL,
-    "COOLING_SIG_COL": TEST_COOLING_COIL_SIG_COL,
-    "SUPPLY_VFD_SPEED_COL": TEST_SUPPLY_VFD_SPEED_COL,
-    "TROUBLESHOOT_MODE": False,  # default value
-}
-
-fc4 = FaultConditionFour(fault_condition_params)
-
-
-def generate_timestamp() -> pd.Series:
-    df = pd.DataFrame()
-    date_range = pd.period_range(
-        # make a time stamp starting at top of
-        # the hour with one min intervals
-        start=datetime(2022, 6, 6, 14, 30, 0, 0, tzinfo=timezone.utc),
-        periods=TEST_DATASET_ROWS,
-        freq="min",
-    )
-    df["Date"] = [x.to_timestamp() for x in date_range]
-    return df["Date"]
-
-
-def econ_plus_mech_clg_row() -> dict:
-    data = {
-        TEST_MIX_AIR_DAMPER_COL: 0.6,
-        TEST_HEATING_COIL_SIG_COL: 0.0,
-        TEST_COOLING_COIL_SIG_COL: 0.6,
-        TEST_SUPPLY_VFD_SPEED_COL: 0.8,
-    }
-    return data
-
-
-def mech_clg_row() -> dict:
-    data = {
-        TEST_MIX_AIR_DAMPER_COL: 0.0,
-        TEST_HEATING_COIL_SIG_COL: 0.0,
-        TEST_COOLING_COIL_SIG_COL: 0.6,
-        TEST_SUPPLY_VFD_SPEED_COL: 0.8,
-    }
-    return data
-
-
-def econ_plus_mech_clg_row_int() -> dict:
-    data = {
-        TEST_MIX_AIR_DAMPER_COL: 0.6,
-        TEST_HEATING_COIL_SIG_COL: 0.0,
-        TEST_COOLING_COIL_SIG_COL: 0.6,
-        TEST_SUPPLY_VFD_SPEED_COL: 88,
-    }
-    return data
-
-
-def econ_plus_mech_clg_row_float_greater_than_one() -> dict:
-    data = {
-        TEST_MIX_AIR_DAMPER_COL: 0.6,
-        TEST_HEATING_COIL_SIG_COL: 0.0,
-        TEST_COOLING_COIL_SIG_COL: 0.6,
-        TEST_SUPPLY_VFD_SPEED_COL: 88.8,
-    }
-    return data
-
-
-class TestFault(object):
-
-    def fault_df(self) -> pd.DataFrame:
-        data = []
-        counter = 0
-        for i in range(TEST_DATASET_ROWS):
-            if i % 2 == 0 and counter < 11:
-                data.append(econ_plus_mech_clg_row())
-                counter += 1  # only simulate 10 OS changes
-            else:
-                data.append(mech_clg_row())
-        return pd.DataFrame(data)
-
-    def test_fault(self):
-        fault_df = self.fault_df().set_index(generate_timestamp())
-        results = fc4.apply(fault_df)
-        actual = results["fc4_flag"].sum()
-        expected = 1
-        message = f"FC4 fault_df actual is {actual} and expected is {expected}"
-        assert actual == expected, message
-
-
-class TestNoFault(object):
-
-    def no_fault_df(self) -> pd.DataFrame:
-        data = []
-        for i in range(TEST_DATASET_ROWS):
-            data.append(mech_clg_row())
-        return pd.DataFrame(data)
-
-    def test_no_fault(self):
-        no_fault_df = self.no_fault_df().set_index(generate_timestamp())
-        results = fc4.apply(no_fault_df)
-        actual = results["fc4_flag"].sum()
-        expected = 0
-        message = f"FC4 no_fault_df actual is {actual} and expected is {expected}"
-        assert actual == expected, message
-
-
-class TestFaultOnInt(object):
-
-    def fault_df_on_output_int(self) -> pd.DataFrame:
-        data = []
-        for i in range(TEST_DATASET_ROWS):
-            if i % 2 == 0:
-                data.append(econ_plus_mech_clg_row_int())
-            else:
-                data.append(mech_clg_row())
-        return pd.DataFrame(data)
-
-    def test_fault_on_int(self):
-        fault_df_on_output_int = self.fault_df_on_output_int().set_index(
-            generate_timestamp()
-        )
-        with pytest.raises(
-            TypeError,
-            match=HelperUtils().float_int_check_err(TEST_SUPPLY_VFD_SPEED_COL),
-        ):
-            fc4.apply(fault_df_on_output_int)
-
-
-class TestFaultOnFloatGreaterThanOne(object):
-
-    def fault_df_on_output_greater_than_one(self) -> pd.DataFrame:
-        data = []
-        for i in range(TEST_DATASET_ROWS):
-            if i % 2 == 0:
-                data.append(econ_plus_mech_clg_row_float_greater_than_one())
-            else:
-                data.append(mech_clg_row())
-        return pd.DataFrame(data)
-
-    def test_fault_on_float_greater_than_one(self):
-        fault_df_on_output_greater_than_one = (
-            self.fault_df_on_output_greater_than_one().set_index(generate_timestamp())
-        )
-        with pytest.raises(
-            TypeError,
-            match=HelperUtils().float_max_check_err(TEST_SUPPLY_VFD_SPEED_COL),
-        ):
-            fc4.apply(fault_df_on_output_greater_than_one)
-
-
-class TestFaultOnMixedTypes(object):
-
-    def fault_df_on_mixed_types(self) -> pd.DataFrame:
-        data = []
-        for i in range(TEST_DATASET_ROWS):
-            if i % 2 == 0:
-                data.append(
-                    {
-                        TEST_MIX_AIR_DAMPER_COL: 0.6,
-                        TEST_HEATING_COIL_SIG_COL: 0.0,
-                        TEST_COOLING_COIL_SIG_COL: 0.6,
-                        TEST_SUPPLY_VFD_SPEED_COL: 1.1,
-                    }
-                )
-            else:
-                data.append(mech_clg_row())
-        return pd.DataFrame(data)
-
-    def test_fault_on_mixed_types(self):
-        fault_df_on_mixed_types = self.fault_df_on_mixed_types().set_index(
-            generate_timestamp()
-        )
-        with pytest.raises(
-            TypeError,
-            match=HelperUtils().float_max_check_err(TEST_SUPPLY_VFD_SPEED_COL),
-        ):
-            fc4.apply(fault_df_on_mixed_types)
+from open_fdd.air_handling_unit.faults.fault_condition import (
+    FaultCondition,
+    MissingColumnError,
+)
+import sys
+
+
+class FaultConditionFour(FaultCondition):
+    """Class provides the definitions for Fault Condition 4.
+
+    This fault flags excessive operating states on the AHU
+    if it's 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_):
+        super().__init__()
+        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_)
+
+        # Set required columns, making heating and cooling optional
+        self.required_columns = [
+            self.economizer_sig_col,
+            self.supply_vfd_speed_col,
+        ]
+
+        # If heating or cooling columns are provided, add them to the required columns
+        if self.heating_sig_col:
+            self.required_columns.append(self.heating_sig_col)
+        if self.cooling_sig_col:
+            self.required_columns.append(self.cooling_sig_col)
+
+    def get_required_columns(self) -> str:
+        """Returns a string representation of the required columns."""
+        return f"Required columns for FaultConditionFour: {', '.join(self.required_columns)}"
+
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        try:
+            # Ensure all required columns are present
+            self.check_required_columns(df)
+
+            # If the optional columns are not present, create them with all values set to 0.0
+            if self.heating_sig_col not in df.columns:
+                df[self.heating_sig_col] = 0.0
+            if self.cooling_sig_col not in df.columns:
+                df[self.cooling_sig_col] = 0.0
+
+            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
+
+        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