ecoengine 3.3.2__tar.gz → 3.3.3__tar.gz

{ecoengine-3.3.2 → ecoengine-3.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ecoengine
-Version: 3.3.2
+Version: 3.3.3
 Requires-Python: >=3.11
 Requires-Dist: numpy<3.0,>=2.4
 Requires-Dist: scipy<2.0,>=1.17

{ecoengine-3.3.2 → ecoengine-3.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ecoengine"
-version = "3.3.2"
+version = "3.3.3"
 requires-python = ">=3.11"
 
 # Ranges are bounded on purpose, and the shared ones are kept in sync with

{ecoengine-3.3.2 → ecoengine-3.3.3}/src/ecoengine/objects/building/UtilityCostTracker.py

@@ -260,6 +260,13 @@ class UtilityCostTracker:
         )
 
         uc = UtilityCostTracker.from_csv("utility_rates.csv")
+
+    Demand interval
+    ---------------
+    ``demand_interval_min`` (default 15) is the averaging window for demand
+    charges: the billed demand of a period is the highest average kW over any
+    ``demand_interval_min``-minute window that lies entirely inside that
+    period (see ``SimulationRun.get_max_demand_kw_by_period``).
     """
 
     def __init__(
@@ -272,7 +279,12 @@ class UtilityCostTracker:
         monthly_base_charge: float,
         energy_charge_by_hour: list[float] | None = None,
         include_discount: bool = False,
+        demand_interval_min: int = 15,
     ) -> None:
+        if not isinstance(demand_interval_min, int) or isinstance(demand_interval_min, bool) or demand_interval_min <= 0:
+            raise ValueError(
+                f"demand_interval_min must be a positive integer number of minutes, got {demand_interval_min!r}."
+            )
         self.demand_period_chart  = demand_period_chart
         self.demand_charge_map    = demand_charge_map
         self.energy_charge_map    = energy_charge_map
@@ -281,6 +293,7 @@ class UtilityCostTracker:
         self.monthly_base_charge  = monthly_base_charge
         self.energy_charge_by_hour: list[float] = energy_charge_by_hour or []
         self.include_discount     = include_discount
+        self.demand_interval_min  = demand_interval_min
 
     # ------------------------------------------------------------------
     # Factory constructors
@@ -303,6 +316,7 @@ class UtilityCostTracker:
         dscnt_end_hour=None,
         discnt_demand_charge=None,
         discnt_energy_charge=None,
+        demand_interval_min: int = 15,
     ) -> UtilityCostTracker:
         """
         Build a UtilityCostTracker from rate parameters.
@@ -348,6 +362,8 @@ class UtilityCostTracker:
             Discount demand charge [$/kW].
         discnt_energy_charge : float or list[float] or None
             Discount energy rate [$/kWh].
+        demand_interval_min : int
+            Averaging window for demand charges [minutes]. Default 15.
 
         Returns
         -------
@@ -414,6 +430,7 @@ class UtilityCostTracker:
             is_discount_map=is_discount_map,
             monthly_base_charge=monthly_base_charge,
             include_discount=include_discount,
+            demand_interval_min=demand_interval_min,
         )
 
     @classmethod
@@ -421,6 +438,7 @@ class UtilityCostTracker:
         cls,
         csv_path: str | None = None,
         csv_file: TextIOWrapper | None = None,
