perf: mechanical Python-level optimizations (Tier 0) — 34% faster simulation

Eliminate Python overhead in the hot simulation loop through mechanical,
behavior-preserving replacements. No architecture or physics changes.

Benchmark: 30-day simulation at 1-minute timesteps (43,560 steps) using
BEopt_example.xml + BEopt_example_schedule.csv + Denver TMY3 weather,
starting June 1 2018, with PV (5kW), Battery (6kWh/3kW), and EV (BEV
Level 2). Deterministic via seed=42.

  Before: 37.67s → After: 24.86s (34.0% faster, 12.81s saved)
  Function calls: 74.3M → 44.6M (40% reduction)
  All 244 tests pass. Output identical within tolerances.

Changes by category:

Schedule/dispatch overhead:
- Cache DataFrame.empty as bool flag, recomputed in reset_time()
- Replace to_dict("records") iterator with array-backed dict construction
- Replace isinstance() checks with bit-flag dispatch on Equipment._kind
- Skip per-sub datetime comparisons when all sub-simulators share resolution
- Convert all_schedule_inputs membership test from list to frozenset

Unit conversion and constant caching:
- Cache pint convert() results as module-level constants for natural ventilation
- Also fixes natural ventilation area unit: ft^2 → m^2 (pre-existing bug)
- Pre-compute f-string schedule keys at init instead of per-step

Numpy small-array allocation elimination:
- Replace np.insert() with pre-allocated buffer in Water.update_model
- Replace np.array() + np.dot() biquadratic with inline scalar polynomial
- Pre-allocate np.zeros buffers in Envelope.update_inputs/update_model
- Pre-allocate surface temperature buffers for interior radiation
- Pre-allocate np.zeros/np.concatenate buffers in Water model
- Skip inputs_init.copy() in SSM when full control_signal provided

Scalar math dispatch:
- Python sum()/any() on numpy arrays → ndarray .sum()/.any()
- np.exp/np.sqrt on scalars → math.exp/math.sqrt
- Python min()/max() on numpy arrays → .min()/.max()
- Precompute vol_fractions cumulative sums in Water model

Lookup optimization:
- Dict index maps for StateSpaceModel input/output/state name lookups
- Scalar fast path for RCModel.solve_for_input (common infiltration case)
- Cache np.nonzero(~disable_speeds) in HVAC

Tests:
- Add tests for scalar solver equivalence and nat-vent unit conversion

Author: rcbevans

.gitignore

@@ -14,4 +14,8 @@ docs/_build
 *.code-workspace
 
 ochre/defaults/Input Files/OCHRE*
