Update utils/heat_transfer.py

utils/heat_transfer.py

@@ -1,548 +1,500 @@
 """
-Shared calculation functions module for HVAC Load Calculator.
-This module implements common heat transfer calculations used in both cooling and heating load calculations.
+Heat transfer calculation module for HVAC Load Calculator.
+This module provides enhanced calculations for conduction, convection, radiation,
+infiltration, and solar geometry, with improved modularity and error handling.
 """
 
-from typing import Dict, List, Any, Optional, Tuple
+from typing import Optional, Tuple
 import math
 import numpy as np
-import pandas as pd
-import os
 
-# Import data models and utilities
-from data.building_components import Wall, Roof, Floor, Window, Door, Orientation
-from utils.psychrometrics import Psychrometrics
 
-# Define constants
-STEFAN_BOLTZMANN_CONSTANT = 5.67e-8  # W/(m²·K⁴)
-SOLAR_CONSTANT = 1367  # W/m²
-EARTH_TILT_ANGLE = 23.45  # degrees
-
-
-class HeatTransferCalculations:
-    """Class for shared heat transfer calculations."""
+class SolarCalculations:
+    """Class for solar geometry and irradiance calculations."""
     
-    @staticmethod
-    def conduction_heat_transfer(u_value: float, area: float, delta_t: float) -> float:
-        """
-        Calculate conduction heat transfer through a building component.
-        
-        Args:
-            u_value: U-value of the component in W/(m²·K)
-            area: Area of the component in m²
-            delta_t: Temperature difference across the component in K (or °C)
-            
-        Returns:
-            Heat transfer rate in W
-        """
-        return u_value * area * delta_t
+    def __init__(self):
+        """Initialize solar calculations with cached values."""
+        self._declination_cache = {}  # Cache for declination by day of year
     
-    @staticmethod
-    def convection_heat_transfer(h_c: float, area: float, delta_t: float) -> float:
+    def validate_angle(self, angle: float, name: str, min_val: float, max_val: float) -> None:
         """
-        Calculate convection heat transfer.
+        Validate an angle input.
         
         Args:
-            h_c: Convection heat transfer coefficient in W/(m²·K)
-            area: Surface area in m²
-            delta_t: Temperature difference between surface and fluid in K (or °C)
+            angle: Angle in degrees
+            name: Name of the angle for error messages
+            min_val: Minimum allowed value
+            max_val: Maximum allowed value
             
-        Returns:
-            Heat transfer rate in W
+        Raises:
+            ValueError: If angle is out of range
         """
-        return h_c * area * delta_t
+        if not min_val <= angle <= max_val:
+            raise ValueError(f"{name} {angle}° is outside valid range ({min_val} to {max_val}°)")
     
-    @staticmethod
-    def radiation_heat_transfer(emissivity: float, area: float, t_surface: float, t_surroundings: float) -> float:
+    def solar_declination(self, day_of_year: int) -> float:
         """
-        Calculate radiation heat transfer.
+        Calculate solar declination angle for a given day of the year.
         
         Args:
-            emissivity: Surface emissivity (0-1)
-            area: Surface area in m²
-            t_surface: Surface temperature in K
-            t_surroundings: Surroundings temperature in K
+            day_of_year: Day of the year (1-365)
             
         Returns:
-            Heat transfer rate in W
+            Solar declination angle in degrees
         """
-        return emissivity * STEFAN_BOLTZMANN_CONSTANT * area * (t_surface**4 - t_surroundings**4)
+        if not 1 <= day_of_year <= 365:
+            raise ValueError(f"Day of year {day_of_year} must be between 1 and 365")
+        
+        if day_of_year in self._declination_cache:
+            return self._declination_cache[day_of_year]
+        
+        declination = 23.45 * math.sin(math.radians(360 * (284 + day_of_year) / 365))
+        self._declination_cache[day_of_year] = declination
+        return declination
     
-    @staticmethod
-    def infiltration_heat_transfer(flow_rate: float, delta_t: float, density: float = 1.2, specific_heat: float = 1006) -> float:
+    def solar_hour_angle(self, hour: float) -> float:
         """
-        Calculate sensible heat transfer due to infiltration or ventilation.
+        Calculate solar hour angle for a given hour of the day.
         
         Args:
-            flow_rate: Volumetric flow rate in m³/s
-            delta_t: Temperature difference between indoor and outdoor air in K (or °C)
-            density: Air density in kg/m³ (default: 1.2 kg/m³)
-            specific_heat: Specific heat capacity of air in J/(kg·K) (default: 1006 J/(kg·K))
+            hour: Hour of the day (0-23)
             
         Returns:
-            Heat transfer rate in W
+            Solar hour angle in degrees
         """
