Update utils/psychrometrics.py

utils/psychrometrics.py

@@ -1,6 +1,7 @@
 """
 Psychrometric module for HVAC Load Calculator.
 This module implements psychrometric calculations for air properties.
+Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1.
 """
 
 from typing import Dict, List, Any, Optional, Tuple
@@ -19,10 +20,31 @@ GAS_CONSTANT_WATER_VAPOR = UNIVERSAL_GAS_CONSTANT / WATER_MOLECULAR_WEIGHT  # J/
 class Psychrometrics:
     """Class for psychrometric calculations."""
     
+    @staticmethod
+    def validate_inputs(t_db: float, rh: Optional[float] = None, p_atm: Optional[float] = None) -> None:
+        """
+        Validate input parameters for psychrometric calculations.
+        
+        Args:
+            t_db: Dry-bulb temperature in °C
+            rh: Relative humidity in % (0-100), optional
+            p_atm: Atmospheric pressure in Pa, optional
+            
+        Raises:
+            ValueError: If inputs are invalid
+        """
+        if not -50 <= t_db <= 60:
+            raise ValueError(f"Temperature {t_db}°C must be between -50°C and 60°C")
+        if rh is not None and not 0 <= rh <= 100:
+            raise ValueError(f"Relative humidity {rh}% must be between 0 and 100%")
+        if p_atm is not None and p_atm <= 0:
+            raise ValueError(f"Atmospheric pressure {p_atm} Pa must be positive")
+
     @staticmethod
     def saturation_pressure(t_db: float) -> float:
         """
         Calculate saturation pressure of water vapor.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Equations 5 and 6.
         
         Args:
             t_db: Dry-bulb temperature in °C
@@ -30,6 +52,8 @@ class Psychrometrics:
         Returns:
             Saturation pressure in Pa
         """
+        Psychrometrics.validate_inputs(t_db)
+        
         # Convert temperature to Kelvin
         t_k = t_db + 273.15
         
@@ -67,6 +91,7 @@ class Psychrometrics:
     def humidity_ratio(t_db: float, rh: float, p_atm: float = ATMOSPHERIC_PRESSURE) -> float:
         """
         Calculate humidity ratio (mass of water vapor per unit mass of dry air).
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Equation 20.
         
         Args:
             t_db: Dry-bulb temperature in °C
@@ -76,6 +101,8 @@ class Psychrometrics:
         Returns:
             Humidity ratio in kg water vapor / kg dry air
         """
+        Psychrometrics.validate_inputs(t_db, rh, p_atm)
+        
         # Convert relative humidity to decimal
         rh_decimal = rh / 100.0
         
@@ -85,8 +112,10 @@ class Psychrometrics:
         # Calculate partial pressure of water vapor
         p_w = rh_decimal * p_ws
         
+        if p_w >= p_atm:
+            raise ValueError("Partial pressure of water vapor exceeds atmospheric pressure")
+        
         # Calculate humidity ratio
-        # ASHRAE Fundamentals 2017 Chapter 1, Equation 20
         w = 0.621945 * p_w / (p_atm - p_w)
         
         return w
@@ -95,6 +124,7 @@ class Psychrometrics:
     def relative_humidity(t_db: float, w: float, p_atm: float = ATMOSPHERIC_PRESSURE) -> float:
         """
         Calculate relative humidity from humidity ratio.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Equation 20 (rearranged).
         
         Args:
             t_db: Dry-bulb temperature in °C
@@ -104,11 +134,14 @@ class Psychrometrics:
         Returns:
             Relative humidity (0-100)
         """
+        Psychrometrics.validate_inputs(t_db, p_atm=p_atm)
+        if w < 0:
+            raise ValueError("Humidity ratio cannot be negative")
+        
         # Calculate saturation pressure
         p_ws = Psychrometrics.saturation_pressure(t_db)
         
         # Calculate partial pressure of water vapor
-        # Rearranged from ASHRAE Fundamentals 2017 Chapter 1, Equation 20
         p_w = p_atm * w / (0.621945 + w)
         
         # Calculate relative humidity
@@ -120,6 +153,7 @@ class Psychrometrics:
     def wet_bulb_temperature(t_db: float, rh: float, p_atm: float = ATMOSPHERIC_PRESSURE) -> float:
         """
         Calculate wet-bulb temperature using iterative method.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Equation 35.
         
         Args:
             t_db: Dry-bulb temperature in °C
@@ -129,6 +163,8 @@ class Psychrometrics:
         Returns:
             Wet-bulb temperature in °C
         """
+        Psychrometrics.validate_inputs(t_db, rh, p_atm)
+        
         # Calculate humidity ratio at given conditions
         w = Psychrometrics.humidity_ratio(t_db, rh, p_atm)
         
@@ -140,6 +176,9 @@ class Psychrometrics:
         tolerance = 0.001  # °C
         
         for i in range(max_iterations):
