hvac-crossover 0.1.0__py3-none-any.whl

hvac_crossover/__init__.py

@@ -0,0 +1,75 @@
+"""
+hvac_crossover - Multi-Source HVAC Efficiency & Thermodynamic Crossover Optimizer
+Decoupled library for optimizing heat pumps, boilers, multi-split constraints, and micro-zoning.
+"""
+
+from .models import (
+    HvacMode,
+    HvacAction,
+    ProducerType,
+    EmitterType,
+    FuelType,
+    NetMeteringMode,
+    ThermalProfile,
+    SharedBoilerRole,
+    SystemPhase,
+    TariffSchedule,
+    Producer,
+    InverterHeatPumpProducer,
+    ModulatingBoilerProducer,
+    SteamBoilerProducer,
+    ProducerProfileFactory,
+    DeliveryUnit,
+    MiniSplitHead,
+    HydronicEmitter,
+    SmartRadiatorValve,
+    ComfortRange,
+    Space,
+    SpaceCondition,
+    SystemSnapshot,
+    SpaceDirective,
+    ProducerDirective,
+    Diagnostics,
+    DispatchPlan,
+    SystemTopology,
+)
+from .config import CoordinatorConfig
+from .coordinator import DualFuelCoordinator
+from .engines import EconomicsEngine, RecoveryEngine, ArbitratorEngine
+
+__version__ = "0.1.0"
+__all__ = [
+    "CoordinatorConfig",
+    "DualFuelCoordinator",
+    "EconomicsEngine",
+    "RecoveryEngine",
+    "ArbitratorEngine",
+    "HvacMode",
+    "HvacAction",
+    "ProducerType",
+    "EmitterType",
+    "FuelType",
+    "NetMeteringMode",
+    "ThermalProfile",
+    "SharedBoilerRole",
+    "SystemPhase",
+    "TariffSchedule",
+    "Producer",
+    "InverterHeatPumpProducer",
+    "ModulatingBoilerProducer",
+    "SteamBoilerProducer",
+    "ProducerProfileFactory",
+    "DeliveryUnit",
+    "MiniSplitHead",
+    "HydronicEmitter",
+    "SmartRadiatorValve",
+    "ComfortRange",
+    "Space",
+    "SpaceCondition",
+    "SystemSnapshot",
+    "SpaceDirective",
+    "ProducerDirective",
+    "Diagnostics",
+    "DispatchPlan",
+    "SystemTopology",
+]

hvac_crossover/config.py