-        return flow_rate * density * specific_heat * delta_t
+        if not 0 <= hour <= 23:
+            raise ValueError(f"Hour {hour} must be between 0 and 23")
+        return 15 * (hour - 12)
     
-    @staticmethod
-    def infiltration_latent_heat_transfer(flow_rate: float, delta_w: float, density: float = 1.2, latent_heat: float = 2501000) -> float:
+    def solar_altitude(self, latitude: float, declination: float, hour_angle: float) -> float:
         """
-        Calculate latent heat transfer due to infiltration or ventilation.
+        Calculate solar altitude angle.
         
         Args:
-            flow_rate: Volumetric flow rate in m³/s
-            delta_w: Humidity ratio difference between indoor and outdoor air in kg/kg
-            density: Air density in kg/m³ (default: 1.2 kg/m³)
-            latent_heat: Latent heat of vaporization in J/kg (default: 2501000 J/kg)
+            latitude: Latitude in degrees
+            declination: Solar declination angle in degrees
+            hour_angle: Solar hour angle in degrees
             
         Returns:
-            Heat transfer rate in W
+            Solar altitude angle in degrees
         """
-        return flow_rate * density * latent_heat * delta_w
+        self.validate_angle(latitude, "Latitude", -90, 90)
+        self.validate_angle(declination, "Declination", -90, 90)
+        self.validate_angle(hour_angle, "Hour angle", -180, 180)
+        
+        lat_rad = math.radians(latitude)
+        dec_rad = math.radians(declination)
+        ha_rad = math.radians(hour_angle)
+        
+        sin_alt = math.sin(lat_rad) * math.sin(dec_rad) + math.cos(lat_rad) * math.cos(dec_rad) * math.cos(ha_rad)
+        altitude = math.degrees(math.asin(sin_alt))
+        return max(0, altitude)
     
-    @staticmethod
-    def air_exchange_rate_to_flow_rate(ach: float, volume: float) -> float:
+    def solar_azimuth(self, latitude: float, declination: float, hour_angle: float, altitude: float) -> float:
         """
-        Convert air changes per hour to volumetric flow rate.
+        Calculate solar azimuth angle.
         
         Args:
-            ach: Air changes per hour (1/h)
-            volume: Room or building volume in m³
+            latitude: Latitude in degrees
+            declination: Solar declination angle in degrees
+            hour_angle: Solar hour angle in degrees
+            altitude: Solar altitude angle in degrees
             
         Returns:
-            Volumetric flow rate in m³/s
+            Solar azimuth angle in degrees
         """
-        return ach * volume / 3600
+        self.validate_angle(latitude, "Latitude", -90, 90)
+        self.validate_angle(declination, "Declination", -90, 90)
+        self.validate_angle(hour_angle, "Hour angle", -180, 180)
+        self.validate_angle(altitude, "Altitude", 0, 90)
+        
+        lat_rad = math.radians(latitude)
+        dec_rad = math.radians(declination)
+        ha_rad = math.radians(hour_angle)
+        alt_rad = math.radians(altitude)
+        
+        cos_az = (math.sin(alt_rad) * math.sin(lat_rad) - math.sin(dec_rad)) / (math.cos(alt_rad) * math.cos(lat_rad))
+        cos_az = max(-1, min(1, cos_az))
+        azimuth = math.degrees(math.acos(cos_az))
+        
+        if hour_angle > 0:
+            azimuth = 360 - azimuth
+        return azimuth
     
-    @staticmethod
-    def flow_rate_to_air_exchange_rate(flow_rate: float, volume: float) -> float:
+    def incident_angle(self, surface_tilt: float, surface_azimuth: float, 
+                      solar_altitude: float, solar_azimuth: float) -> float:
         """
-        Convert volumetric flow rate to air changes per hour.
+        Calculate angle of incidence for a surface.
         
         Args:
-            flow_rate: Volumetric flow rate in m³/s
-            volume: Room or building volume in m³
+            surface_tilt: Surface tilt angle in degrees (0=horizontal, 90=vertical)
+            surface_azimuth: Surface azimuth angle in degrees
+            solar_altitude: Solar altitude angle in degrees
+            solar_azimuth: Solar azimuth angle in degrees
             
         Returns:
-            Air changes per hour (1/h)
+            Angle of incidence in degrees
         """
