ecoengine 3.2.0__tar.gz → 3.2.2__tar.gz

{ecoengine-3.2.0 → ecoengine-3.2.2}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: ecoengine
-Version: 3.2.0
+Version: 3.2.2
 Requires-Python: >=3.11
 Requires-Dist: numpy<3.0,>=2.4
 Requires-Dist: scipy<2.0,>=1.17
 Requires-Dist: plotly<8.0,>=7.0
+Requires-Dist: kaleido>=1.3.0
 Provides-Extra: docs
 Requires-Dist: sphinx>=6; extra == "docs"
 Requires-Dist: furo; extra == "docs"

{ecoengine-3.2.0 → ecoengine-3.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ecoengine"
-version = "3.2.0"
+version = "3.2.2"
 requires-python = ">=3.11"
 
 # Ranges are bounded on purpose, and the shared ones are kept in sync with
@@ -32,6 +32,7 @@ dependencies = [
     "numpy>=2.4,<3.0",
     "scipy>=1.17,<2.0",
     "plotly>=7.0,<8.0",
+    "kaleido>=1.3.0",
 ]
 
 [project.optional-dependencies]

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine/constants/constants.py

@@ -2,4 +2,4 @@
 _RHO_CP: float = 8.353535
 
 # Unit conversion: 1 W = 3.412142 BTU/hr  (equivalently, 1 kW = 3.412142 kBTU/hr)
-_W_TO_KBTUH: float = 3.412142
+_BTUH_PER_W: float = 3.412142

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine/interfaces/EcosizerEngine.py

@@ -5,6 +5,7 @@ import os
 import warnings
 from .Simulator import simulate_3day as _simulate_3day, simulate_annual as _simulate_annual
 from ecoengine.objects.building.ClimateZone import ClimateZone as _ClimateZone
+from ecoengine.constants.constants import _BTUH_PER_W
 
 _BUNDLED_MAPS_PATH = os.path.join(os.path.dirname(__file__), "../data/preformanceMaps/maps.json")
 _WS_LOOKUP    = os.path.join(os.path.dirname(__file__), "../data/climate_data/WeatherStation_ClimateZone_Lookup.csv")
@@ -229,7 +230,7 @@ def get_hpwh_output_capacity(
     capacity_kbtuh *= num_heaters * (1.0 - defrost_derate)
 
     if return_as_kw:
-        return capacity_kbtuh / 3.41214  # kBTU/hr → kW
+        return capacity_kbtuh / _BTUH_PER_W  # kBTU/hr → kW
     return capacity_kbtuh
 
 
@@ -810,6 +811,7 @@ class EcosizerEngine:
         self._dhw_system  = None
 
         # Build and size immediately
+        self.fallback = False
         self.build()
 
     # ------------------------------------------------------------------
@@ -1113,7 +1115,7 @@ class EcosizerEngine:
             self._require_dual_fuel_sizing_params()
             with warnings.catch_warnings():
                 warnings.simplefilter("ignore")
-                return SP_RTPInSeriesSystem.from_size(
+                sprtp_in_series_system = SP_RTPInSeriesSystem.from_size(
                     building                   = self._building,
                     supply_temp_f              = self.supply_temp_f,
                     storage_temp_f             = self.storage_temp_f,
@@ -1128,6 +1130,11 @@ class EcosizerEngine:
                     control_map                = control_map,
                     load_shift_fract_total_vol = ls_fract,
                 )
+                if not sprtp_in_series_system.fallback_system is None:
+                    self.fallback = True
+                    return sprtp_in_series_system.fallback_system
+                else:
+                    return sprtp_in_series_system
 
         if self.schematic == "sprtp_in_parallel":
             from ecoengine.objects.dhwsystems.rtp_systems.SP_RTPInParallelSystem import SP_RTPInParallelSystem
@@ -1135,7 +1142,7 @@ class EcosizerEngine:
             self._require_dual_fuel_sizing_params()
             with warnings.catch_warnings():
                 warnings.simplefilter("ignore")
-                return SP_RTPInParallelSystem.from_size(
+                sprtp_in_parallel_system = SP_RTPInParallelSystem.from_size(
                     building                   = self._building,
                     supply_temp_f              = self.supply_temp_f,
                     storage_temp_f             = self.storage_temp_f,
@@ -1151,6 +1158,11 @@ class EcosizerEngine:
                     load_shift_fract_total_vol = ls_fract,
                     gas_controls               = self._build_gas_controls(),
                 )
+                if not sprtp_in_parallel_system.fallback_system is None:
+                    self.fallback = True
+                    return sprtp_in_parallel_system.fallback_system
+                else:
+                    return sprtp_in_parallel_system
 
         if self.schematic == "mprtp_in_series":
             from ecoengine.objects.dhwsystems.rtp_systems.MP_RTPInSeriesSystem import MP_RTPInSeriesSystem
@@ -1162,7 +1174,7 @@ class EcosizerEngine:
                 # engine-level setting (see the plain 'multi_pass_rtp' branch above,
                 # which hardcodes 14); MP_RTPInSeriesSystem defaults to the same
                 # value via _MPRTP_MAX_DAILY_RUN_HR.
-                return MP_RTPInSeriesSystem.from_size(
+                mprtp_in_series_system = MP_RTPInSeriesSystem.from_size(
                     building               = self._building,
                     supply_temp_f          = self.supply_temp_f,
                     storage_temp_f         = self.storage_temp_f,
@@ -1176,6 +1188,11 @@ class EcosizerEngine:
                     control_map            = control_map,
                     drawdown_fract         = self.drawdown_fract,
                 )
+                if not mprtp_in_series_system.fallback_system is None:
+                    self.fallback = True
+                    return mprtp_in_series_system.fallback_system
+                else:
+                    return mprtp_in_series_system
 
         if self.schematic == "swing_dual_fuel":
             from ecoengine.objects.dhwsystems.recirc_systems.SwingDualFuelSystem import SwingDualFuelSystem
@@ -1696,6 +1713,18 @@ class EcosizerEngine:
         if hasattr(sys, "_gas_capacity_kbtuh") and sys._gas_capacity_kbtuh is not None:
             result["gas_capacity_kbtuh"] = sys._gas_capacity_kbtuh
         return result
+    
+    def was_fallback_operation(self) -> bool:
+        """
+        Returns if flag for fallback operation was set (only applicable for supplemental heating systems that were undersized but still 
+        successfully completed a simulation)
+
+        Returns
+        -------
+        bool
+            True if an undersized base system succesfully passed simulation and sized no additional heating
+        """
+        return self.fallback
 
     # ------------------------------------------------------------------
     # Simulation
@@ -1905,7 +1934,7 @@ class EcosizerEngine:
         control_schedule, control_map = self._build_control_map()
         is_ls = "shed" in control_map
 
-        if self.schematic in _DUAL_FUEL_SCHEMATICS:
+        if self.schematic in _DUAL_FUEL_SCHEMATICS and not self.fallback:
             title = get_sizing_curve_title(self.schematic)
             # Gas backup curve has its own x/y semantics (backup storage vs.
             # backup capacity across ASHRAE windows) — _build_sizing_curve_figure

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine/objects/components/heating/PerformanceMap.py

@@ -5,7 +5,7 @@ import math
 import os
 import pickle
 
-from ecoengine.constants.constants import _W_TO_KBTUH
+from ecoengine.constants.constants import _BTUH_PER_W
 
 # Bundled data directory — used as a fallback when perf_map_dir is not supplied.
 # Will be removed once the data is fully externalised.
@@ -221,7 +221,7 @@ class PerformanceMap:
         pwr_kw    = self.get_power_in_kw(oat_f, outlet_temp_f, inlet_temp_f)
         if cap_kbtuh is None or pwr_kw is None or pwr_kw <= 0:
             return None
-        return (cap_kbtuh / _W_TO_KBTUH) / pwr_kw
+        return (cap_kbtuh / _BTUH_PER_W) / pwr_kw
 
     def is_within_operating_bounds(self, oat_f: float) -> bool:
         """Return True if the conditions are within the map's valid operating range."""
@@ -427,7 +427,7 @@ class PklPerformanceMap(PerformanceMap):
     def _er_per_unit_kw(self) -> float:
         """kW per unit at COP=1 (Electric Resistance fallback)."""
         if self._nominal_kbtuh is not None:
-            return (self._nominal_kbtuh / self.num_units) / _W_TO_KBTUH
+            return (self._nominal_kbtuh / self.num_units) / _BTUH_PER_W
         return self._default_out_low_kw
 
     def _get_per_unit_kw(
@@ -477,7 +477,7 @@ class PklPerformanceMap(PerformanceMap):
     ) -> float:
         inlet, outlet = self._resolve_temps(outlet_temp_f, inlet_temp_f)
         out_kw, _     = self._get_per_unit_kw(oat_f, inlet, outlet)
-        return out_kw * self.num_units * _W_TO_KBTUH
+        return out_kw * self.num_units * _BTUH_PER_W
 
     def get_capacity_kw(
         self,
@@ -485,7 +485,7 @@ class PklPerformanceMap(PerformanceMap):
         outlet_temp_f: float,
         inlet_temp_f: float | None = None,
     ) -> float:
-        return self.get_capacity_kbtuh(oat_f, outlet_temp_f, inlet_temp_f) / _W_TO_KBTUH
+        return self.get_capacity_kbtuh(oat_f, outlet_temp_f, inlet_temp_f) / _BTUH_PER_W
 
     def get_power_in_kw(
         self,
@@ -589,7 +589,7 @@ class HPWHsimPerformanceMap(PerformanceMap):
             entry    = self._perfmap[0]
             input_kw = self._quad(entry["inputPower_coeffs"], self._design_inlet_f) / 1000.0
             cop      = max(self._quad(entry["COP_coeffs"], self._design_inlet_f), 0.0)
-            return max(cop * input_kw * _W_TO_KBTUH, 0.0)
+            return max(cop * input_kw * _BTUH_PER_W, 0.0)
         return 0.0
 
     def _get_per_unit_kbtuh(
@@ -642,7 +642,7 @@ class HPWHsimPerformanceMap(PerformanceMap):
 
         output_kw = cop * input_kw
         # Convert kW to kBTU/hr
-        return output_kw * _W_TO_KBTUH, input_kw * _W_TO_KBTUH
+        return output_kw * _BTUH_PER_W, input_kw * _BTUH_PER_W
 
     # ------------------------------------------------------------------
     # Public interface
@@ -666,7 +666,7 @@ class HPWHsimPerformanceMap(PerformanceMap):
     ) -> float:
         inlet_temp_f  = inlet_temp_f if inlet_temp_f is not None else self._design_inlet_f
         _, inp_kbtuh = self._get_per_unit_kbtuh(oat_f, inlet_temp_f, outlet_temp_f)
-        return inp_kbtuh / _W_TO_KBTUH * self.num_units
+        return inp_kbtuh / _BTUH_PER_W * self.num_units
 
     def is_within_operating_bounds(self, oat_f: float) -> bool:
         return oat_f >= self.oat_min

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine/objects/dhwsystems/InstantWHSystem.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from ecoengine.constants.constants import _RHO_CP, _W_TO_KBTUH
+from ecoengine.constants.constants import _RHO_CP, _BTUH_PER_W
 from .DHWSystem import DHWSystem
 
 
@@ -119,7 +119,7 @@ class InstantWHSystem(DHWSystem):
             "demand_supplyT_gal":        demand_supplyT_gal,
             "usable_volume_supplyT_gal": 0.0,
             "heater_output_kbtuh":       capacity_kbtuh,
-            "heater_power_in_kw":        capacity_kbtuh / _W_TO_KBTUH,  # COP of 1.0
+            "heater_power_in_kw":        capacity_kbtuh / _BTUH_PER_W,  # COP of 1.0
             "oat_f":                     oat_f,
             "inlet_water_temp_f":        inlet_temp_f,
             "tank_temps_f":              [self.supply_temp_f] * 6,

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine/objects/dhwsystems/recirc_systems/SwingDualFuelSystem.py

@@ -7,7 +7,7 @@ from ecoengine.objects.components.heating.WaterHeater import WaterHeater
 from ecoengine.objects.components.storage.MixedStorageTank import MixedStorageTank
 from ecoengine.objects.components.storage.StratifiedTank import StratifiedTank
 from ecoengine.objects.dhwsystems.DHWSystem import DHWSystem
-from ecoengine.constants.constants import _RHO_CP, _W_TO_KBTUH
+from ecoengine.constants.constants import _RHO_CP, _BTUH_PER_W
 from ecoengine.objects.dhwsystems.utils import (
     mixing_valve_behavior,
     mixing_valve_behavior_swing,
@@ -509,5 +509,5 @@ class SwingDualFuelSystem(SwingSystem):
             # TM panel data (consumed by SimulationRun for the swing-tank subplot)
             "tm_tank_temp_f":            swing_mid_temp_f,
             "tm_heater_output_kbtuh":    tm_kbtuh,
-            "tm_heater_input_kw":        tm_kbtuh / _W_TO_KBTUH,
+            "tm_heater_input_kw":        tm_kbtuh / _BTUH_PER_W,
         }

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine/objects/dhwsystems/recirc_systems/SwingERTrdOffSystem.py

@@ -10,7 +10,7 @@ from ecoengine.objects.components.storage.MixedStorageTank import MixedStorageTa
 from ecoengine.objects.components.storage.StratifiedTank import StratifiedTank
 from ecoengine.objects.dhwsystems.DHWSystem import _get_peak_indices
 from .SwingSystem import SwingSystem, _ELEMENT_DEADBAND_F, _hr_to_min
-from ecoengine.constants.constants import _RHO_CP, _W_TO_KBTUH
+from ecoengine.constants.constants import _RHO_CP, _BTUH_PER_W
 
 if TYPE_CHECKING:
     from ecoengine.objects.building.Building import Building
@@ -520,7 +520,7 @@ class SwingERTrdOffSystem(SwingSystem):
 
     def get_er_capacity_kw(self) -> float:
         """Return the additional ER capacity added to the TM element [kW]."""
-        return self.get_er_capacity_kbtuh() / _W_TO_KBTUH
+        return self.get_er_capacity_kbtuh() / _BTUH_PER_W
 
     # ------------------------------------------------------------------
     # ER sizing curve (trade-off plot)
@@ -591,7 +591,7 @@ class SwingERTrdOffSystem(SwingSystem):
                 total_tm_i = self._minimum_tm_capacity_kbtuh
                 er_needed  = bool(self._er_capacity_kbtuh and self._er_capacity_kbtuh > 0)
 
-            er_cap_kw.append(round(total_tm_i / _W_TO_KBTUH, 0))
+            er_cap_kw.append(round(total_tm_i / _BTUH_PER_W, 0))
             fract_covered.append(i)
             i -= 10.0
 

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine/objects/dhwsystems/recirc_systems/SwingSystem.py

@@ -9,7 +9,7 @@ from ecoengine.objects.components.storage.StratifiedTank import StratifiedTank
 from ecoengine.objects.components.storage.MixedStorageTank import MixedStorageTank
 from ecoengine.objects.dhwsystems.DHWSystem import _get_peak_indices, StorageVolumeTooSmallError
 from .RecircSystem import RecircSystem
-from ecoengine.constants.constants import _RHO_CP, _W_TO_KBTUH
+from ecoengine.constants.constants import _RHO_CP, _BTUH_PER_W
 
 if TYPE_CHECKING:
     from ecoengine.objects.building.Building import Building
@@ -373,7 +373,7 @@ class SwingSystem(RecircSystem):
             tm_safety_factor × recirc_loss_kbtuh
         """
         recirc_loss_btuhr = self.get_recirc_loss_kbtuh() * 1000.0
-        vol_required = recirc_loss_btuhr / (_WATTS_PER_GAL * _W_TO_KBTUH)
+        vol_required = recirc_loss_btuhr / (_WATTS_PER_GAL * _BTUH_PER_W)
 
         if building is not None:
             peak_draw_gal_per_min = (
@@ -1038,5 +1038,5 @@ class SwingSystem(RecircSystem):
             # TM panel data (consumed by SimulationRun for the swing-tank subplot)
             "tm_tank_temp_f":            swing_mid_temp_f,
             "tm_heater_output_kbtuh":    tm_kbtuh,
-            "tm_heater_input_kw":        tm_kbtuh / _W_TO_KBTUH, # assume COP of 1
+            "tm_heater_input_kw":        tm_kbtuh / _BTUH_PER_W, # assume COP of 1
         }

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine/objects/dhwsystems/rtp_systems/MP_RTPInSeriesSystem.py

@@ -6,7 +6,7 @@ from ecoengine.objects.components.heating.Controls import Controls
 from ecoengine.objects.components.heating.WaterHeater import WaterHeater
 from ecoengine.objects.components.storage.MixedStorageTank import MixedStorageTank
 from ecoengine.objects.components.storage.SlugOverlayTank import SlugOverlayTank
-from ecoengine.constants.constants import _W_TO_KBTUH
+from ecoengine.constants.constants import _BTUH_PER_W
 from ecoengine.objects.dhwsystems.rtp_systems.SP_RTPInSeriesSystem import _GAS_DEADBAND_F
 from ..utils import (
     mixing_valve_behavior,
@@ -111,7 +111,10 @@ class MP_RTPInSeriesSystem(MultiPassRTPSystem):
         MP_RTPInSeriesSystem
         """
         # ensure shed turns primary system completely off
-        control_map = set_dual_fuel_shed_controls(control_map)
+        saved_shed_state = None
+        if 'shed' in control_map:
+            saved_shed_state = control_map.get("shed")
+            control_map = set_dual_fuel_shed_controls(control_map)
 
         system = cls(
             water_heaters=[],
@@ -124,7 +127,8 @@ class MP_RTPInSeriesSystem(MultiPassRTPSystem):
             defrost_factor=defrost_factor,
             tm_safety_factor=tm_safety_factor,
         )
-
+        system.saved_shed_state = saved_shed_state
+        system.fallback_system = None
         system._minimum_capacity_kbtuh = nominal_capacity_kbtuh
         system._minimum_storage_storageT_gal = nominal_storage_gal
 
@@ -194,24 +198,52 @@ class MP_RTPInSeriesSystem(MultiPassRTPSystem):
         """
         _WINDOW_MIN = 30
 
-        self.outage_volume_gal, self.outage_temp_delta_f = size_supplemental_heating_and_storage(
-            primary_system=self,
-            building=building,
-            nominal_capacity_kbtuh=nominal_capacity_kbtuh,
-        )
-
-        gas_capacity_kbtuh, gas_storage_vol_gal = self._gas_backup_from_window(_WINDOW_MIN)
-        # TODO add thermal efficiency
+        try:
+            self.outage_volume_gal, self.outage_temp_delta_f = size_supplemental_heating_and_storage(
+                primary_system=self,
+                building=building,
+                nominal_capacity_kbtuh=nominal_capacity_kbtuh,
+            )
+            gas_capacity_kbtuh, gas_storage_vol_gal = self._gas_backup_from_window(_WINDOW_MIN)
+            # TODO add thermal efficiency
 
-        self._in_series_storage_vol_gal = gas_storage_vol_gal
-        self._in_series_capacity_kbtuh = gas_capacity_kbtuh
+            self._in_series_storage_vol_gal = gas_storage_vol_gal
+            self._in_series_capacity_kbtuh = gas_capacity_kbtuh
 
-        self.gas_water_heater = WaterHeater.from_nominal_capacity(
-            nominal_capacity_kbtuh=gas_capacity_kbtuh,
-            control_schedule=["normal"] * 24,
-            control_map={"normal": gas_controls},
-        )
-        self.gas_storage_tank = MixedStorageTank(total_volume_gal=gas_storage_vol_gal)
+            self.gas_water_heater = WaterHeater.from_nominal_capacity(
+                nominal_capacity_kbtuh=gas_capacity_kbtuh,
+                control_schedule=["normal"] * 24,
+                control_map={"normal": gas_controls},
+            )
+            self.gas_storage_tank = MixedStorageTank(total_volume_gal=gas_storage_vol_gal)
+        except ValueError as e:
+            # Compare against base class to cover window where system is undersized but still passing the simulation
+            control_map = self.water_heaters[0].control_map
+            if 'shed' in control_map:
+                control_map['shed'] = self.saved_shed_state
+            comparison_system = MultiPassRTPSystem.from_size(
+                    building         = building,
+                    supply_temp_f    = self.supply_temp_f,
+                    storage_temp_f   = self.storage_temp_f,
+                    return_temp_f    = self.return_temp_f,
+                    return_flow_gpm  = self.return_flow_gpm,
+                    max_daily_run_hr = 14,
+                    defrost_factor   = self.defrost_factor,
+                    tm_safety_factor = self.tm_safety_factor,
+                    control_schedule = self.water_heaters[0].control_schedule,
+                    control_map      = control_map,
+                    drawdown_fract   = self.storage_tank.drawdown_fract,
+                )
+            result = {
+                "min_capacity_kbtuh":      comparison_system._minimum_capacity_kbtuh,
+                "min_storage_storageT_gal": comparison_system._minimum_storage_storageT_gal,
+            }
+            if result["min_capacity_kbtuh"] >= nominal_capacity_kbtuh and result["min_storage_storageT_gal"] >= nominal_storage_gal:
+                # redirect user to base model
+                self.fallback_system = comparison_system
+                return
+            else:
+                raise e
 
     # ------------------------------------------------------------------
     # Gas backup sizing helpers
@@ -409,6 +441,6 @@ class MP_RTPInSeriesSystem(MultiPassRTPSystem):
             "mode":                      mode,
             "tm_tank_temp_f":          self.gas_storage_tank.get_temperature_at_fraction(1.0),
             "tm_heater_output_kbtuh":  gas_kbtuh,
-            "tm_heater_input_kw":      gas_kbtuh / _W_TO_KBTUH,
+            "tm_heater_input_kw":      gas_kbtuh / _BTUH_PER_W,
             "delivery_temp_f":         gas_top_t,
         }

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine/objects/dhwsystems/rtp_systems/SP_RTPInParallelSystem.py

@@ -6,7 +6,7 @@ import numpy as np
 from ecoengine.objects.components.heating.Controls import Controls
 from ecoengine.objects.components.heating.WaterHeater import WaterHeater
 from ecoengine.objects.components.storage.EnergyTank import EnergyTank
-from ecoengine.constants.constants import _RHO_CP, _W_TO_KBTUH
+from ecoengine.constants.constants import _RHO_CP, _BTUH_PER_W
 from ..utils import (
     mixing_valve_behavior,
     size_supplemental_heating_and_storage,
@@ -154,7 +154,10 @@ class SP_RTPInParallelSystem(SinglePassRTPSystem):
         SP_RTPInParallelSystem
         """
         # ensure shed turns primary system completely off
-        control_map = set_dual_fuel_shed_controls(control_map)
+        saved_shed_state = None
+        if 'shed' in control_map:
+            saved_shed_state = control_map.get("shed")
+            control_map = set_dual_fuel_shed_controls(control_map)
 
         system = cls(
             water_heaters=[],
@@ -184,6 +187,9 @@ class SP_RTPInParallelSystem(SinglePassRTPSystem):
             control_map=control_map,
         )]
 
+        system.saved_shed_state = saved_shed_state
+        system.fallback_system = None
+
         # Gas backup controls: on at supply_temp, off at supply_temp + deadband
         system._size_gas_backup(
             building=building,
@@ -265,13 +271,39 @@ class SP_RTPInParallelSystem(SinglePassRTPSystem):
             0.0, max(self.supply_temp_f - t for t in sim_run.tank_temps_f[-1])
         )
         if sim_run.outage_minutes <= self._MIN_OUTAGE_MIN and max_deficit_f <= self._MIN_DEFICIT_F:
-            raise ValueError(
-                "The primary system is already adequately sized: "
-                f"outage duration was {sim_run.outage_minutes} min "
-                f"(threshold {self._MIN_OUTAGE_MIN} min) and max temperature deficit "
-                f"was {max_deficit_f:.2f} °F (threshold {self._MIN_DEFICIT_F:.1f} °F). "
-                "No gas backup is required."
-            )
+            control_map = self.water_heaters[0].control_map
+            if 'shed' in control_map:
+                control_map['shed'] = self.saved_shed_state
+            comparison_system = SinglePassRTPSystem.from_size(
+                    building                   = building,
+                    supply_temp_f              = self.supply_temp_f,
+                    storage_temp_f             = self.storage_temp_f,
+                    return_temp_f              = self.return_temp_f,
+                    return_flow_gpm            = self.return_flow_gpm,
+                    max_daily_run_hr           = self.max_daily_run_hr,
+                    defrost_factor             = self.defrost_factor,
+                    tm_safety_factor           = self.tm_safety_factor,
+                    control_schedule           = self.water_heaters[0].control_schedule,
+                    control_map                = control_map,
+                    load_shift_fract_total_vol = 1.0,
+                )
+            result = {
+                "min_capacity_kbtuh":      comparison_system._minimum_capacity_kbtuh,
+                "min_storage_storageT_gal": comparison_system._minimum_storage_storageT_gal,
+            }
+            if result["min_capacity_kbtuh"] >= nominal_capacity_kbtuh and result["min_storage_storageT_gal"] >= nominal_storage_gal:
+                # redirect user to base model
+                self.fallback_system = comparison_system
+                return
+            else:
+
+                raise ValueError(
+                    "The primary system is already adequately sized: "
+                    f"outage duration was {sim_run.outage_minutes} min "
+                    f"(threshold {self._MIN_OUTAGE_MIN} min) and max temperature deficit "
+                    f"was {max_deficit_f:.2f} °F (threshold {self._MIN_DEFICIT_F:.1f} °F). "
+                    "No gas backup is required."
+                )
 
         # The amount of storage (supply temp gallons) the gas is able to keep in a worst case scenario
         design_inlet    = self._require_design_inlet_temp(building)
@@ -462,6 +494,6 @@ class SP_RTPInParallelSystem(SinglePassRTPSystem):
             "tank_temps_f":              tank_temps_f,
             "mode":                      mode,
             "tm_heater_output_kbtuh":    gas_kbtuh,
-            "tm_heater_input_kw":        gas_kbtuh / _W_TO_KBTUH,
+            "tm_heater_input_kw":        gas_kbtuh / _BTUH_PER_W,
             "draw_thru_system_gal":      draw_gal,
         }

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine/objects/dhwsystems/rtp_systems/SP_RTPInSeriesSystem.py

@@ -6,7 +6,7 @@ from ecoengine.objects.components.heating.Controls import Controls
 from ecoengine.objects.components.heating.WaterHeater import WaterHeater
 from ecoengine.objects.components.storage.EnergyTank import EnergyTank
 from ecoengine.objects.components.storage.MixedStorageTank import MixedStorageTank
-from ecoengine.constants.constants import _RHO_CP, _W_TO_KBTUH
+from ecoengine.constants.constants import _RHO_CP, _BTUH_PER_W
 from ..utils import (
     mixing_valve_behavior,
     size_supplemental_heating_and_storage,
@@ -114,7 +114,10 @@ class SP_RTPInSeriesSystem(SinglePassRTPSystem):
         SP_RTPInSeriesSystem
         """
         # ensure shed turns primary system completely off
-        control_map = set_dual_fuel_shed_controls(control_map)
+        saved_shed_state = None
+        if 'shed' in control_map:
+            saved_shed_state = control_map.get("shed")
+            control_map = set_dual_fuel_shed_controls(control_map)
 
         system = cls(
             water_heaters=[],
@@ -127,6 +130,8 @@ class SP_RTPInSeriesSystem(SinglePassRTPSystem):
             defrost_factor=defrost_factor,
             tm_safety_factor=tm_safety_factor,
         )
+        system.saved_shed_state = saved_shed_state
+        system.fallback_system = None
 
         system._minimum_capacity_kbtuh = nominal_capacity_kbtuh
         system._minimum_storage_storageT_gal = nominal_storage_gal
@@ -180,9 +185,9 @@ class SP_RTPInSeriesSystem(SinglePassRTPSystem):
         ----------
         building : Building
         nominal_capacity_kbtuh : float
-            Primary HPWH capacity ceiling [kBTU/hr].
+            Primary HPWH capacity of the original undersized system [kBTU/hr].
         nominal_storage_gal : float
-            Primary storage volume ceiling [gal at storageT].
+            Primary storage volume of the original undersized system [gal at storageT].
         gas_controls : Controls
             Controls for the gas backup water heater.
 
@@ -193,17 +198,47 @@ class SP_RTPInSeriesSystem(SinglePassRTPSystem):
             and max deficit < 2 °F), meaning no gas backup is needed.
         """
         _WINDOW_MIN = 30
+        try:
+            # --- 1 & 2. Sizing simulation → outage arrays (raises ValueError if no backup needed) ---
+            self.outage_volume_gal, self.outage_temp_delta_f = size_supplemental_heating_and_storage(
+                primary_system=self,
+                building=building,
+                nominal_capacity_kbtuh=nominal_capacity_kbtuh,
+            )
 
-        # --- 1 & 2. Sizing simulation → outage arrays (raises ValueError if no backup needed) ---
-        self.outage_volume_gal, self.outage_temp_delta_f = size_supplemental_heating_and_storage(
-            primary_system=self,
-            building=building,
-            nominal_capacity_kbtuh=nominal_capacity_kbtuh,
-        )
-
-        # --- 3. Size gas backup components at the default 30-minute window ---
-        gas_capacity_kbtuh, gas_storage_vol_gal = self._gas_backup_from_window(_WINDOW_MIN)
-        # TODO add thermal efficiency
+            # --- 3. Size gas backup components at the default 30-minute window ---
+            gas_capacity_kbtuh, gas_storage_vol_gal = self._gas_backup_from_window(_WINDOW_MIN)
+            # TODO add thermal efficiency
+        except ValueError as e:
+            # Compare against base class to cover window where system is undersized but still passing the simulation
+            control_map = self.water_heaters[0].control_map
+            if 'shed' in control_map:
+                control_map['shed'] = self.saved_shed_state
+            comparison_system = SinglePassRTPSystem.from_size(
+                    building                   = building,
+                    supply_temp_f              = self.supply_temp_f,
+                    storage_temp_f             = self.storage_temp_f,
+                    return_temp_f              = self.return_temp_f,
+                    return_flow_gpm            = self.return_flow_gpm,
+                    max_daily_run_hr           = self.max_daily_run_hr,
+                    defrost_factor             = self.defrost_factor,
+                    tm_safety_factor           = self.tm_safety_factor,
+                    control_schedule           = self.water_heaters[0].control_schedule,
+                    control_map                = control_map,
+                    load_shift_fract_total_vol = 1.0,
+                )
+            result = {
+                "min_capacity_kbtuh":      comparison_system._minimum_capacity_kbtuh,
+                "min_storage_storageT_gal": comparison_system._minimum_storage_storageT_gal,
+            }
+            if result["min_capacity_kbtuh"] >= nominal_capacity_kbtuh and result["min_storage_storageT_gal"] >= nominal_storage_gal:
+                # redirect user to base model
+                self.fallback_system = comparison_system
+                return
+            else:
+                raise e
+
+            
 
         self._in_series_storage_vol_gal = gas_storage_vol_gal
         self._in_series_capacity_kbtuh = gas_capacity_kbtuh
@@ -393,6 +428,6 @@ class SP_RTPInSeriesSystem(SinglePassRTPSystem):
             "mode":                      mode,
             "tm_tank_temp_f":          self.gas_storage_tank.get_temperature_at_fraction(1.0),
             "tm_heater_output_kbtuh":  gas_kbtuh,
-            "tm_heater_input_kw":      gas_kbtuh / _W_TO_KBTUH,
+            "tm_heater_input_kw":      gas_kbtuh / _BTUH_PER_W,
             "delivery_temp_f":         gas_top_t,
         }

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine.egg-info/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: ecoengine
-Version: 3.2.0
+Version: 3.2.2
 Requires-Python: >=3.11
 Requires-Dist: numpy<3.0,>=2.4
 Requires-Dist: scipy<2.0,>=1.17
 Requires-Dist: plotly<8.0,>=7.0
+Requires-Dist: kaleido>=1.3.0
 Provides-Extra: docs
 Requires-Dist: sphinx>=6; extra == "docs"
 Requires-Dist: furo; extra == "docs"

{ecoengine-3.2.0 → ecoengine-3.2.2}/src/ecoengine.egg-info/requires.txt

@@ -1,6 +1,7 @@
 numpy<3.0,>=2.4
 scipy<2.0,>=1.17
 plotly<8.0,>=7.0
+kaleido>=1.3.0
 
 [docs]
 sphinx>=6