Merge pull request #29 from pnnl/add_verif_docstrings

Add missing docstrings

constrain/library/AppendixGHVACSystemFanOperation.py

@@ -1,3 +1,63 @@
+"""
+ASHRAE 90.1-2022 
+### Description
+
+Section G3.1.4 HVAC System Fan Schedules
+
+- Schedules for HVAC system fans that provide outdoor air for ventilation shall run continuously whenever spaces are occupied and shall be cycled ON and OFF to meet heating and cooling loads during unoccupied hours.
+
+Note: exceptions to this requirement are not capture since they depend on system design which is not related to system control.
+
+Verification Item:
+
+- Check that when a zone is occupied and served by a system that provides outdoor air the system runs continuously and cycles when the zone is occupied.
+
+### Verification logic
+
+In the following pseudo code `None` means that the verification is not verifiable, `True` means that it is verifiable and that the verification passes, and `False` that it fails.
+
+```
+# Check that the system provide OA
+# This is a one-time check, do not perform further checks if None is returned
+If sum(m_oa) == 0
+  return None
+Endif
+
+# This assume that the system does provide OA to the space as per the first check
+potential_failures_count = 0
+potential_pass_count = 0
+If o
+  If fan_runtime_fraction == 1
+    return True
+  Else
+    return False
+  Endif
+Else
+  If fan_runtime_fraction == 1 # the system could be "cycling" for the whole timestep so add to counter
+    potential_failures_count += 1
+    return None
+  Else
+    potential_pass_count += 1
+    return None
+  Endif
+Endif
+
+# Check that if the system has been cycling for a whole timestep it also cycles during some
+# If it hasn't we assume that the system is set to run continuously when the zone is unoccupied
+# This is a one-time check, it can be used to make a final pass/fail decision
+If potential_failures_count > 0 and potential_pass_count == 0
+  return False
+Endif
+```
+
+### Data requirements
+- o: number of occupants sensed in the zones served by the system.
+- fan_runtime_fraction: system fan runtime fraction (between 0 and 1).
+- m_oa: system outdoor air flow rate.
+- tol_o: occupancy threshold; below that value the zones are considered unoccupied.
+
+"""
+
 from constrain.checklib import RuleCheckBase
 
 

constrain/library/ExteriorLightingControlDaylightOff.py

@@ -1,3 +1,40 @@
+"""
+ASHRAE 90.1-2022 
+### Description
+
+Section 9.4.1.4.b Daylight OFF control
+
+- [Exterior] Lighting shall automatically turn off when sufficient daylight is available or within 30 minutes of sunrise.
+
+Verification Item:
+
+- Check if the lighting power is turned off when enough daylight is available.
+
+### Verification logic
+
+```
+daylight_setpoint_met = data["daylight_sensed"] / data["daylight_setpoint"]
+
+
+If daylight_setpoint_met >= 1 or time_since_last_sun_up >= 30: # min
+    If total_lighting_power == 0:
+        Pass
+    Else
+        Fail
+    Endif
+Else
+    Untested
+Endif
+```
+
+### Data requirements
+- is_sun_up: flag indicating whether the sun is up; data can be either a boolean (True or False), or numeric boolean (0 or 1)
+- daylight_sensed: Amount of daylight sensed by a photocell type sensor; unit should be consistent with `daylight_setpoint`
+- daylight_setpoint: Setpoint or threshold below which daylight is not sufficient and exterior lighting is required
+- total_lighting_power: reported total lighting power (not the design total lighting power)
+
+"""
+
 from constrain.checklib import RuleCheckBase
 import numpy as np
 

constrain/library/ExteriorLightingControlOccupancySensingReduction.py