-        return flow_rate * 3600 / volume
+        self.validate_angle(surface_tilt, "Surface tilt", 0, 180)
+        self.validate_angle(surface_azimuth, "Surface azimuth", 0, 360)
+        self.validate_angle(solar_altitude, "Solar altitude", 0, 90)
+        self.validate_angle(solar_azimuth, "Solar azimuth", 0, 360)
+        
+        tilt_rad = math.radians(surface_tilt)
+        az_diff_rad = math.radians(solar_azimuth - surface_azimuth)
+        alt_rad = math.radians(solar_altitude)
+        
+        cos_theta = (math.sin(alt_rad) * math.cos(tilt_rad) +
+                     math.cos(alt_rad) * math.sin(tilt_rad) * math.cos(az_diff_rad))
+        cos_theta = max(0, min(1, cos_theta))
+        return math.degrees(math.acos(cos_theta))
     
-    @staticmethod
-    def crack_method_infiltration(crack_length: float, coefficient: float, pressure_difference: float, exponent: float = 0.65) -> float:
+    def direct_normal_irradiance(self, solar_altitude: float) -> float:
         """
-        Calculate infiltration using the crack method.
+        Calculate direct normal irradiance.
         
         Args:
-            crack_length: Length of cracks in m
-            coefficient: Flow coefficient in m³/(s·m·Pa^n)
-            pressure_difference: Pressure difference in Pa
-            exponent: Flow exponent (default: 0.65)
+            solar_altitude: Solar altitude angle in degrees
             
         Returns:
-            Infiltration flow rate in m³/s
+            Direct normal irradiance in W/m²
         """
-        return coefficient * crack_length * pressure_difference**exponent
+        self.validate_angle(solar_altitude, "Solar altitude", 0, 90)
+        if solar_altitude <= 0:
+            return 0
+        air_mass = 1 / math.cos(math.radians(90 - solar_altitude))
+        dni = 1367 * (1 - 0.14 * air_mass)  # Simplified model
+        return max(0, dni)
     
-    @staticmethod
-    def wind_pressure_difference(wind_speed: float, wind_coefficient: float, density: float = 1.2) -> float:
+    def diffuse_horizontal_irradiance(self, dni: float, solar_altitude: float) -> float:
         """
-        Calculate pressure difference due to wind.
+        Calculate diffuse horizontal irradiance.
         
         Args:
-            wind_speed: Wind speed in m/s
-            wind_coefficient: Wind pressure coefficient (dimensionless)
-            density: Air density in kg/m³ (default: 1.2 kg/m³)
+            dni: Direct normal irradiance in W/m²
+            solar_altitude: Solar altitude angle in degrees
             
         Returns:
-            Pressure difference in Pa
+            Diffuse horizontal irradiance in W/m²
         """
-        return 0.5 * density * wind_speed**2 * wind_coefficient
+        self.validate_angle(solar_altitude, "Solar altitude", 0, 90)
+        if solar_altitude <= 0:
+            return 0
+        return 0.1 * dni  # Simplified model
     
-    @staticmethod
-    def stack_pressure_difference(height: float, indoor_temp: float, outdoor_temp: float, 
-                                 neutral_plane_height: float = None, gravity: float = 9.81) -> float:
+    def irradiance_on_surface(self, dni: float, dhi: float, incident_angle: float, surface_tilt: float) -> float:
         """
-        Calculate pressure difference due to stack effect.
+        Calculate total irradiance on a tilted surface.
         
         Args:
-            height: Height from reference level in m
-            indoor_temp: Indoor temperature in K
-            outdoor_temp: Outdoor temperature in K
-            neutral_plane_height: Height of neutral pressure plane in m (default: half of height)
-            gravity: Acceleration due to gravity in m/s² (default: 9.81 m/s²)
+            dni: Direct normal irradiance in W/m²
+            dhi: Diffuse horizontal irradiance in W/m²
+            incident_angle: Angle of incidence in degrees
+            surface_tilt: Surface tilt angle in degrees
             
         Returns:
-            Pressure difference in Pa
+            Total irradiance in W/m²
         """
-        if neutral_plane_height is None:
-            neutral_plane_height = height / 2
+        self.validate_angle(incident_angle, "Incident angle", 0, 90)
+        self.validate_angle(surface_tilt, "Surface tilt", 0, 180)
+        if dni < 0 or dhi < 0:
+            raise ValueError("Irradiance values cannot be negative")
         
-        # Calculate pressure difference
-        return gravity * (height - neutral_plane_height) * (outdoor_temp - indoor_temp) / outdoor_temp
+        direct = dni * math.cos(math.radians(incident_angle))
+        diffuse = dhi * (1 + math.cos(math.radians(surface_tilt))) / 2
+        return max(0, direct + diffuse)
+
+
+class HeatTransferCalculations:
+    """Class for heat transfer calculations."""
     
