add hvac data-monitoring demo

examples/hvac-data-monitoring/.env.template

@@ -0,0 +1,2 @@
+HF_API_KEY=[... HuggingFace API key if running HuggingFace-hosted models ...]
+OPENAI_API_KEY=[... OpenAI API key if running on OpenAI services ...]

examples/hvac-data-monitoring/.gitignore

@@ -0,0 +1,5 @@
+# environment variables
+.env
+
+# Streamlit secrets
+.streamlit/secrets.toml

examples/hvac-data-monitoring/.streamlit/secrets.toml.template

@@ -0,0 +1,2 @@
+HF_API_KEY = '[... HuggingFace API key if running HuggingFace-hosted models ...]'
+OPENAI_API_KEY = '[... OpenAI API key if running on OpenAI services ...]'

examples/hvac-data-monitoring/Makefile

@@ -0,0 +1,2 @@
+streamlit-run:
+	@poetry run streamlit run streamlit-main.py --server.allowRunOnSave=true --server.runOnSave=true

examples/hvac-data-monitoring/README.md

@@ -0,0 +1,16 @@
+<!-- markdownlint-disable MD013 MD043 -->
+
+# Semiconductor Etching YieldGuard
+
+## How to Run This Example
+
+Install OpenSSA repo beforehand by running `make install` (or `.\make install` on Windows)
+at the OpenSSA repo root directory.
+
+In this example's directory:
+
+- Necessary credentials need to be in the `.env` file
+
+- DANA problem-solving can be run by `make dana-solve prob="..."` (or `.\make dana-solve "..."` on Windows)
+
+- Streamlit app can be run by `make streamlit-run` (or `.\make streamlit-run` on Windows)

examples/hvac-data-monitoring/Sensor_Readings.txt

@@ -0,0 +1,11 @@
+TimeStamp: 1, 2, 3, 4, 5, 6
+
+Temperature: 20.0, 19.5, 19.0, 19.2, 18.8, 18.5
+
+Occupancy: 5, 5, 5, 5, 5, 5
+
+HVAC Energy Usage (kWh): 150, 150, 150, 150, 150, 150
+
+CO Levels (ppm): 5.0, 9.5, 10.0, 10.5, 10.0, 9.5
+
+CO2 Levels (ppm): 1450, 1500, 1550, 1600, 1550, 1500

examples/hvac-data-monitoring/ans1.md

@@ -0,0 +1,49 @@
+# Temperature Fluctuation Analysis and Recommendations
+
+To identify and address the temperature fluctuation issue from the data, we need to consider the observed temperature readings and apply the HVAC sensor monitoring rules.
+
+## Temperature Data Analysis
+
+The recorded temperature values are **20.0°C, 19.5°C, 19.0°C, 19.2°C, 18.8°C, and 18.5°C**. These readings show a consistent decline, with a maximum deviation of **-1.5°C** from the initial setpoint of **20.0°C**. This deviation does not exceed the **±2°C threshold** specified in the Temperature Sensor Rule for more than 1 hour, indicating that the fluctuation is within acceptable limits.
+
+## Recommendations
+
+### 1. System Inspection
+Despite the deviation being within limits, it is prudent to conduct a thorough inspection of the HVAC system to preemptively identify any potential issues. This includes:
+- Checking for mechanical failures.
+- Inspecting refrigerant levels for leaks.
+- Verifying thermostat functionality.
+- Ensuring air filters are not blocked.
+
+### 2. Calibration
+Verify that the temperature sensors are properly calibrated to ensure accurate readings and prevent improper system responses.
+
+### 3. Regular Maintenance
+Implement a regular maintenance schedule to:
+- Clean components.
+- Check for wear and tear.
+- Ensure optimal functioning of all parts.
+
+### 4. Load Assessment
+Evaluate the thermal load of the monitored space to ensure the HVAC system is adequately sized for its usage patterns, especially if occupancy remains constant.
+
+### 5. Control System Optimization
+Review and optimize the control strategies of the HVAC system by:
+- Adjusting setpoints.
+- Improving system responsiveness to temperature changes.
+
+### 6. Monitoring and Data Analysis
+Continue monitoring temperature data to identify patterns or recurring issues, which can inform necessary adjustments or upgrades.
+
+## Additional Considerations
+
+1. **Aging Components**: 
+   - If the HVAC components are over 3 years old or not maintained in over 1 year, consider increasing the temperature deviation threshold to **4°C** to account for potential variability due to aging.
+2. **Problem Escalation**:
+   - If deviations exceeding the adjusted thresholds are identified:
+     - Report a **Temperature Control Problem**.
+     - Recommend inspecting and replacing aging components.
+     - Verify sensor calibration.
+     - Perform a system audit for inefficiencies or leaks.
+
+By following these recommendations, the HVAC system's performance can be optimized, ensuring a stable and comfortable environment.