@@ -0,0 +1,26 @@
+"""Coordinator configuration, policies, and operational thresholds."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CoordinatorConfig:
+    """
+    Configurable policies, thresholds, and safety parameters for the DualFuelCoordinator.
+    """
+    # Thermal Recovery vs Plateau Boundaries
+    recovery_delta_threshold_f: float = 3.0   # Deficit >= 3.0°F -> engage high-capacity boiler recovery
+    plateau_delta_threshold_f: float = 1.0    # Deficit <= 1.0°F -> hand off to heat pump plateau
+
+    # Economic Switching Buffer (Hysteresis)
+    # E.g. 1.05 means heat pump cost ($/MMBtu) must be at least 5% cheaper than boiler
+    # to switch from boiler to heat pump, preventing flip-flopping right at the crossover line.
+    economic_switching_buffer: float = 1.05
+
+    # Absolute Outdoor Temperature Safeguards
+    min_heat_pump_temp_f: float = -13.0       # Minimum rated operational temperature for cold-climate inverters
+
+    # Operational Interlocks
+    passive_ventilation_override: bool = True # Open window/skylight forces space delivery units to OFF
+    enforce_odu_mode_locks: bool = True       # Enforce single-refrigerant mode lock across heads on same ODU
+    short_cycling_protection: bool = True     # Apply burner cycling derate when load is below boiler min fire

hvac_crossover/coordinator.py

@@ -0,0 +1,295 @@
+"""Main DualFuelCoordinator facade and central evaluation pipeline."""
+
+from typing import Dict, Any, Optional, List, Set, Tuple
+from .models.enums import HvacMode, HvacAction, SystemPhase, ProducerType
+from .models.topology import SystemTopology
+from .models.tariffs import TariffSchedule
+from .models.snapshot import SystemSnapshot
+from .models.spaces import SpaceCondition, ComfortRange
+from .models.delivery import MiniSplitHead, HydronicEmitter
+from .models.plan import DispatchPlan, SpaceDirective, ProducerDirective, Diagnostics
+from .config import CoordinatorConfig
+from .engines.economics import EconomicsEngine
+from .engines.recovery import RecoveryEngine
+from .engines.arbitrator import ArbitratorEngine
+
+
+class DualFuelCoordinator:
+    """
+    Central coordination service and facade for dual-fuel HVAC systems.
+    Evaluates ground-truth environmental and space conditions to produce
+    actionable hardware directives and explainable telemetry.
+    """
+
+    def __init__(
+        self,
+        topology: SystemTopology,
+        config: Optional[CoordinatorConfig] = None,
+    ):
+        self.topology = topology
+        self.config = config or CoordinatorConfig()
+        self.economics = EconomicsEngine()
+        self.recovery = RecoveryEngine(self.config)
+        self.arbitrator = ArbitratorEngine(self.config)
+
+    def evaluate(self, snapshot: SystemSnapshot) -> DispatchPlan:
+        """
+        Evaluates the ground-truth snapshot and generates a DispatchPlan.
+        """
+        space_directives: Dict[str, SpaceDirective] = {}
+        producer_directives: Dict[str, ProducerDirective] = {}
+        explanations: List[str] = []
+
+        # 1. Determine Macro System Phase
+        system_phase = self.recovery.determine_system_phase(snapshot.spaces, self.topology)
+
+        # 2. Find primary boiler for crossover calculations
+        boiler_producers = [
+            p for p in self.topology.producers
+            if p.producer_type in (ProducerType.MODULATING_BOILER, ProducerType.ATMOSPHERIC_BOILER, ProducerType.STEAM_BOILER)
+        ]
+        primary_boiler = boiler_producers[0] if boiler_producers else None
+
+        # Calculate general economic crossover temp for telemetry
+        crossover_temp = 41.4  # Default fallback
+        hp_producers = [p for p in self.topology.producers if p.producer_type == ProducerType.INVERTER_HEAT_PUMP]
+        if primary_boiler and hp_producers:
+            t_cross = self.economics.compute_crossover_temperature(
+                tariffs=snapshot.tariffs,
+                odu=hp_producers[0],
+                boiler=primary_boiler,
+                telemetry=snapshot.telemetry,
+            )
+            if t_cross is not None:
+                crossover_temp = t_cross
+
+        # 3. Initial Space Demand Assessment
+        candidate_space_modes: Dict[str, HvacMode] = {}
+        candidate_emitters: Dict[str, Optional[str]] = {}
+        target_temps: Dict[str, Optional[float]] = {}
+        requested_boiler_zones: Set[Tuple[str, str]] = set()
+
+        space_costs: Dict[str, float] = {}
+        space_cops: Dict[str, float] = {}
+
+        for space in self.topology.spaces:
+            cond = snapshot.spaces.get(space.id)
+            if not cond:
+                candidate_space_modes[space.id] = HvacMode.OFF
+                candidate_emitters[space.id] = None
+                target_temps[space.id] = None
+                continue
+
+            # Check window interlocks for passive ventilation
+            if cond.window_open and self.config.passive_ventilation_override:
+                candidate_space_modes[space.id] = HvacMode.OFF
+                candidate_emitters[space.id] = None
+                target_temps[space.id] = None
+                explanations.append(f"Space '{space.name}' delivery units turned OFF due to open window/skylight.")
+                continue
+
+            # Deadband / Uncontrolled Float Check
+            if cond.comfort.is_in_deadband(cond.current_temp):
+                candidate_space_modes[space.id] = HvacMode.OFF
+                candidate_emitters[space.id] = None
+                target_temps[space.id] = None
+                continue
+
+            # Cooling Demand
+            if cond.comfort.demands_cool(cond.current_temp):
+                candidate_space_modes[space.id] = HvacMode.COOL
+                target_temps[space.id] = cond.comfort.cool_to
+                cooling_heads = [e for e in space.emitters if isinstance(e, MiniSplitHead)]
+                if cooling_heads:
+                    candidate_emitters[space.id] = cooling_heads[0].id
+                else:
+                    candidate_emitters[space.id] = None
+                continue
+
+            # Heating Demand
+            if cond.comfort.demands_heat(cond.current_temp):
+                candidate_space_modes[space.id] = HvacMode.HEAT
+                target_temps[space.id] = cond.comfort.heat_to
+
+                # Estimate space heating load
+                load_btu = space.estimated_heat_loss_btu_per_hr(cond.current_temp, snapshot.outdoor_temp)
+
+                # Check if space is in heavy setback recovery (>= 3.0°F deficit)
+                in_recovery = self.recovery.is_space_in_recovery(cond)
+
+                # Find available hydronic emitter
+                hydronic_emitters = [e for e in space.emitters if isinstance(e, HydronicEmitter)]
+                mini_split_heads = [e for e in space.emitters if isinstance(e, MiniSplitHead)]
+
+                if in_recovery and hydronic_emitters and snapshot.outdoor_temp < 45.0:
+                    # In deep recovery pull-up below 45°F, dispatch high-capacity boiler
+                    selected = hydronic_emitters[0]
+                    candidate_emitters[space.id] = selected.id
+                    requested_boiler_zones.add((selected.producer_id, selected.zone_id))
+                    explanations.append(
+                        f"Space '{space.name}' in setback recovery (deficit {cond.comfort.heat_deficit(cond.current_temp):.1f}°F): "
+                        f"dispatched high-capacity hydronic boiler for rapid pull-up."
+                    )
+                else:
+                    # Steady-state plateau or mild weather: rank emitters economically
+                    ranked = self.economics.rank_space_emitters_by_cost(
+                        space=space,
+                        outdoor_temp_f=snapshot.outdoor_temp,
+                        tariffs=snapshot.tariffs,
+                        topology=self.topology,
+                        load_btu=load_btu,
+                        telemetry=snapshot.telemetry,
+                        part_load=True,
+                    )
+                    if ranked:
+                        best_emitter, best_cost, best_eff = ranked[0]
+                        candidate_emitters[space.id] = best_emitter.id
+                        space_costs[space.id] = round(best_cost, 2)
+                        space_cops[space.id] = round(best_eff, 2)
+
+                        if isinstance(best_emitter, HydronicEmitter):
+                            requested_boiler_zones.add((best_emitter.producer_id, best_emitter.zone_id))
+
+        # 4. Multi-Split ODU Mode Conflict Arbitration
+        if self.config.enforce_odu_mode_locks:
+            resolved_modes, odu_explanations = self.arbitrator.arbitrate_odu_modes(
+                requested_space_modes=candidate_space_modes,
+                topology=self.topology,
+                space_conditions=snapshot.spaces,
+            )
+            explanations.extend(odu_explanations)
+        else:
+            resolved_modes = candidate_space_modes
+
+        # 5. Shared Hydronic Zone Valve Arbitration
+        approved_boiler_zones, boiler_explanations = self.arbitrator.arbitrate_shared_boiler_zones(
+            requested_boiler_zones=requested_boiler_zones,
+            topology=self.topology,
+            space_conditions=snapshot.spaces,
+        )
+        explanations.extend(boiler_explanations)
+
+        # 6. Build Space Directives
+        for space in self.topology.spaces:
+            cond = snapshot.spaces.get(space.id)
+            final_mode = resolved_modes.get(space.id, HvacMode.OFF)
+            emitter_id = candidate_emitters.get(space.id)
+            target = target_temps.get(space.id)
+
+            if cond and cond.window_open and self.config.passive_ventilation_override:
+                action = HvacAction.PASSIVE_VENTILATION
+                final_mode = HvacMode.OFF
+                emitter_id = None
+            elif final_mode == HvacMode.HEAT:
+                action = HvacAction.HEATING
+            elif final_mode in (HvacMode.COOL, HvacMode.DRY):
+                action = HvacAction.COOLING
+            else:
+                action = HvacAction.IDLE if cond and cond.comfort.is_in_deadband(cond.current_temp) else HvacAction.OFF
+
+            active_producer_id = None
+            if emitter_id:
+                for e in space.emitters:
+                    if e.id == emitter_id:
+                        active_producer_id = e.producer_id
+                        break
+
+            space_directives[space.id] = SpaceDirective(
+                space_id=space.id,
+                action=action,
+                hvac_mode=final_mode,
+                target_temp=target,
+                active_delivery_unit_id=emitter_id,
+                active_producer_id=active_producer_id,
+                explanation=f"Mode: {final_mode.value}, Action: {action.value}"
+            )
+
+        # 7. Build Producer Directives
+        odu_operational_modes: Dict[str, str] = {}
+        for producer in self.topology.producers:
+            if producer.producer_type == ProducerType.INVERTER_HEAT_PUMP:
+                # Find mode of active heads on this ODU
+                active_modes = [
+                    space_directives[s.id].hvac_mode
+                    for s in self.topology.get_spaces_for_producer(producer.id)
+                    if s.id in space_directives and space_directives[s.id].active_producer_id == producer.id
+                ]
+                active_modes = [m for m in active_modes if m != HvacMode.OFF]
+                odu_mode = active_modes[0] if active_modes else HvacMode.OFF
+                is_active = odu_mode != HvacMode.OFF
+                odu_operational_modes[producer.id] = odu_mode.value
+
+                producer_directives[producer.id] = ProducerDirective(
+                    producer_id=producer.id,
+                    operational_mode=odu_mode,
+                    is_active=is_active,
+                )
+            else:
+                # Boiler / Furnace producer
+                active_zones = [
+                    zone_id for b_id, zone_id in approved_boiler_zones
+                    if b_id == producer.id
+                ]
+                is_active = len(active_zones) > 0
+                producer_directives[producer.id] = ProducerDirective(
+                    producer_id=producer.id,
+                    operational_mode=HvacMode.HEAT if is_active else HvacMode.OFF,
+                    is_active=is_active,
+                    active_zones=active_zones,
+                )
+
+        # 8. Assemble Diagnostics
+        diagnostics = Diagnostics(
+            economic_crossover_temp=round(crossover_temp, 1),
+            system_phase=system_phase,
+            odu_modes=odu_operational_modes,
+            space_costs_per_mmbtu=space_costs,
+            space_cops=space_cops,
+            explanations=explanations,
+        )
+
+        return DispatchPlan(
+            space_directives=space_directives,
+            producer_directives=producer_directives,
+            diagnostics=diagnostics,
+        )
+
+    def evaluate_conditions(
+        self,
+        outdoor_temp: float,
+        tariffs: TariffSchedule,
+        spaces: Dict[str, Dict[str, Any]],
+        solar_export_watts: float = 0.0,
+        boiler_return_temp: Optional[float] = None,
+        elec_rate_override: Optional[float] = None,
+        current_hour: Optional[int] = None,
+    ) -> DispatchPlan:
+        """
+        Convenience keyword-argument evaluation method that constructs a SystemSnapshot internally.
+        """
+        space_conditions: Dict[str, SpaceCondition] = {}
+        for s_id, s_data in spaces.items():
+            current_temp = float(s_data["current"])
+            comfort = ComfortRange(
+                heat_to=s_data.get("heat_to"),
+                cool_to=s_data.get("cool_to"),
+            )
+            window_open = bool(s_data.get("window_open", False))
+            occupied = bool(s_data.get("occupied", True))
+            space_conditions[s_id] = SpaceCondition(
+                current_temp=current_temp,
+                comfort=comfort,
+                window_open=window_open,
+                occupied=occupied,
+            )
+
+        snapshot = SystemSnapshot(
+            outdoor_temp=outdoor_temp,
+            tariffs=tariffs,
+            spaces=space_conditions,
+            solar_export_watts=solar_export_watts,
+            boiler_return_temp=boiler_return_temp,
+            elec_rate_override=elec_rate_override,
+            current_hour=current_hour,
+        )
+        return self.evaluate(snapshot)

hvac_crossover/engines/__init__.py

@@ -0,0 +1,11 @@
+"""Specialized evaluation engines for hybrid_hvac."""
+
+from .economics import EconomicsEngine
+from .recovery import RecoveryEngine
+from .arbitrator import ArbitratorEngine
+
+__all__ = [
+    "EconomicsEngine",
+    "RecoveryEngine",
+    "ArbitratorEngine",
+]

hvac_crossover/engines/arbitrator.py

@@ -0,0 +1,163 @@
+"""Refrigerant mode safety and shared-zone arbitration engine."""
+
+from typing import Dict, List, Set, Tuple, Optional
+from ..models.enums import HvacMode, HvacAction, SharedBoilerRole
+from ..models.producers import InverterHeatPumpProducer
+from ..models.delivery import DeliveryUnit, MiniSplitHead, HydronicEmitter
+from ..models.spaces import Space, SpaceCondition
+from ..models.topology import SystemTopology
+from ..config import CoordinatorConfig
+
+
+class ArbitratorEngine:
+    """
+    Enforces hardware physical safety constraints:
+    1. Multi-split single-refrigerant mode locks (preventing heat/cool conflict faults).
+    2. Shared hydronic zone valve arbitration (master/slave relationships).
+    3. Window/skylight cutoffs for passive thermal banking.
+    """
+
+    def __init__(self, config: CoordinatorConfig):
+        self.config = config
+
+    def arbitrate_odu_modes(
+        self,
+        requested_space_modes: Dict[str, HvacMode],
+        topology: SystemTopology,
+        space_conditions: Dict[str, SpaceCondition],
+    ) -> Tuple[Dict[str, HvacMode], List[str]]:
+        """
+        Ensures all heads on each ODU operate in a compatible refrigerant mode.
+        If a conflict occurs (e.g. Head A wants COOL, Head B wants HEAT on same ODU):
+        - If the ODU supports simultaneous heat/cool (VRF Heat Recovery), allow both.
+        - Otherwise, checks if the heating head can be diverted to an alternate producer (boiler).
+        - If no alternate exists, highest priority Space wins; lower priority is idled.
+        Returns: (resolved_space_modes, explanation_messages)
+        """
+        resolved_modes = dict(requested_space_modes)
+        explanations = []
+
+        # Find all inverter heat pump producers
+        odus = [p for p in topology.producers if isinstance(p, InverterHeatPumpProducer)]
+
+        for odu in odus:
+            if odu.supports_simultaneous_heat_cool:
+                continue  # VRF Heat Recovery relaxes the single-mode lock
+
+            # Find all spaces that have a mini-split head on this ODU
+            odu_spaces: List[Tuple[Space, MiniSplitHead]] = []
+            for s in topology.spaces:
+                for d in s.emitters:
+                    if isinstance(d, MiniSplitHead) and d.producer_id == odu.id:
+                        odu_spaces.append((s, d))
+                        break
+
+            # Collect active requested modes (ignore OFF/IDLE)
+            active_modes: Dict[str, List[Tuple[Space, MiniSplitHead]]] = {"heat": [], "cool": [], "dry": []}
+            for s, head in odu_spaces:
+                mode = resolved_modes.get(s.id, HvacMode.OFF)
+                if mode in (HvacMode.HEAT, HvacMode.COOL, HvacMode.DRY):
+                    active_modes[mode.value].append((s, head))
+
+            active_mode_keys = [k for k, v in active_modes.items() if v]
+
+            # Conflict: both HEAT and COOL (or DRY) requested on the same ODU!
+            if "heat" in active_mode_keys and ("cool" in active_mode_keys or "dry" in active_mode_keys):
+                cooling_spaces = active_modes["cool"] + active_modes["dry"]
+                heating_spaces = active_modes["heat"]
+
+                # Check if heating spaces can be cleanly diverted to an alternate hydronic emitter
+                diverted_all_heaters = True
+                diverted_spaces = []
+
+                for s, head in heating_spaces:
+                    has_hydronic_alt = any(
+                        isinstance(e, HydronicEmitter) for e in s.emitters
+                    )
+                    if has_hydronic_alt:
+                        diverted_spaces.append(s)
+                    else:
+                        diverted_all_heaters = False
+                        break
+
+                if diverted_all_heaters:
+                    # Successfully resolved conflict by diverting heat to boiler!
+                    for s in diverted_spaces:
+                        explanations.append(
+                            f"ODU Mode Conflict on '{odu.id}': Space '{s.name}' diverted heating to hydronic boiler "
+                            f"to allow cooling on upper space(s)."
+                        )
+                else:
+                    # Cannot divert all heaters; resolve via space priority
+                    max_cooling_priority = max(s.priority for s, _ in cooling_spaces)
+                    max_heating_priority = max(s.priority for s, _ in heating_spaces)
+
+                    if max_cooling_priority > max_heating_priority:
+                        winning_mode = HvacMode.COOL
+                        for s, _ in heating_spaces:
+                            resolved_modes[s.id] = HvacMode.OFF
+                            explanations.append(
+                                f"ODU Mode Conflict on '{odu.id}': Space '{s.name}' heating paused; "
+                                f"cooling prioritized on higher-priority space."
+                            )
+                    else:
+                        winning_mode = HvacMode.HEAT
+                        for s, _ in cooling_spaces:
+                            resolved_modes[s.id] = HvacMode.OFF
+                            explanations.append(
+                                f"ODU Mode Conflict on '{odu.id}': Space '{s.name}' cooling paused; "
+                                f"heating prioritized on higher-priority space."
+                            )
+
+        return resolved_modes, explanations
+
+    def arbitrate_shared_boiler_zones(
+        self,
+        requested_boiler_zones: Set[Tuple[str, str]],
+        topology: SystemTopology,
+        space_conditions: Dict[str, SpaceCondition],
+    ) -> Tuple[Set[Tuple[str, str]], List[str]]:
+        """
+        Arbitrates multiple spaces sharing the same boiler zone valve (e.g. Floor 2 Z2).
+        Returns: (approved_boiler_zones, explanation_messages)
+        """
+        approved_zones = set(requested_boiler_zones)
+        explanations = []
+
+        # Find all unique (boiler_id, zone_id) pairs
+        all_zones = set()
+        for s in topology.spaces:
+            for d in s.emitters:
+                if isinstance(d, HydronicEmitter):
+                    all_zones.add((d.producer_id, d.zone_id))
+
+        for boiler_id, zone_id in all_zones:
+            shared_spaces = topology.get_shared_hydronic_spaces(boiler_id, zone_id)
+            if len(shared_spaces) <= 1:
+                continue  # Dedicated zone, no arbitration needed
+
+            # Identify Master and Slave spaces
+            masters = [s for s in shared_spaces if s.shared_boiler_role == SharedBoilerRole.MASTER]
+            slaves = [s for s in shared_spaces if s.shared_boiler_role == SharedBoilerRole.SLAVE]
+
+            zone_key = (boiler_id, zone_id)
+            if zone_key not in approved_zones:
+                continue
+
+            # If zone was called by a slave, check if master permits or if slave should float
+            master_calling = any(
+                space_conditions[m.id].comfort.demands_heat(space_conditions[m.id].current_temp)
+                for m in masters if m.id in space_conditions
+            )
+
+            if not master_calling and slaves:
+                for slave in slaves:
+                    cond = space_conditions.get(slave.id)
+                    if cond and not cond.occupied:
+                        approved_zones.discard(zone_key)
+                        explanations.append(
+                            f"Shared Zone '{zone_id}' call cancelled: Slave space '{slave.name}' is unoccupied "
+                            f"and master space is satisfied."
+                        )
+
+        return approved_zones, explanations