-    @staticmethod
-    def combined_pressure_difference(wind_pd: float, stack_pd: float) -> float:
-        """
-        Calculate combined pressure difference from wind and stack effects.
-        
-        Args:
-            wind_pd: Pressure difference due to wind in Pa
-            stack_pd: Pressure difference due to stack effect in Pa
-            
-        Returns:
-            Combined pressure difference in Pa
-        """
-        # Simple quadrature combination
-        return math.sqrt(wind_pd**2 + stack_pd**2)
+    def __init__(self):
+        """Initialize heat transfer calculations with solar calculations."""
+        self.solar = SolarCalculations()
     
-    @staticmethod
-    def solar_declination(day_of_year: int) -> float:
+    def validate_inputs(self, temp: float, area: float = 0.0, flow_rate: float = 0.0) -> None:
         """
-        Calculate solar declination angle.
+        Validate input parameters for heat transfer calculations.
         
         Args:
-            day_of_year: Day of the year (1-365)
+            temp: Temperature in °C
+            area: Area in m²
+            flow_rate: Flow rate in m³/s
             
-        Returns:
-            Solar declination angle in degrees
-        """
-        return EARTH_TILT_ANGLE * math.sin(2 * math.pi * (day_of_year - 81) / 365)
+        Raises:
+            ValueError: If inputs are out of acceptable ranges
+        """
+        if not -50 <= temp <= 60:
+            raise ValueError(f"Temperature {temp}°C is outside valid range (-50 to 60°C)")
+        if area < 0:
+            raise ValueError(f"Area {area}m² cannot be negative")
+        if flow_rate < 0:
+            raise ValueError(f"Flow rate {flow_rate}m³/s cannot be negative")
     
-    @staticmethod
-    def solar_hour_angle(solar_time: float) -> float:
+    def conduction_heat_transfer(self, u_value: float, area: float, delta_t: float) -> float:
         """
-        Calculate solar hour angle.
+        Calculate heat transfer by conduction.
         
         Args:
-            solar_time: Solar time in hours (0-24)
+            u_value: Overall heat transfer coefficient in W/(m²·K)
+            area: Surface area in m²
+            delta_t: Temperature difference in °C
             
         Returns:
-            Solar hour angle in degrees
+            Heat transfer rate in W
         """
-        return 15 * (solar_time - 12)
+        if u_value < 0:
+            raise ValueError(f"U-value {u_value} W/(m²·K) cannot be negative")
+        self.validate_inputs(delta_t, area)
+        return u_value * area * delta_t
     
-    @staticmethod
-    def solar_altitude(latitude: float, declination: float, hour_angle: float) -> float:
+    def convection_heat_transfer(self, h: float, area: float, delta_t: float) -> float:
         """
-        Calculate solar altitude angle.
+        Calculate heat transfer by convection.
         
         Args:
-            latitude: Latitude in degrees
-            declination: Solar declination angle in degrees
-            hour_angle: Solar hour angle in degrees
+            h: Convective heat transfer coefficient in W/(m²·K)
+            area: Surface area in m²
+            delta_t: Temperature difference in °C
             
         Returns:
-            Solar altitude angle in degrees
+            Heat transfer rate in W
         """
-        # Convert angles to radians
-        lat_rad = math.radians(latitude)
-        decl_rad = math.radians(declination)
-        hour_rad = math.radians(hour_angle)
-        
-        # Calculate solar altitude
-        sin_altitude = (math.sin(lat_rad) * math.sin(decl_rad) + 
-                       math.cos(lat_rad) * math.cos(decl_rad) * math.cos(hour_rad))
-        
-        return math.degrees(math.asin(sin_altitude))
+        if h < 0:
+            raise ValueError(f"Convective coefficient {h} W/(m²·K) cannot be negative")
+        self.validate_inputs(delta_t, area)
+        return h * area * delta_t
     
-    @staticmethod
-    def solar_azimuth(latitude: float, declination: float, hour_angle: float, altitude: float) -> float:
+    def radiation_heat_transfer(self, emissivity: float, area: float, t_surface: float, t_surroundings: float) -> float:
         """
-        Calculate solar azimuth angle.
+        Calculate heat transfer by radiation using Stefan-Boltzmann law.
         
         Args:
-            latitude: Latitude in degrees
-            declination: Solar declination angle in degrees
-            hour_angle: Solar hour angle in degrees
-            altitude: Solar altitude angle in degrees
+            emissivity: Surface emissivity (0-1)
+            area: Surface area in m²
+            t_surface: Surface temperature in °C
+            t_surroundings: Surroundings temperature in °C
             
         Returns:
-            Solar azimuth angle in degrees (0° = South, positive westward)
+            Heat transfer rate in W
         """
-        # Convert angles to radians
-        lat_rad = math.radians(latitude)
-        decl_rad = math.radians(declination)
-        hour_rad = math.radians(hour_angle)
-        alt_rad = math.radians(altitude)
-        
-        # Calculate solar azimuth
-        cos_azimuth = ((math.sin(decl_rad) * math.cos(lat_rad) - 
-                      math.cos(decl_rad) * math.sin(lat_rad) * math.cos(hour_rad)) / 
-                      math.cos(alt_rad))
-        
-        # Constrain to [-1, 1] to avoid domain errors
-        cos_azimuth = max(-1, min(1, cos_azimuth))
-        
-        # Calculate azimuth angle
-        azimuth = math.degrees(math.acos(cos_azimuth))
-        
-        # Adjust for morning hours (negative hour angle)
-        if hour_angle < 0:
-            azimuth = -azimuth
+        if not 0 <= emissivity <= 1:
+            raise ValueError(f"Emissivity {emissivity} must be between 0 and 1")
+        self.validate_inputs(t_surface, area)
+        self.validate_inputs(t_surroundings)
         
-        return azimuth
+        sigma = 5.67e-8  # Stefan-Boltzmann constant in W/(m²·K⁴)
+        t_s = t_surface + 273.15
+        t_sur = t_surroundings + 273.15
+        return emissivity * sigma * area * (t_s**4 - t_sur**4)
     
-    @staticmethod
-    def incident_angle(surface_tilt: float, surface_azimuth: float, 
-                      solar_altitude: float, solar_azimuth: float) -> float:
+    def thermal_lag_factor(self, thermal_mass: float, time_constant: float, time_step: float) -> float:
         """
-        Calculate angle of incidence on a surface.
+        Calculate thermal lag factor for transient heat transfer.
         
         Args:
-            surface_tilt: Surface tilt angle from horizontal in degrees (0° = horizontal, 90° = vertical)
-            surface_azimuth: Surface azimuth angle in degrees (0° = South, positive westward)
-            solar_altitude: Solar altitude angle in degrees
-            solar_azimuth: Solar azimuth angle in degrees
+            thermal_mass: Thermal mass in J/K
+            time_constant: Time constant in hours
+            time_step: Time step in hours
             
         Returns:
-            Incident angle in degrees
+            Thermal lag factor (0-1)
         """
-        # Convert angles to radians
-        surf_tilt_rad = math.radians(surface_tilt)
-        surf_azim_rad = math.radians(surface_azimuth)
-        solar_alt_rad = math.radians(solar_altitude)
-        solar_azim_rad = math.radians(solar_azimuth)
-        
-        # Calculate incident angle
-        cos_incident = (math.sin(solar_alt_rad) * math.cos(surf_tilt_rad) + 
-                       math.cos(solar_alt_rad) * math.sin(surf_tilt_rad) * 
-                       math.cos(solar_azim_rad - surf_azim_rad))
+        if thermal_mass < 0:
+            raise ValueError(f"Thermal mass {thermal_mass} J/K cannot be negative")
+        if time_constant <= 0:
+            raise ValueError(f"Time constant {time_constant} hours must be positive")
+        if time_step < 0:
+            raise ValueError(f"Time step {time_step} hours cannot be negative")
         
-        # Constrain to [-1, 1] to avoid domain errors
-        cos_incident = max(-1, min(1, cos_incident))
-        
-        return math.degrees(math.acos(cos_incident))
+        return math.exp(-time_step / time_constant)
     
-    @staticmethod
-    def direct_normal_irradiance(altitude: float, atmospheric_clearness: float = 1.0) -> float:
+    def infiltration_heat_transfer(self, flow_rate: float, delta_t: float) -> float:
         """
-        Calculate direct normal irradiance.
+        Calculate sensible heat transfer due to infiltration or ventilation.
         
         Args:
-            altitude: Solar altitude angle in degrees
-            atmospheric_clearness: Atmospheric clearness factor (0-1)
+            flow_rate: Air flow rate in m³/s
+            delta_t: Temperature difference in °C
             
         Returns:
-            Direct normal irradiance in W/m²
+            Sensible heat transfer rate in W
         """
-        if altitude <= 0:
-            return 0
-        
-        # Simple model based on air mass
-        air_mass = 1 / math.sin(math.radians(altitude))
-        
-        # Limit air mass to reasonable values
-        air_mass = min(air_mass, 38)
-        
-        # Calculate direct normal irradiance
-        dni = SOLAR_CONSTANT * atmospheric_clearness**air_mass
-        
-        return dni
+        self.validate_inputs(delta_t, flow_rate=flow_rate)
+        rho = 1.2  # Air density in kg/m³
+        cp = 1005  # Specific heat of air in J/(kg·K)
+        return flow_rate * rho * cp * delta_t
     
-    @staticmethod
-    def diffuse_horizontal_irradiance(dni: float, altitude: float, clearness: float = 0.2) -> float:
+    def infiltration_latent_heat_transfer(self, flow_rate: float, delta_w: float) -> float:
         """