-.history
+.history
+
+test/outputs/*
+!test/outputs/benchmark_golden.parquet
+!test/outputs/benchmark_baseline.pstats

ochre/Dwelling.py

@@ -4,6 +4,7 @@
 import numpy as np
 
 from ochre import Simulator, Analysis
+from ochre.Simulator import KIND_EQUIPMENT, KIND_GENERATOR, KIND_BATTERY
 from ochre.utils import (
     OCHREException,
     load_hpxml,
@@ -177,6 +178,10 @@ def __init__(self, metrics_verbosity=3, save_schedule_columns=None, save_args_to
         # add envelope to sub_simulators after all equipment
         self.sub_simulators.append(self.envelope)
 
+        self._same_resolution = all(
+            sub.time_res == self.time_res for sub in self.sub_simulators
+        )
+
         # Run initialization to get realistic initial state
         if self.initialization_time is not None:
             self.initialize()
@@ -267,18 +272,18 @@ def start_sub_update(self, sub, control_signal):
         sub_control_signal = super().start_sub_update(sub, control_signal)
 
         # Add house net_power to schedule for Generator
-        if isinstance(sub, Generator) and "net_power" not in sub.current_schedule:
+        if sub._kind & KIND_GENERATOR and "net_power" not in sub.current_schedule:
             sub.current_schedule["net_power"] = self.total_p_kw
 
         # Add pv_power to schedule for Battery
-        if isinstance(sub, Battery) and "pv_power" not in sub.current_schedule:
+        if sub._kind & KIND_BATTERY and "pv_power" not in sub.current_schedule:
             pv_power = sum([e.electric_kw for e in self.equipment_by_end_use["PV"]])
             sub.current_schedule["pv_power"] = pv_power
 
         return sub_control_signal
 
     def finish_sub_update(self, sub):
-        if isinstance(sub, Equipment):
+        if sub._kind & KIND_EQUIPMENT:
             # update total electric and gas powers
             self.total_p_kw += sub.electric_kw
             self.total_q_kvar += sub.reactive_kvar

ochre/Equipment/Battery.py

@@ -5,6 +5,7 @@
 @author: rchintal, xjin, mblonsky
 """
 
+import math
 import numpy as np
 import datetime as dt
 import pandas as pd
@@ -15,6 +16,7 @@
 from ochre.utils.units import convert, degC_to_K
 from ochre.Models import OneNodeRCModel
 from ochre.Equipment import Generator
+from ochre.Simulator import KIND_EQUIPMENT, KIND_GENERATOR, KIND_BATTERY
 
 
 class BatteryThermalModel(OneNodeRCModel):
@@ -35,6 +37,7 @@ class Battery(Generator):
     end_use = "Battery"
     allow_consumption = True
     is_gas = False
+    _kind = KIND_EQUIPMENT | KIND_GENERATOR | KIND_BATTERY
     optional_inputs = Generator.optional_inputs + [
         "pv_power",
         "Battery Electric Power (kW)",
@@ -289,7 +292,7 @@ def calculate_efficiency(self, electric_kw=None, is_output_power=True):
             voc = float(self.voc_curve(self.soc)) * self.n_series
             if is_output_power:
                 electric_kw *= self.efficiency_inverter
-                v = voc / 2 + np.sqrt((voc / 2) ** 2 + (electric_kw * 1000) * self.r_internal)  # V = V_oc + P*R/V
+                v = voc / 2 + math.sqrt((voc / 2) ** 2 + (electric_kw * 1000) * self.r_internal)  # V = V_oc + P*R/V
             else:
                 v = voc + (electric_kw * 1000 / voc) * self.r_internal  # V = V_oc + I*R = V_oc + P/V_oc * R
 
@@ -322,7 +325,7 @@ def calculate_power_and_heat(self):
         e_ad2 = 9.752e6  # J / mol
         if self.thermal_model is not None:
             t_batt = self.thermal_model.states[self.t_idx] + degC_to_K
-            d0 = d0_ref * np.exp(-e_ad1 / R * (1 / t_batt - 1 / t_ref) + -e_ad2 / R * (1 / t_batt - 1 / t_ref) ** 2)
+            d0 = d0_ref * math.exp(-e_ad1 / R * (1 / t_batt - 1 / t_ref) + -e_ad2 / R * (1 / t_batt - 1 / t_ref) ** 2)
             self.capacity_kwh = self.capacity_kwh_nominal * d0
         else:
             self.capacity_kwh = self.capacity_kwh_nominal
@@ -423,15 +426,16 @@ def calculate_degradation(self):
         q3 += deg_time / tau_b3 * min(b3 - q3, 0)  # q3 always decreasing, always negative
         q3 = max(q3, b3)
         self.degradation_states = q1, q2, q3
+        deg_sum = sum(self.degradation_states)
 
         # raise warning/error if degradation is too high
-        if sum(self.degradation_states) >= 1:
+        if deg_sum >= 1:
             raise OCHREException("{} degraded beyond useful life.".format(self.name))
-        elif sum(self.degradation_states) >= 0.7:
+        elif deg_sum >= 0.7:
             self.warn("Degraded beyond useful life.")
 
         # update nominal capacity due to degradation
-        self.capacity_kwh_nominal = self.capacity_rated * (b0 - sum(self.degradation_states))
+        self.capacity_kwh_nominal = self.capacity_rated * (b0 - deg_sum)
 
         # reset degradation data
         self.degradation_data.clear()

ochre/Equipment/Equipment.py

@@ -2,6 +2,7 @@
 import numpy as np
 
 from ochre import Simulator
+from ochre.Simulator import KIND_EQUIPMENT
 from ochre.utils import OCHREException, load_csv
 from ochre.utils.units import kwh_to_therms
 
@@ -11,6 +12,7 @@ class Equipment(Simulator):
     end_use = "Other"
     is_electric = True
     is_gas = False
+    _kind = KIND_EQUIPMENT
     modes = ["On", "Off"]  # On and Off assumed as default modes
     zone_name = "Indoor"
 

ochre/Equipment/Generator.py

@@ -10,11 +10,13 @@
 from ochre.utils import OCHREException
 from ochre.utils.units import kwh_to_therms
 from ochre.Equipment import Equipment
+from ochre.Simulator import KIND_EQUIPMENT, KIND_GENERATOR
 
 
 class Generator(Equipment):
     allow_consumption = False
     is_gas = False
+    _kind = KIND_EQUIPMENT | KIND_GENERATOR
     zone_name = None
     optional_inputs = ["net_power"]
 

ochre/Equipment/HVAC.py

@@ -1,3 +1,4 @@
+import math
 import datetime as dt
 import numpy as np
 import psychrolib
@@ -680,15 +681,13 @@ def update_eir(self):
         plr = self.speed_idx  # part-load-ratio
         t_in = self.zone.temperature
         t_out = self.outlet_temp
+        c = self.efficiency_coeff
         if self.condensing:
-            eff_var = np.array([1, plr, plr**2, t_in, t_in**2, plr * t_in], dtype=float)
-            eff_curve_output = np.dot(eff_var, self.efficiency_coeff)
+            eff_curve_output = c[0] + c[1] * plr + c[2] * plr**2 + c[3] * t_in + c[4] * t_in**2 + c[5] * plr * t_in
         else:
-            eff_var = np.array(
-                [1, plr, plr**2, t_out, t_out**2, plr * t_out, plr**3, t_out**3, plr**2 * t_out, plr * t_out**2],
-                dtype=float,
-            )
-            eff_curve_output = np.dot(eff_var, self.efficiency_coeff)
+            eff_curve_output = (c[0] + c[1] * plr + c[2] * plr**2 + c[3] * t_out + c[4] * t_out**2
+                                + c[5] * plr * t_out + c[6] * plr**3 + c[7] * t_out**3
+                                + c[8] * plr**2 * t_out + c[9] * plr * t_out**2)
         return self.eir_max / eff_curve_output
 
 
@@ -712,6 +711,9 @@ def __init__(self, control_type="Time", **kwargs):
         # 2-speed control type and timing variables
         self.control_type = control_type  # 'Time', 'Time2', or 'Setpoint'
         self.disable_speeds = np.zeros(self.n_speeds, dtype=bool)  # if True, disable that speed
+        # Cached from np.nonzero(~disable_speeds). Must be recomputed in
+        # update_external_control whenever disable_speeds changes.
+        self._max_enabled_speed = self.n_speeds
         self.time_in_speed = dt.timedelta(0)
         min_time_in_low = kwargs.get("Minimum Low Time (minutes)", 5)
         min_time_in_high = kwargs.get("Minimum High Time (minutes)", 5)
@@ -809,6 +811,7 @@ def update_external_control(self, control_signal):
         #   - Note: Disable Speeds will not reset back to original value
         for idx in range(self.n_speeds):
             self.disable_speeds[idx] = bool(control_signal.get(f"Disable Speed {idx + 1}"))
+        self._max_enabled_speed = int(np.nonzero(~self.disable_speeds)[0][-1]) + 1
 
         return super().update_external_control(control_signal)
 
@@ -862,7 +865,7 @@ def run_two_speed_control(self):
         # enforce speed disabling from external control
         if self.disable_speeds[speed - 1]:
             # set to highest allowed speed
-            speed = np.nonzero(~self.disable_speeds)[0][-1] + 1
+            speed = self._max_enabled_speed
 
         if speed != prev_speed_idx or self.mode == "Off":
             self.time_in_speed = self.time_res
@@ -910,15 +913,15 @@ def calculate_biquadratic_param(self, param, speed_idx, flow_fraction=1, part_lo
         t_ext_db = min(max(t_ext_db, params["min_Tdb"]), params["max_Tdb"])
         flow_fraction = min(max(flow_fraction, params["min_ff"]), params["max_ff"])
 
-        # create vectors based on temperature, flow fraction, and plr
-        t_list = np.array([1, t_in, t_in**2, t_ext_db, t_ext_db**2, t_in * t_ext_db], dtype=float)
-        t_ratio = np.dot(t_list, params[param + "_t"])
+        # Coefficient order must match the arrays in initialize_biquad_params().
+        ct = params[param + "_t"]
+        t_ratio = ct[0] + ct[1] * t_in + ct[2] * t_in**2 + ct[3] * t_ext_db + ct[4] * t_ext_db**2 + ct[5] * t_in * t_ext_db
 
-        ff_list = np.array([1, flow_fraction, flow_fraction**2], dtype=float)
-        ff_ratio = np.dot(ff_list, params[param + "_ff"])
+        cf = params[param + "_ff"]
+        ff_ratio = cf[0] + cf[1] * flow_fraction + cf[2] * flow_fraction**2
 
-        plf_list = np.array([1, part_load_ratio, part_load_ratio**2], dtype=float)
-        plf_ratio = np.dot(plf_list, params[param + "_plr"])
+        cp = params[param + "_plr"]
+        plf_ratio = cp[0] + cp[1] * part_load_ratio + cp[2] * part_load_ratio**2
         plf_ratio = min(max(plf_ratio, params["min_plf"]), params["max_plf"])
 
         return rated * t_ratio * ff_ratio / plf_ratio
@@ -936,15 +939,15 @@ def calc_startup_capacity_degredation(self):
                     return 1.0
                 else:
                     exp_term = -3.79936 * (self.time_from_start / time_full_cap)
-                    capacity_mult = max(0, min(1.0, -1.025 * np.exp(exp_term) + 1.025))
+                    capacity_mult = max(0, min(1.0, -1.025 * math.exp(exp_term) + 1.025))
                     self.time_from_start += self.time_res
                     return capacity_mult
             else:
                 return 1.0
 
     def update_capacity(self):
         # update max capacity using highest enabled speed
-        max_speed = np.nonzero(~self.disable_speeds)[0][-1] + 1
+        max_speed = self._max_enabled_speed
         self.capacity_max = self.calculate_biquadratic_param(param="cap", speed_idx=max_speed)
 
         if self.use_ideal_capacity:
@@ -983,7 +986,7 @@ def update_capacity(self):
 
     def update_eir(self):
         # Update eir and eir_max using biquadratic model
-        max_speed = np.nonzero(~self.disable_speeds)[0][-1] + 1
+        max_speed = self._max_enabled_speed
         self.eir_max = self.calculate_biquadratic_param(param="eir", speed_idx=max_speed)
 
         if isinstance(self.speed_idx, int):

ochre/Equipment/WaterHeater.py

@@ -76,6 +76,8 @@ def __init__(self, use_ideal_capacity=None, model_class=None, **kwargs):
         self.deadband_temp = kwargs.get("Deadband Temperature (C)", 5.56)  # deadband range, in delta degC, i.e. Kelvin
         self.max_power = kwargs.get("Max Power (kW)")
 
+        self._heats_to_tank_buf = np.zeros(self.model.n_nodes, dtype=float)
+
     def update_inputs(self, schedule_inputs=None):
         # Add zone temperature to schedule inputs for water tank
         if not self.main_simulator:
@@ -249,7 +251,8 @@ def update_internal_control(self):
 
     def add_heat_from_mode(self, mode, heats_to_tank=None, duty_cycle=1):
         if heats_to_tank is None:
-            heats_to_tank = np.zeros(self.model.n_nodes, dtype=float)
+            self._heats_to_tank_buf.fill(0)
+            heats_to_tank = self._heats_to_tank_buf
 
         if mode == "Upper On":
             heats_to_tank[self.h_upper_idx] += self.capacity_rated * duty_cycle
@@ -262,7 +265,8 @@ def add_heat_from_mode(self, mode, heats_to_tank=None, duty_cycle=1):
     def calculate_power_and_heat(self):
         # get heat injections from water heater
         if self.use_ideal_capacity and self.mode != "Off":
-            heats_to_tank = np.zeros(self.model.n_nodes, dtype=float)
+            self._heats_to_tank_buf.fill(0)
+            heats_to_tank = self._heats_to_tank_buf
             for mode, duty_cycle in self.duty_cycle_by_mode.items():
                 heats_to_tank = self.add_heat_from_mode(mode, heats_to_tank, duty_cycle)
         else:
@@ -626,9 +630,14 @@ def add_heat_from_mode(self, mode, heats_to_tank=None, duty_cycle=1):
 
     def update_cop_and_capacity(self, t_wet):
         t_lower = np.dot(self.hp_nodes, self.model.states)  # use node connected to condenser
-        vector = np.array([1, t_wet, t_wet**2, t_lower, t_lower**2, t_lower * t_wet])
-        self.hp_capacity = self.hp_capacity_nominal * np.dot(self.hp_capacity_coeff, vector)
-        self.hp_cop = self.cop_nominal * np.dot(self.cop_coeff, vector)
+        cc = self.hp_capacity_coeff
+        self.hp_capacity = self.hp_capacity_nominal * (
+            cc[0] + cc[1] * t_wet + cc[2] * t_wet**2 + cc[3] * t_lower + cc[4] * t_lower**2 + cc[5] * t_lower * t_wet
+        )
+        ce = self.cop_coeff
+        self.hp_cop = self.cop_nominal * (
+            ce[0] + ce[1] * t_wet + ce[2] * t_wet**2 + ce[3] * t_lower + ce[4] * t_lower**2 + ce[5] * t_lower * t_wet
+        )
 
     def calculate_power_and_heat(self):
         t_dry = self.current_schedule["Zone Temperature (C)"]