examples/hvac-data-monitoring/ans2.md

@@ -0,0 +1,66 @@
+# Occupancy Issues Analysis and Recommendations
+
+To identify any occupancy issues from the data and recommend appropriate actions, we need to analyze the occupancy readings and their impact on HVAC energy usage. Here's a synthesis of the findings and recommendations:
+
+## Identified Occupancy Issue
+
+### Constant Occupancy Readings
+The data shows that occupancy levels remain constant at **5 individuals** across all recorded timestamps. This consistency suggests a potential issue with the accuracy of occupancy reporting, which could lead to inefficiencies in HVAC energy usage and indoor air quality management.
+
+---
+
+## Analysis
+
+### 1. Energy Usage Discrepancy
+- **Observation**: The HVAC energy usage is consistently recorded at **150 kWh** for each timestamp.
+- **Concern**: This steady energy consumption, despite constant occupancy readings, indicates that the system may not dynamically adjust its operation based on actual occupancy levels.
+- **Impact**: Assuming a typical baseline energy usage for low-occupancy periods is **125 kWh**, the recorded usage exceeds this by **20%**, suggesting inefficiency.
+
+### 2. Sensor Anomalies
+- The constant occupancy readings suggest potential anomalies or misconfigurations in the occupancy sensor.
+- Possible causes include:
+  - Sensor malfunction.
+  - Improper sensor placement.
+  - Lack of calibration, leading to inaccurate occupancy data.
+
+### 3. Environmental Impact
+- **CO2 Levels**: The CO2 levels are on the higher side, particularly at **1600 ppm**, indicating inadequate ventilation for the number of occupants.
+- **Concern**: This suggests that the HVAC system may not be effectively managing air quality in relation to occupancy.
+
+---
+
+## Recommendations
+
+### 1. Implement Real-Time Occupancy Monitoring
+- Utilize advanced sensors such as **motion detectors** or **video analytics** to capture real-time occupancy data.
+- Enable the HVAC system to adjust its operations dynamically based on actual occupancy levels.
+
+### 2. Adjust HVAC Control Schedules
+- Review and modify HVAC control schedules to reflect actual occupancy patterns.
+- Focus on:
+  - Reducing energy usage during low occupancy.
+  - Increasing efficiency during peak times.
+
+### 3. Inspect and Recalibrate Occupancy Sensors
+- Conduct a thorough inspection of the occupancy sensors to ensure correct functionality.
+- Recalibrate the sensors if necessary to improve their accuracy in detecting actual occupancy levels.
+
+### 4. Enhance Ventilation Strategies
+- For high occupancy levels:
+  - Increase the frequency of **air exchanges**.
+  - Utilize **air purifiers** to manage CO2 levels effectively and improve indoor air quality.
+
+### 5. Investigate System Inefficiencies
+- Perform a comprehensive assessment of the HVAC system to identify any **leaks or inefficiencies**.
+- Addressing these issues can enhance overall performance and reduce unnecessary energy consumption.
+
+---
+
+## Conclusion
+
+By implementing these strategies, it is possible to:
+- Optimize HVAC performance.
+- Improve energy efficiency.
+- Enhance indoor air quality based on actual occupancy levels.
+
+These actions will ensure that the HVAC system operates efficiently, providing a comfortable and healthy environment for occupants.

examples/hvac-data-monitoring/ans3.md

