perf: mechanical Python-level optimizations — 34% faster simulation

[rcbevans]

Summary

Mechanical, behavior-preserving Python-level optimizations that eliminate overhead in the hot simulation loop. No architecture or physics changes. All existing tests pass. Simulation output is numerically identical to baseline within defined tolerances.

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

Results:

• 37.67s → 24.86s (34.0% faster, 12.81s saved)
• Function calls: 74.3M → 44.6M (40% reduction)
• All 244 tests pass, output identical within tolerances (temperatures: atol=0.01, rtol=1e-4; power: atol=0.001, rtol=1e-3)

Changes

Schedule/dispatch overhead (~5s saved)

• Cache DataFrame.empty as bool flag, recomputed in reset_time()
• Replace to_dict("records") iterator with array-backed dict construction
• Reuse schedule dict in-place via clear() instead of allocating new dict each step
• 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 (~4.5s saved)

• Cache pint convert() results as module-level constants for natural ventilation
• Also fixes natural ventilation area unit: ft^2 → m^2 (pre-existing bug — open_window_area is computed in m² but was being converted as ft²)
• Pre-compute f-string schedule keys at init instead of per-step
• Pre-format zone temperature schedule keys at Dwelling init
• Cache time_res.total_seconds() as _dt_seconds/_dt_hours/_dt_minutes at init (eliminates repeated timedelta method calls across Simulator, Water, Humidity, WaterHeater, Generator, and EV hot paths)

Numpy small-array allocation elimination (~2s saved)

• Replace np.insert() with pre-allocated buffer in Water.update_model
• Replace np.array() + np.dot() biquadratic with inline scalar polynomial (HVAC, GasBoiler, HPWH)
• 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 StateSpaceModel when full control_signal provided

Scalar math dispatch (~1s saved)

• Python sum()/any() on numpy arrays → .sum()/.any()
• np.exp/np.sqrt on scalars → math.exp/math.sqrt
• Python min()/max() on numpy arrays → .min()/.max() (including Water.update_results)
• Precompute vol_fractions cumulative sums in Water model
• Replace list-wrapped any([...]) and sum([...]) with generator expressions across Dwelling, HVAC, WaterHeater, Envelope, and Simulator

Lookup optimization (~1s saved)

• Dict index maps for StateSpaceModel input/output/state name lookups
• Scalar fast path for RCModel.solve_for_input (common single-input infiltration case)
• Cache np.nonzero(~disable_speeds) in HVAC
• Pre-compute Generator._ramp_minutes at init

Bug fix

• Fix Battery.py typo: "Zone Temperture (C)" → "Zone Temperature (C)" — battery thermal model was writing to wrong schedule key, so its Water sub-model never received correct zone temperature from Dwelling

Correctness

Every change is a mechanical replacement that produces identical numerical results:

• sum(arr) → arr.sum() — same values
• np.exp(scalar) → math.exp(scalar) — same values
• np.array([1, x, x**2]) @ coeffs → coeffs[0] + coeffs[1]*x + coeffs[2]*x**2 — same values
• Pre-allocated buffers replace per-step allocations — same contents
• Cached constants replace per-call pint.convert() — same conversion factors
• isinstance(x, Class) → x._kind & FLAG — same dispatch decisions
• Dict reuse via clear() + repopulate — same key/value pairs each step
• any([genexpr]) → any(genexpr) — same boolean result, avoids intermediate list

Test plan

• uv run python -m unittest discover test — 244 pass, 1 skipped (pre-existing)
• Golden reference comparison passed (--compare mode)
• Deterministic benchmark with seed=42 confirms output stability across runs
• New tests for scalar solver equivalence (test_rcmodel.py) and nat-vent unit conversion (test_envelope.py)

[jmaguire1]

This is awesome, thanks Rich! It's going to take us a little bit to look through this, make sure we're comfortable with everything (and taking on the maintenance burden of any new methods). If you find issues with the physics or other bugs please do keep calling them out, but for speed I think give us a little time to digest here before going too much farther down the optimizing path. We don't normally have such productive collaborators!

[rcbevans]

This is awesome, thanks Rich! It's going to take us a little bit to look through this, make sure we're comfortable with everything (and taking on the maintenance burden of any new methods). If you find issues with the physics or other bugs please do keep calling them out, but for speed I think give us a little time to digest here before going too much farther down the optimizing path. We don't normally have such productive collaborators!

I have a second branch which would go into this one which refactored core formulas to use numba (again, it matches a golden parque so no behavioral deviation).

https://github.com/AZX-PBC-OSS/OCHRE/tree/perf/tier1-numba-optimizations

This reduces the 30 day simulation further, down to ~19s from the original 37.67 in the dev branch.

[rcbevans]

This was an existing bug

[rcbevans]

This was an existing bug