@@ -1,3 +1,39 @@
+"""
+ASHRAE 90.1-2022 
+### Description
+
+Section 9.4.1.4.e Occupancy-sensing light reduction control
+
+- Occupancy-sensing light reduction control: Lighting shall be controlled to automatically reduce the connected lighting power by a minimum of 50% when no activity has been detected in the area illuminated by the controlled luminaires for a time of no longer than 15 minutes. No more than 1500 W of lighting power shall be controlled together.
+
+Verification Item:
+
+- Check if the lighting power is reduced when no occupancy is detected.
+
+### Verification logic
+
+```
+design_total_lighting_power = max(total_lighting_power)
+
+date_diff = current_date - last_reported_occupancy # in min
+If o < tol_o and date_diff > 15
+    If total_lighting_power <= 0.5 * design_total_lighting_power
+        Pass
+    Else
+        Fail
+    Endif
+Else
+    Untested
+Endif
+```
+
+### Data requirements
+- o: number of occupants sensed in the zones served by the system.
+- total_lighting_power: reported total lighting power (not the design total lighting power)
+- tol_o: occupancy threshold; below that value the zones are considered unoccupied.
+
+"""
+
 from constrain.checklib import RuleCheckBase
 import numpy as np
 

constrain/library/InteriorLightingControlAutomaticFullOff.py

@@ -1,3 +1,47 @@
+"""
+ASHRAE 90.1-2022 
+### Description
+
+Section 9.4.1.1.h Automatic full OFF control
+
+- All lighting in the space, including lighting connected to emergency circuits,shall be automatically shut off within 20 minutes of all occupants leaving the space. A control device meeting this requirement shall control no more than 5000 ft2.
+- Exceptions:
+  - The following lighting is not required to be automatically shut off:
+    1. Lighting required for 24/7 continuous operation.
+    2. Lighting in spaces where patient care is rendered.
+    3. General lighting and task lighting in spaces where automatic shutoff would endanger the safety or security of the room or building occupants.
+    4. Lighting load not exceeding 0.02 W/ft2 multiplied by the gross lighted floor area of the building.
+
+Verification Item:
+
+- Check if the lighting power is reduced when no occupancy is detected.
+
+### Verification logic
+
+```
+If lighted_floor_area >= 5000:
+    return False
+
+date_diff = current_date - last_reported_occupancy # in min
+If o < tol_o and date_diff > 20
+    If total_lighting_power / lighted_floor_area <= 0.02
+        Pass
+    Else
+        Fail
+    Endif
+Else
+    Untested
+Endif
+```
+
+### Data requirements
+- o: number of occupants sensed in the zones served by the system.
+- total_lighting_power: reported total lighting power (not the design total lighting power)
+- lighted_floor_area: area lit by the device/system considered
+- tol_o: occupancy threshold; below that value the zones are considered unoccupied.
+
+"""
+
 from constrain.checklib import RuleCheckBase
 import numpy as np
 

constrain/library/MZSystemOccupiedStandbyVentilationZoneControl.py

@@ -1,3 +1,39 @@
+"""
+ASHRAE 90.1-2022
+### Description
+
+Section 6.5.3.9.1 Occupied-Standby Control of Multiple-Zone Systems
+
+- Multi-zone systems with ventilation optimization shall reset their outdoor air setpoint assuming that all zones in standby mode don't require any outdoor air.
+
+Verification Item:
+
+- Check that the requested outdoor air flow rate setpoint is at least reduced by the amount of outdoor air that would be required for the zone in standby mode.
+
+### Verification logic
+
+In the following pseudo code `None` means that the verification is not verifiable, `True` means that it is verifiable and that the verification passes, and `False` that it fails.
+
+```
+If (zone_is_standby_mode)
+  If (m_oa_requested_system[t_last_standby] - m_oa_requested_system[t]) >= m_oa_zone_requirement
+    return True
+  Else
+    return False
+  Endif
+  t_last_standby = t
+Else
+  return None
+Endif
+```
+
+### Data requirements
+- zone_is_standby_mode: flag indicating whether the zone is in 'active' occupied standby mode; data can be either a boolean (True or False), or numeric boolean (0 or 1)
+- m_oa_requested_by_system: system outdoor air setpoint, i.e., outdoor air required by the system for the reported period
+- m_oa_zone_requirement: required zone outdoor air flow rate for the reported period
+
+"""
+
 from constrain.checklib import RuleCheckBase
 import numpy as np