@@ -0,0 +1,63 @@
+# CO and CO2 Data Analysis and Recommended Actions
+
+To analyze the CO and CO2 data and identify any cleaning needs, we evaluate the recorded levels and determine if they exceed safe thresholds, which would indicate a need for action.
+
+
+## CO Levels Analysis
+
+- **Recorded CO Levels**: 5.0, 9.5, 10.0, 10.5, 10.0, and 9.5 ppm.
+- **Key Observations**:
+  - CO levels exceed the **9 ppm threshold** starting from the second measurement and continue through the fifth.
+  - This indicates unsafe levels for more than **3 consecutive hours**.
+- **Impact**:
+  - According to HVAC sensor monitoring rules, CO levels exceeding 9 ppm require:
+    - **Alerting safety personnel**.
+    - **Inspecting HVAC systems** for possible leaks.
+  - This suggests a need for **immediate inspection** and potential cleaning or repair of the HVAC system to address leaks or malfunctions.
+
+
+## CO2 Levels Analysis
+
+- **Recorded CO2 Levels**: 1450, 1500, 1550, 1600, 1550, and 1500 ppm.
+- **Key Observations**:
+  - CO2 levels exceed the **1500 ppm threshold** at the third and fourth measurements.
+  - However, levels do not remain elevated for more than **3 consecutive hours**.
+- **Impact**:
+  - While immediate action is not required based on duration, reaching **1600 ppm** suggests that **ventilation rates** may need to be increased to prevent future exceedances.
+
+
+## Cross-Checking with Ventilation System Data
+
+- **Ventilation System Performance**:
+  - Temperature readings are stable.
+  - Occupancy levels remain constant.
+  - This indicates that the system should be capable of maintaining adequate air exchange rates.
+- **Key Concern**:
+  - Elevated CO2 levels suggest that current ventilation may not be sufficient, and **adjustments to increase airflow** could be necessary.
+
+
+## External Factors
+
+- **Potential External Influences**:
+  - Nearby combustion sources or adverse weather conditions could contribute to elevated CO and CO2 levels.
+  - Investigating these factors may help identify additional cleaning or maintenance needs.
+
+
+## Recommended Actions
+
+1. **Increase Ventilation Rates**:
+   - Immediately increase ventilation rates to dilute CO and CO2 concentrations.
+
+2. **Inspect HVAC System**:
+   - Conduct a thorough inspection for leaks or malfunctions, particularly in **combustion systems**, to address elevated CO levels.
+
+3. **Alert Safety Personnel**:
+   - Notify safety personnel and consider evacuation if CO levels remain elevated despite increased ventilation.
+
+4. **Enhance Monitoring**:
+   - Continue monitoring CO and CO2 levels to assess the effectiveness of these measures and identify recurring issues.
+
+
+## Conclusion
+
+The analysis indicates a **need for immediate inspection** and potential cleaning of the HVAC system to address elevated CO levels. Additionally, **increasing ventilation rates** is recommended to manage CO2 levels and ensure a safe indoor environment.

examples/hvac-data-monitoring/dana.py

@@ -0,0 +1,65 @@
+from argparse import ArgumentParser
+from functools import cache
+from pathlib import Path
+
+from dotenv import load_dotenv
+import yaml
+
+from openssa import DANA, ProgramStore, HTP, HTPlanner, FileResource, HuggingFaceLM
+
+# pylint: disable=wrong-import-order
+from semikong_lm import SemiKongLM
+
+
+load_dotenv()
+
+
+BASE_DIR: Path = Path(__file__).parent
+
+DATA_DIR_PATH: Path = BASE_DIR / 'data'
+
+EXPERTISE_DIR_PATH: Path = BASE_DIR / 'expertise'
+
+EXPERT_KNOWLEDGE_FILE_PATH: Path = EXPERTISE_DIR_PATH / 'expert-knowledge.txt'
+with open(file=EXPERT_KNOWLEDGE_FILE_PATH,
+          buffering=-1,
+          encoding='utf-8',
+          errors='strict',
+          newline=None,
+          closefd=True,
+          opener=None) as f:
+    EXPERT_KNOWLEDGE: str = f.read()
+
+EXPERT_PROGRAMS_FILE_PATH: Path = EXPERTISE_DIR_PATH / 'expert-programs.yml'
+with open(file=EXPERT_PROGRAMS_FILE_PATH,
+          buffering=-1,
+          encoding='utf-8',
+          errors='strict',
+          newline=None,
+          closefd=True,
+          opener=None) as f:
+    EXPERT_PROGRAMS: dict[str, dict] = yaml.safe_load(stream=f)
+
+
+@cache
+def get_or_create_dana(use_semikong_lm: bool = True, max_depth=2, max_subtasks_per_decomp=4) -> DANA:
+    lm = (SemiKongLM if use_semikong_lm else HuggingFaceLM).from_defaults()
+
+    program_store = ProgramStore(lm=lm)
+    if EXPERT_PROGRAMS:
+        for program_name, htp_dict in EXPERT_PROGRAMS.items():
+            htp = HTP.from_dict(htp_dict)
+            program_store.add_or_update_program(name=program_name, description=htp.task.ask, program=htp)
+
+    return DANA(knowledge={EXPERT_KNOWLEDGE},
+                program_store=program_store,
+                programmer=HTPlanner(lm=lm, max_depth=max_depth, max_subtasks_per_decomp=max_subtasks_per_decomp),
+                resources={FileResource(path=DATA_DIR_PATH, re_index=True)})
+
+
+if __name__ == '__main__':
+    arg_parser = ArgumentParser()
+    arg_parser.add_argument('problem')
+    args = arg_parser.parse_args()
+
+    print(get_or_create_dana().solve(problem=args.problem))