+            # Validate wet-bulb temperature
+            Psychrometrics.validate_inputs(t_wb)
+            
             # Calculate saturation pressure at wet-bulb temperature
             p_ws_wb = Psychrometrics.saturation_pressure(t_wb)
             
@@ -147,7 +186,6 @@ class Psychrometrics:
             w_s_wb = 0.621945 * p_ws_wb / (p_atm - p_ws_wb)
             
             # Calculate humidity ratio from wet-bulb temperature
-            # ASHRAE Fundamentals 2017 Chapter 1, Equation 35
             h_fg = 2501000 + 1840 * t_wb  # Latent heat of vaporization at t_wb in J/kg
             c_pa = 1006  # Specific heat of dry air in J/(kg·K)
             c_pw = 1860  # Specific heat of water vapor in J/(kg·K)
@@ -170,6 +208,7 @@ class Psychrometrics:
     def dew_point_temperature(t_db: float, rh: float) -> float:
         """
         Calculate dew point temperature.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Equations 39 and 40.
         
         Args:
             t_db: Dry-bulb temperature in °C
@@ -178,6 +217,8 @@ class Psychrometrics:
         Returns:
             Dew point temperature in °C
         """
+        Psychrometrics.validate_inputs(t_db, rh)
+        
         # Convert relative humidity to decimal
         rh_decimal = rh / 100.0
         
@@ -188,7 +229,6 @@ class Psychrometrics:
         p_w = rh_decimal * p_ws
         
         # Calculate dew point temperature
-        # ASHRAE Fundamentals 2017 Chapter 1, Equation 39 and 40
         alpha = math.log(p_w / 1000.0)  # Convert to kPa for the formula
         
         if t_db >= 0:
@@ -214,6 +254,7 @@ class Psychrometrics:
     def enthalpy(t_db: float, w: float) -> float:
         """
         Calculate specific enthalpy of moist air.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Equation 30.
         
         Args:
             t_db: Dry-bulb temperature in °C
@@ -222,7 +263,10 @@ class Psychrometrics:
         Returns:
             Specific enthalpy in J/kg dry air
         """
-        # ASHRAE Fundamentals 2017 Chapter 1, Equation 30
+        Psychrometrics.validate_inputs(t_db)
+        if w < 0:
+            raise ValueError("Humidity ratio cannot be negative")
+        
         c_pa = 1006  # Specific heat of dry air in J/(kg·K)
         h_fg = 2501000  # Latent heat of vaporization at 0°C in J/kg
         c_pw = 1860  # Specific heat of water vapor in J/(kg·K)
@@ -235,6 +279,7 @@ class Psychrometrics:
     def specific_volume(t_db: float, w: float, p_atm: float = ATMOSPHERIC_PRESSURE) -> float:
         """
         Calculate specific volume of moist air.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Equation 28.
         
         Args:
             t_db: Dry-bulb temperature in °C
@@ -244,10 +289,13 @@ class Psychrometrics:
         Returns:
             Specific volume in m³/kg dry air
         """
+        Psychrometrics.validate_inputs(t_db, p_atm=p_atm)
+        if w < 0:
+            raise ValueError("Humidity ratio cannot be negative")
+        
         # Convert temperature to Kelvin
         t_k = t_db + 273.15
         
-        # ASHRAE Fundamentals 2017 Chapter 1, Equation 28
         r_da = GAS_CONSTANT_DRY_AIR  # Gas constant for dry air in J/(kg·K)
         
         v = r_da * t_k * (1 + 1.607858 * w) / p_atm
@@ -258,6 +306,7 @@ class Psychrometrics:
     def density(t_db: float, w: float, p_atm: float = ATMOSPHERIC_PRESSURE) -> float:
         """
         Calculate density of moist air.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, derived from Equation 28.
         
         Args:
             t_db: Dry-bulb temperature in °C
@@ -267,6 +316,10 @@ class Psychrometrics:
         Returns:
             Density in kg/m³
         """
+        Psychrometrics.validate_inputs(t_db, p_atm=p_atm)
+        if w < 0:
+            raise ValueError("Humidity ratio cannot be negative")
+        
         # Calculate specific volume
         v = Psychrometrics.specific_volume(t_db, w, p_atm)
         
@@ -279,6 +332,7 @@ class Psychrometrics:
     def moist_air_properties(t_db: float, rh: float, p_atm: float = ATMOSPHERIC_PRESSURE) -> Dict[str, float]:
         """
         Calculate all psychrometric properties of moist air.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1.
         
         Args:
             t_db: Dry-bulb temperature in °C
@@ -288,6 +342,8 @@ class Psychrometrics:
         Returns:
             Dictionary with all psychrometric properties
         """
+        Psychrometrics.validate_inputs(t_db, rh, p_atm)
+        
         # Calculate humidity ratio
         w = Psychrometrics.humidity_ratio(t_db, rh, p_atm)
         