-        Calculate diffuse horizontal irradiance.
+        Calculate latent heat transfer due to infiltration or ventilation.
         
         Args:
-            dni: Direct normal irradiance in W/m²
-            altitude: Solar altitude angle in degrees
-            clearness: Sky clearness factor (0-1)
+            flow_rate: Air flow rate in m³/s
+            delta_w: Humidity ratio difference in kg/kg
             
         Returns:
-            Diffuse horizontal irradiance in W/m²
+            Latent heat transfer rate in W
         """
-        if altitude <= 0:
-            return 0
-        
-        # Simple model for diffuse irradiance
-        return dni * clearness * math.sin(math.radians(altitude))
+        self.validate_inputs(0, flow_rate=flow_rate)
+        rho = 1.2  # Air density in kg/m³
+        h_fg = 2501000  # Latent heat of vaporization in J/kg
+        return flow_rate * rho * h_fg * delta_w
     
-    @staticmethod
-    def global_horizontal_irradiance(dni: float, dhi: float, altitude: float) -> float:
+    def wind_pressure_difference(self, wind_speed: float, wind_coefficient: float = 0.4) -> float:
         """
-        Calculate global horizontal irradiance.
+        Calculate pressure difference due to wind.
         
         Args:
-            dni: Direct normal irradiance in W/m²
-            dhi: Diffuse horizontal irradiance in W/m²
-            altitude: Solar altitude angle in degrees
+            wind_speed: Wind speed in m/s
+            wind_coefficient: Wind pressure coefficient
             
         Returns:
-            Global horizontal irradiance in W/m²
+            Pressure difference in Pa
         """
-        if altitude <= 0:
-            return 0
+        if wind_speed < 0:
+            raise ValueError(f"Wind speed {wind_speed} m/s cannot be negative")
+        if not 0 <= wind_coefficient <= 1:
+            raise ValueError(f"Wind coefficient {wind_coefficient} must be between 0 and 1")
         
-        # Calculate direct horizontal component
-        direct_horizontal = dni * math.sin(math.radians(altitude))
-        
-        # Calculate global horizontal irradiance
-        return direct_horizontal + dhi
+        rho = 1.2  # Air density in kg/m³
+        return 0.5 * wind_coefficient * rho * wind_speed**2
     
-    @staticmethod
-    def irradiance_on_surface(dni: float, dhi: float, incident_angle: float, 
-                             surface_tilt: float, ground_reflectance: float = 0.2) -> float:
+    def stack_pressure_difference(self, height: float, indoor_temp: float, outdoor_temp: float) -> float:
         """
-        Calculate total irradiance on a surface.
+        Calculate pressure difference due to stack effect.
         
         Args:
-            dni: Direct normal irradiance in W/m²
-            dhi: Diffuse horizontal irradiance in W/m²
-            incident_angle: Incident angle in degrees
-            surface_tilt: Surface tilt angle from horizontal in degrees
-            ground_reflectance: Ground reflectance (albedo) (0-1)
+            height: Height difference in m
+            indoor_temp: Indoor temperature in K
+            outdoor_temp: Outdoor temperature in K
             
         Returns:
-            Total irradiance on the surface in W/m²
+            Pressure difference in Pa
         """
-        # Convert angles to radians
-        incident_rad = math.radians(incident_angle)
-        tilt_rad = math.radians(surface_tilt)
-        
-        # Calculate direct component
-        if incident_angle < 90:
-            direct = dni * math.cos(incident_rad)
-        else:
-            direct = 0
+        if height < 0:
+            raise ValueError(f"Height {height} m cannot be negative")
+        if indoor_temp <= 0 or outdoor_temp <= 0:
+            raise ValueError("Temperatures must be positive in Kelvin")
         
-        # Calculate diffuse component (simple isotropic model)
-        diffuse = dhi * (1 + math.cos(tilt_rad)) / 2
-        
-        # Calculate ground-reflected component
-        reflected = (dni * math.sin(math.radians(incident_angle)) + dhi) * ground_reflectance * (1 - math.cos(tilt_rad)) / 2
-        
-        # Calculate total irradiance
-        return direct + diffuse + reflected
+        g = 9.81  # Gravitational acceleration in m/s²
+        rho = 1.2  # Air density in kg/m³
+        delta_t = abs(indoor_temp - outdoor_temp)
+        t_avg = (indoor_temp + outdoor_temp) / 2
+        return rho * g * height * delta_t / t_avg
     
-    @staticmethod
-    def solar_heat_gain(irradiance: float, area: float, shgc: float, 
-                       shading_coefficient: float = 1.0, frame_factor: float = 0.85) -> float:
+    def combined_pressure_difference(self, wind_pd: float, stack_pd: float) -> float:
         """