examples/hvac-data-monitoring/data/expert-programs.yml

@@ -0,0 +1,77 @@
+hvac-temperature-monitoring:
+  task: |-
+    Monitor HVAC temperature deviations and recommend inspection/maintenance actions if deviations exceed thresholds.
+
+  sub-htps:
+    - task: >-
+        What are the recorded temperature values in the recent data?
+
+    - task: |-
+        Analyze whether the temperature deviates by more than 3°C from the setpoint for over 3 consecutive hours.
+        If so, note down the time periods and the corresponding deviation values.
+
+    - task: >-
+        What are the last maintenance dates and the ages of critical system components (e.g., filters, fans, ducts)?
+
+    - task: |-
+        Adjust the sensitivity of the temperature deviation threshold:
+        - For components less than 1 year old or maintained within the last 6 months, keep the threshold at 3°C.
+        - For components over 3 years old or not maintained in over 1 year, increase the threshold to 4°C.
+
+    - task: |-
+        If deviations exceeding the adjusted thresholds are identified, report a Temperature Control Problem,
+        and recommend the following maintenance actions:
+        - Inspect and replace aging components.
+        - Verify calibration of temperature sensors.
+        - Perform a system audit for inefficiencies or leaks.
+
+
+hvac-occupancy-sensor-monitoring:
+  task: |-
+    Monitor HVAC occupancy data and energy usage patterns to recommend adjustments or inspections if discrepancies are detected.
+
+  sub-htps:
+    - task: >-
+        What are the occupancy readings and corresponding HVAC energy usage values in the recent data?
+
+    - task: |-
+        Analyze whether HVAC energy usage exceeds typical levels for low-occupancy periods by more than 20%.
+        If so, note the time periods and energy discrepancies.
+
+    - task: >-
+        Check if the HVAC system is operating according to the programmed schedules and occupancy conditions.
+
+    - task: |-
+        Identify any sensor anomalies or misconfigurations that might cause false occupancy readings.
+
+    - task: |-
+        If discrepancies between occupancy and energy usage are found, recommend the following actions:
+        - Adjust HVAC control schedules for efficiency.
+        - Inspect and recalibrate occupancy sensors.
+        - Investigate potential system leaks or inefficiencies.
+
+
+
+hvac-co-co2-sensor-monitoring:
+  task: |-
+    Monitor CO and CO2 levels in indoor air and recommend actions if levels exceed safe thresholds.
+
+  sub-htps:
+    - task: >-
+        What are the recorded CO and CO2 levels in the recent data?
+
+    - task: |-
+        Analyze whether CO levels exceed 9 ppm or CO2 levels exceed 1500 ppm for more than 3 consecutive hours.
+        If so, note the time periods and recorded values.
+
+    - task: |-
+        Cross-check with ventilation system data to ensure proper air exchange rates are maintained.
+
+    - task: |-
+        Identify whether external factors (e.g., weather conditions, nearby combustion sources) might be contributing to the elevated levels.
+
+    - task: |-
+        If unsafe CO or CO2 levels are detected, recommend the following actions:
+        - Increase ventilation rates immediately.
+        - Inspect for leaks in HVAC or combustion systems.
+        - Alert safety personnel and consider evacuation if CO levels remain elevated.

examples/hvac-data-monitoring/data/measurement-data-old.txt

@@ -0,0 +1,11 @@
+WaterBatch: 1, 2, 3, 4, 5, 6
+
+ReflectedPower_W: 36.6, 35.4, 37.5, 40.1, 42.3, 37.9
+
+ForwardPower_W: 60.0, 58.0, 58.2, 57.8, 65.3, 60.0
+
+ChamberPressure_Torr: 3.89, 4.18, 3.85, 4.22, 4.25, 3.53
+
+GasFlowRate_sccm: 59.7, 58.1, 56.2, 55.1, 59.7, 54.4
+
+ChamberWallTemperature_C: 76.3, 78.3, 76.6, 79.6, 81.7, 81.9

examples/hvac-data-monitoring/data/measurement-data.txt

@@ -0,0 +1,11 @@
+Timestamp: 1, 2, 3, 4, 5, 6
+
+Temperature (°C): 20.0, 19.5, 19.0, 19.2, 18.8, 18.5
+
+Occupancy: 5, 5, 5, 5, 5, 5
+
+HVAC Energy Usage (kWh): 150, 150, 150, 150, 150, 150
+
+CO Levels (ppm): 5.0, 9.5, 10.0, 10.5, 10.0, 9.5
+
+CO2 Levels (ppm): 1450, 1500, 1550, 1600, 1550, 1500