+        demand_interval_min: int = 15,
     ) -> UtilityCostTracker:
         """
         Build a UtilityCostTracker from an 8760-row CSV file.
@@ -439,6 +457,8 @@ class UtilityCostTracker:
         ----------
         csv_path : str or None
         csv_file : TextIOWrapper or None
+        demand_interval_min : int
+            Averaging window for demand charges [minutes]. Default 15.
 
         Returns
         -------
@@ -554,6 +574,7 @@ class UtilityCostTracker:
             is_discount_map=is_discount_map,
             monthly_base_charge=monthly_base_charge,
             energy_charge_by_hour=energy_charge_by_hour,
+            demand_interval_min=demand_interval_min,
         )
 
     # ------------------------------------------------------------------

{ecoengine-3.3.2 → ecoengine-3.3.3}/src/ecoengine/objects/simulation/SimulationRun.py

@@ -1,5 +1,8 @@
+import math
 import numbers
 
+import numpy as np
+
 from ecoengine.constants.constants import _RHO_CP
 
 _ANNUAL_DURATION_MIN = 365 * 24 * 60   # 525600
@@ -693,11 +696,71 @@ class SimulationRun:
 
         return fig
 
+    def get_max_demand_kw_by_period(self, uc) -> dict[int, float]:
+        """
+        Return the billed demand [kW] of each demand period: the highest
+        average combined kW (primary + TM / gas) over any
+        ``uc.demand_interval_min``-minute window that lies entirely inside
+        that period.
+
+        Windows slide at the finer of the simulation timestep and the demand
+        interval: each timestep is split into sub-steps of
+        ``gcd(timestep_min, demand_interval_min)`` minutes (e.g. 5 min for a
+        10-min simulation with a 15-min interval), and every window start on
+        that grid is tried. A window that spans two different demand periods
+        is ignored. A period with no complete window inside the simulated
+        time gets no entry, so it has no demand charge.
+
+        Parameters
+        ----------
+        uc : UtilityCostTracker
+
+        Returns
+        -------
+        dict[int, float]
+            ``{period_key: max windowed average kW}``.
+        """
+        n_steps = len(self.heater_power_in_kw)
+        interval_min = uc.demand_interval_min
+        sub_min = math.gcd(self.timestep_min, interval_min)
+        win     = interval_min // sub_min             # sub-steps per window
+
+        # Power and demand period on the sub-step grid
+        kw = np.repeat(
+            np.array([self._combined_kw(i) for i in range(n_steps)], dtype=float),
+            self.timestep_min // sub_min,
+        )
+        n_sub = len(kw)
+        if n_sub < win:
+            return {}
+        chart   = np.asarray(uc.demand_period_chart)
+        hours   = (np.arange(n_sub) * sub_min) // 60
+        periods = chart[hours % len(chart)]
+
+        # Average kW of the window starting at each sub-step
+        csum    = np.concatenate(([0.0], np.cumsum(kw)))
+        n_win   = n_sub - win + 1
+        avg_kw  = (csum[win:] - csum[:n_win]) / win
+
+        # A window is valid when its period never changes inside it
+        changes = np.concatenate(([0], np.cumsum(periods[1:] != periods[:-1])))
+        starts  = np.arange(n_win)
+        valid   = changes[starts + win - 1] == changes[starts]
+
+        start_periods = periods[:n_win]
+        max_kw_by_period: dict[int, float] = {}
+        for period in np.unique(start_periods[valid]):
+            mask = valid & (start_periods == period)
+            max_kw_by_period[int(period)] = float(avg_kw[mask].max())
+        return max_kw_by_period
+
     def get_annual_utility_cost(self, uc) -> float:
         """
         Compute total annual utility cost from this simulation run.
 
-        Cost = energy charges + demand charges (max kW per period) + yearly base.
+        Cost = energy charges + demand charges + yearly base. Demand charges
+        use each period's highest ``uc.demand_interval_min``-minute average kW
+        (see ``get_max_demand_kw_by_period``).
 
         Parameters
         ----------
@@ -711,17 +774,13 @@ class SimulationRun:
         """
         hours_per_step = self.timestep_min / 60.0
         energy_cost = 0.0
-        max_kw_by_period: dict[int, float] = {}
 
         for i in range(len(self.heater_power_in_kw)):
             kw = self._combined_kw(i)
             rate = uc.get_energy_charge_at_step(i, self.timestep_min)
             energy_cost += kw * hours_per_step * rate
 
-            period = uc.get_demand_period_at_step(i, self.timestep_min)
-            if period not in max_kw_by_period or kw > max_kw_by_period[period]:
-                max_kw_by_period[period] = kw
-
+        max_kw_by_period = self.get_max_demand_kw_by_period(uc)
         demand_cost = sum(
             uc.get_demand_charge_for_period(p, max_kw)
             for p, max_kw in max_kw_by_period.items()
@@ -745,7 +804,6 @@ class SimulationRun:
         """
         hours_per_step  = self.timestep_min / 60.0
         energy_by_month = [0.0] * 12
-        max_kw_by_period: dict[int, float] = {}
 
         for i in range(len(self.heater_power_in_kw)):
             kw   = self._combined_kw(i)
@@ -753,9 +811,7 @@ class SimulationRun:
             energy_by_month[_step_to_month(i, self.timestep_min)] += (
                 kw * hours_per_step * rate
             )
-            period = uc.get_demand_period_at_step(i, self.timestep_min)
-            if period not in max_kw_by_period or kw > max_kw_by_period[period]:
-                max_kw_by_period[period] = kw
+        max_kw_by_period = self.get_max_demand_kw_by_period(uc)
 
         # Assign each period's demand charge to its calendar month.
         # Period key = month * num_periods + offset → month = key // num_periods.
@@ -786,7 +842,6 @@ class SimulationRun:
         hours_per_step      = self.timestep_min / 60.0
         energy_peak         = [0.0] * 12
         energy_off_peak     = [0.0] * 12
-        max_kw_by_period: dict[int, float] = {}
 
         for i in range(len(self.heater_power_in_kw)):
             kw = self._combined_kw(i)
@@ -798,8 +853,7 @@ class SimulationRun:
                 energy_peak[month] += cost
             else:
                 energy_off_peak[month] += cost
-            if period not in max_kw_by_period or kw > max_kw_by_period[period]:
-                max_kw_by_period[period] = kw
+        max_kw_by_period = self.get_max_demand_kw_by_period(uc)
 
         num_periods    = 3 if uc.include_discount else 2
         demand_peak    = [0.0] * 12

{ecoengine-3.3.2 → ecoengine-3.3.3}/src/ecoengine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ecoengine
-Version: 3.3.2
+Version: 3.3.3
 Requires-Python: >=3.11
 Requires-Dist: numpy<3.0,>=2.4
 Requires-Dist: scipy<2.0,>=1.17