@@ -331,6 +387,7 @@ class Psychrometrics:
     def find_humidity_ratio_for_enthalpy(t_db: float, h: float) -> float:
         """
         Find humidity ratio for a given dry-bulb temperature and enthalpy.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Equation 30 (rearranged).
         
         Args:
             t_db: Dry-bulb temperature in °C
@@ -339,19 +396,23 @@ class Psychrometrics:
         Returns:
             Humidity ratio in kg water vapor / kg dry air
         """
-        # Rearrange ASHRAE Fundamentals 2017 Chapter 1, Equation 30
+        Psychrometrics.validate_inputs(t_db)
+        if h < 0:
+            raise ValueError("Enthalpy cannot be negative")
+        
         c_pa = 1006  # Specific heat of dry air in J/(kg·K)
         h_fg = 2501000  # Latent heat of vaporization at 0°C in J/kg
         c_pw = 1860  # Specific heat of water vapor in J/(kg·K)
         
         w = (h - c_pa * t_db) / (h_fg + c_pw * t_db)
         
-        return max(0, w)  # Ensure non-negative value
+        return max(0, w)
     
     @staticmethod
     def find_temperature_for_enthalpy(w: float, h: float) -> float:
         """
         Find dry-bulb temperature for a given humidity ratio and enthalpy.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Equation 30 (rearranged).
         
         Args:
             w: Humidity ratio in kg water vapor / kg dry air
@@ -360,19 +421,25 @@ class Psychrometrics:
         Returns:
             Dry-bulb temperature in °C
         """
-        # Rearrange ASHRAE Fundamentals 2017 Chapter 1, Equation 30
+        if w < 0:
+            raise ValueError("Humidity ratio cannot be negative")
+        if h < 0:
+            raise ValueError("Enthalpy cannot be negative")
+        
         c_pa = 1006  # Specific heat of dry air in J/(kg·K)
         h_fg = 2501000  # Latent heat of vaporization at 0°C in J/kg
         c_pw = 1860  # Specific heat of water vapor in J/(kg·K)
         
         t_db = (h - w * h_fg) / (c_pa + w * c_pw)
         
+        Psychrometrics.validate_inputs(t_db)
         return t_db
     
     @staticmethod
     def sensible_heat_ratio(q_sensible: float, q_total: float) -> float:
         """
         Calculate sensible heat ratio.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Section 1.5.
         
         Args:
             q_sensible: Sensible heat load in W
@@ -383,6 +450,8 @@ class Psychrometrics:
         """
         if q_total == 0:
             return 1.0
+        if q_sensible < 0 or q_total < 0:
+            raise ValueError("Heat loads cannot be negative")
         
         return q_sensible / q_total
     
@@ -391,6 +460,7 @@ class Psychrometrics:
                               rh_return: float = 50.0, p_atm: float = ATMOSPHERIC_PRESSURE) -> Dict[str, float]:
         """
         Calculate required air flow rate for a given sensible load.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Section 1.6.
         
         Args:
             q_sensible: Sensible heat load in W
@@ -402,6 +472,9 @@ class Psychrometrics:
         Returns:
             Dictionary with air flow rate in different units
         """
+        Psychrometrics.validate_inputs(t_return, rh_return, p_atm)
+        Psychrometrics.validate_inputs(t_supply)
+        
         # Calculate return air properties
         w_return = Psychrometrics.humidity_ratio(t_return, rh_return, p_atm)
         rho_return = Psychrometrics.density(t_return, w_return, p_atm)
@@ -441,6 +514,7 @@ class Psychrometrics:
                              p_atm: float = ATMOSPHERIC_PRESSURE) -> Dict[str, float]:
         """
         Calculate properties of mixed airstreams.
+        Reference: ASHRAE Handbook—Fundamentals (2017), Chapter 1, Section 1.7.
         
         Args:
             m1: Mass flow rate of airstream 1 in kg/s
@@ -454,6 +528,11 @@ class Psychrometrics:
         Returns:
             Dictionary with mixed air properties
         """
+        Psychrometrics.validate_inputs(t_db1, rh1, p_atm)
+        Psychrometrics.validate_inputs(t_db2, rh2, p_atm)
+        if m1 < 0 or m2 < 0:
+            raise ValueError("Mass flow rates cannot be negative")
+        
         # Calculate humidity ratios
         w1 = Psychrometrics.humidity_ratio(t_db1, rh1, p_atm)
         w2 = Psychrometrics.humidity_ratio(t_db2, rh2, p_atm)
@@ -499,4 +578,4 @@ if __name__ == "__main__":
     print(f"Specific volume: {properties['specific_volume']:.4f} m³/kg")
     print(f"Density: {properties['density']:.4f} kg/m³")
     print(f"Saturation pressure: {properties['saturation_pressure']/1000:.2f} kPa")
-    print(f"Partial pressure: {properties['partial_pressure']/1000:.2f} kPa")
+    print(f"Partial pressure: {properties['partial_pressure']/1000:.2f} kPa")