-        Calculate solar heat gain through a window.
+        Calculate combined pressure difference from wind and stack effects.
         
         Args:
-            irradiance: Total irradiance on the window in W/m²
-            area: Window area in m²
-            shgc: Solar Heat Gain Coefficient (0-1)
-            shading_coefficient: External shading coefficient (0-1)
-            frame_factor: Ratio of glazing area to total window area (0-1)
+            wind_pd: Wind pressure difference in Pa
+            stack_pd: Stack pressure difference in Pa
             
         Returns:
-            Solar heat gain in W
+            Combined pressure difference in Pa
         """
-        return irradiance * area * shgc * shading_coefficient * frame_factor
+        if wind_pd < 0 or stack_pd < 0:
+            raise ValueError("Pressure differences cannot be negative")
+        return math.sqrt(wind_pd**2 + stack_pd**2)
     
-    @staticmethod
-    def internal_gains(occupants: int, lights_power: float, equipment_power: float,
-                      occupant_sensible_gain: float = 70, occupant_latent_gain: float = 45) -> Dict[str, float]:
+    def crack_method_infiltration(self, crack_length: float, coefficient: float, 
+                                pressure_difference: float) -> float:
         """
-        Calculate internal heat gains.
+        Calculate infiltration flow rate using crack method.
         
         Args:
-            occupants: Number of occupants
-            lights_power: Lighting power in W
-            equipment_power: Equipment power in W
-            occupant_sensible_gain: Sensible heat gain per occupant in W (default: 70 W)
-            occupant_latent_gain: Latent heat gain per occupant in W (default: 45 W)
+            crack_length: Total crack length in m
+            coefficient: Flow coefficient in m³/(s·m·Pa^n)
+            pressure_difference: Pressure difference in Pa
             
         Returns:
-            Dictionary with sensible, latent, and total heat gains in W
-        """
-        # Calculate occupant gains
-        occupant_sensible = occupants * occupant_sensible_gain
-        occupant_latent = occupants * occupant_latent_gain
-        
-        # Calculate total sensible and latent gains
-        sensible_gain = occupant_sensible + lights_power + equipment_power
-        latent_gain = occupant_latent
-        
-        return {
-            "sensible": sensible_gain,
-            "latent": latent_gain,
-            "total": sensible_gain + latent_gain
-        }
-    
-    @staticmethod
-    def thermal_mass_effect(mass: float, specific_heat: float, delta_t: float) -> float:
+            Infiltration flow rate in m³/s
         """
-        Calculate heat storage in thermal mass.
+        if crack_length < 0:
+            raise ValueError(f"Crack length {crack_length} m cannot be negative")
+        if coefficient < 0:
+            raise ValueError(f"Coefficient {coefficient} cannot be negative")
+        if pressure_difference < 0:
+            raise ValueError(f"Pressure difference {pressure_difference} Pa cannot be negative")
         
-        Args:
-            mass: Mass of the material in kg
-            specific_heat: Specific heat capacity in J/(kg·K)
-            delta_t: Temperature change in K (or °C)
-            
-        Returns:
-            Heat stored in J
-        """
-        return mass * specific_heat * delta_t
+        n = 0.65  # Flow exponent
+        return coefficient * crack_length * pressure_difference**n
     
-    @staticmethod
-    def thermal_lag_factor(thermal_mass: float, time_constant: float, time_step: float) -> float:
+    def sol_air_temperature(self, outdoor_temp: float, solar_irradiance: float, 
+                           surface_absorptivity: float, surface_resistance: float) -> float:
         """
-        Calculate thermal lag factor for dynamic heat transfer.
+        Calculate sol-air temperature for a surface.
         
         Args:
-            thermal_mass: Thermal mass in J/K
-            time_constant: Time constant in hours
-            time_step: Time step in hours
+            outdoor_temp: Outdoor air temperature in °C
+            solar_irradiance: Solar irradiance on surface in W/m²
+            surface_absorptivity: Surface absorptivity (0-1)
+            surface_resistance: Surface resistance in m²·K/W
             
         Returns:
-            Thermal lag factor (0-1)
+            Sol-air temperature in °C
         """
-        return 1 - math.exp(-time_step / time_constant)
+        self.validate_inputs(outdoor_temp)
+        if solar_irradiance < 0:
+            raise ValueError(f"Solar irradiance {solar_irradiance} W/m² cannot be negative")
+        if not 0 <= surface_absorptivity <= 1:
+            raise ValueError(f"Surface absorptivity {surface_absorptivity} must be between 0 and 1")
+        if surface_resistance < 0:
+            raise ValueError(f"Surface resistance {surface_resistance} m²·K/W cannot be negative")
+        
+        h_ext = 1 / surface_resistance  # External convective coefficient
+        delta_t_rad = surface_absorptivity * solar_irradiance / h_ext
+        return outdoor_temp + delta_t_rad
     
-    @staticmethod
-    def temperature_swing(heat_gain: float, thermal_mass: float) -> float:
+    def solar_heat_gain(self, irradiance: float, area: float, shgc: float, 
+                       shading_coefficient: float = 1.0) -> float:
         """
-        Calculate temperature swing due to heat gain and thermal mass.
+        Calculate solar heat gain through a surface.
         
         Args:
-            heat_gain: Heat gain in J
-            thermal_mass: Thermal mass in J/K
+            irradiance: Solar irradiance on surface in W/m²
+            area: Surface area in m²
+            shgc: Solar heat gain coefficient (0-1)
+            shading_coefficient: Shading coefficient (0-1)
             
         Returns:
-            Temperature swing in K (or °C)
-        """
-        return heat_gain / thermal_mass
-    
-    @staticmethod
-    def sol_air_temperature(outdoor_temp: float, solar_irradiance: float, 
-                           surface_absorptivity: float, surface_resistance: float) -> float:
+            Solar heat gain in W
         """
-        Calculate sol-air temperature.
+        self.validate_inputs(0, area)
+        if irradiance < 0:
+            raise ValueError(f"Irradiance {irradiance} W/m² cannot be negative")
+        if not 0 <= shgc <= 1:
+            raise ValueError(f"SHGC {shgc} must be between 0 and 1")
+        if not 0 <= shading_coefficient <= 1:
+            raise ValueError(f"Shading coefficient {shading_coefficient} must be between 0 and 1")
         
-        Args:
-            outdoor_temp: Outdoor air temperature in °C
-            solar_irradiance: Solar irradiance on the surface in W/m²
-            surface_absorptivity: Surface solar absorptivity (0-1)
-            surface_resistance: Surface heat transfer resistance in m²·K/W
-            
-        Returns:
-            Sol-air temperature in °C
-        """
-        return outdoor_temp + solar_irradiance * surface_absorptivity * surface_resistance
+        return irradiance * area * shgc * shading_coefficient
 
 
 # Create a singleton instance
-heat_transfer = HeatTransferCalculations()
+heat_transfer_calculator = HeatTransferCalculations()
 
 # Example usage
 if __name__ == "__main__":
-    # Calculate conduction heat transfer
-    q_cond = heat_transfer.conduction_heat_transfer(u_value=0.5, area=10, delta_t=20)
-    print(f"Conduction heat transfer: {q_cond:.2f} W")
+    # Example solar calculations
+    latitude = 40.0
+    day_of_year = 204
+    hour = 12.0
     
-    # Calculate infiltration heat transfer
-    q_inf = heat_transfer.infiltration_heat_transfer(flow_rate=0.1, delta_t=20)
-    print(f"Infiltration heat transfer: {q_inf:.2f} W")
+    declination = heat_transfer_calculator.solar.solar_declination(day_of_year)
+    hour_angle = heat_transfer_calculator.solar.solar_hour_angle(hour)
+    altitude = heat_transfer_calculator.solar.solar_altitude(latitude, declination, hour_angle)
+    azimuth = heat_transfer_calculator.solar.solar_azimuth(latitude, declination, hour_angle, altitude)
     
-    # Calculate solar heat gain
-    q_solar = heat_transfer.solar_heat_gain(irradiance=500, area=5, shgc=0.7)
-    print(f"Solar heat gain: {q_solar:.2f} W")
+    print(f"Solar Declination: {declination:.2f}°")
+    print(f"Solar Hour Angle: {hour_angle:.2f}°")
+    print(f"Solar Altitude: {altitude:.2f}°")
+    print(f"Solar Azimuth: {azimuth:.2f}°")
     
-    # Calculate internal gains
-    gains = heat_transfer.internal_gains(occupants=3, lights_power=200, equipment_power=500)
-    print(f"Internal gains - Sensible: {gains['sensible']:.2f} W, Latent: {gains['latent']:.2f} W, Total: {gains['total']:.2f} W")
+    # Example heat transfer calculation
+    u_value = 0.5  # W/(m²·K)
+    area = 20.0  # m²
+    delta_t = 10.0  # °C
+    conduction = heat_transfer_calculator.conduction_heat_transfer(u_value, area, delta_t)
+    print(f"Conduction Heat Transfer: {conduction:.2f} W")