HEAT current-model calculation specification

HEAT’s current HVAC and DHW pipelines compare building/equipment configurations, derive costs and savings, and scale them to technical, economic and achievable adoption. This specification covers the active inputs, hvac, dhw and shared reporting/calculation modules.

​

Execution and input boundary

The entry points covered here are hvac, dhw, hvac_load, dhw_load and hvac_weather_sensitivity. Use the parser for the selected command rather than assuming their flags are identical. HVAC and DHW support file and in-memory paths, sector selection, run-type selection, building-only runs and optional load outputs. Inputs are named Excel tables for settings, jurisdictions, weather, buildings, market stock, equipment, sizing, controls, baseline/upgrade mappings, policies, programs, rates, emissions and avoided costs. Examples include TB_ME_settings, TB_ME_market, TB_ME_rates, TB_ME_emissions_tCO2_per_GJ, TB_ME_sizing, TB_ME_control and TB_ME_baseline_upgrade_mapping. Scenario IDs, jurisdiction/sector/segment/vintage IDs, equipment/configuration IDs and year labels are join keys; compatible column names alone do not establish valid mappings. Config defines economic screening, competition metric/direction, potential types, NTG treatment, replacement cases, maximum adoption payback and weather settings. retain_savings_after_eul defaults to true. Boolean parser flags use the case-sensitive strings True and False; the optional settings helper uses Python truth conversion and does not independently parse arbitrary textual booleans.

​

Units, indexing and signs

Model-year values are at year-end; inputs are at year-start and are shifted during setup. Study endpoints are inclusive. Installation-year capital costs occur before subsequent operating impacts. Savings functions use baseline minus upgrade; positive savings indicate reduced use/cost/emissions. Raw hourly shape collection uses upgrade minus baseline. The published hourly result is subsequently scaled to the selected compiled annual column, so its sign follows that annual column. Do not assume every intermediate and final hourly quantity has the same sign convention.

​

HVAC building demand

For outdoor temperature $T_h$ and balance temperatures $T_b^H,T_b^C$: $$HDH_h=\max(T_b^H-T_h,0),\qquad CDH_h=\max(T_h-T_b^C,0)$$ For specified annual useful output $Q$ in GJ and degree-hour vector $DH$, the ordinary run solves: $$K=\frac{Q\,10^6}{3600\sum_hDH_h},\qquad q_h=KDH_h$$ If total degree-hours are zero, the solved coefficient is zero. A supplied frozen coefficient bypasses normalization and annual output becomes $K\sum_hDH_h3600/10^6$. This distinction is central to weather sensitivity. Heating design power uses the balance-temperature difference at the configured outdoor-temperature quantile. Cooling design power uses floor area and the supplied square-feet-per-cooling-ton assumption with the package’s area/ton conversions. Optional custom daily profiles redistribute each day’s energy across 24 hours; their normalization must preserve the intended daily total. Annual efficiency/demand trends are applied after first-year shapes are constructed.

​

HVAC equipment, sizing and controls

Air-source heat-pump COP is interpolated against temperature. For air-to-water equipment, outdoor reset first determines supply water temperature and the performance curve at that water temperature. Values beyond the supported water-temperature envelope can be zeroed; below the derived minimum outdoor temperature, the equipment’s usable capacity is zero. Before defrost, COP has floor $\min(\min(COP_{input}),1)$; defrost derate is interpolated and capped above at one. Final COP is the product of the floored COP and derate. Capacity interpolation is clipped below at zero. Scalar capacity evaluation and hourly vector interpolation use different helper paths, so extrapolation behaviour should not be assumed identical. Equipment configuration and sizing rules produce nominal primary/secondary capacities. Controls determine which hours and fractions are served by the primary equipment, then allocate unmet loads to available secondary equipment. For useful output assigned to an equipment unit, energy input follows output divided by its applicable COP/efficiency; demand and cost totals then aggregate by fuel/end use. A single annual COP cannot reproduce temperature-dependent dispatch, backup use and peak demand.

​

DHW physics and interactions

DHW useful hourly output is normalized DHW profile × annual useful DHW GJ × the GJ-to-kWh conversion. Design power is the maximum hourly output. Annual trends are applied by scenario. HPWH performance, sizing, controls and backup are evaluated through the DHW equipment configuration pipeline. HPWH extraction from conditioned space can increase space-heating demand and reduce cooling demand according to building inputs: fraction in conditioned space, cooling/heating interaction fractions, space-heating fuel shares and efficiencies, cooling efficiency and HPWH derate. These effects belong in total fuel/end-use results; do not count DHW appliance electricity alone as whole-building savings. The current DHW building helper looks up the winter peak-hour index for both its winter and summer DHW peak quantities. Treat this as implemented behaviour requiring review when interpreting summer peaks, not as a physical assumption that summer and winter peaks coincide.

​

Costs, bills, emissions and incentives

Per-unit capital cost combines fixed and capacity-dependent components with scenario real-growth trajectories. Incremental equipment and measure costs compare the selected baseline/upgrade configurations and replacement cases. Utility/nonutility incentives are calculated at building and measure levels using their configured caps and applicability. Energy value sums period energy × the corresponding fuel/scenario/year rate after index alignment. Demand bill is: $$Bill^{demand}_y=\sum_p\left(\sum_{m\in p}\max_{h\in(m,p)}kW_h\right)Rate_{p,y}$$ The rate helper intersects available period keys and raises an error if none match. Fixed charges, avoided demand costs, carbon valuation and one-off costs remain separate components. Emissions use energy by fuel and configured emissions factors; electricity at generator versus meter must be kept consistent with transmission/distribution losses. The savings helper aligns fuel/end-use combinations and subtracts upgrade from baseline. Present values use $NPV=\sum_tC_t/(1+r)^t$ with participant, societal or other configured perspective rates. Financial screens use the configured metric and a strict > cutoff, not a universal benefit/cost threshold imposed by the documentation. NTG scaling is applied according to potential type and reporting configuration; never apply it twice.

​

Pre-competition adoption and potential selection

Payback calculations distinguish simple payback and time-to-double-capital, with explicit handling for sign combinations of costs/savings. The payback-based willingness fraction is: $$P_{PB}=\min(1,e^{A\,PB+B})$$ Ordinary payback passed to adoption is capped at the configured maximum. For negative costs and negative savings, the inverse-payback branch derives an alternative using equipment life minus inverse payback, with a minimum of four years. Missing both payback values raises an error. The diffusion response uses Bass parameters $p,q,t_0$ evaluated at installation year. In the diffusion method, pre-competition adoption is $P_{PB}P_{diffusion}$. Barrier-based adoption has its own method branch. Technical/economic competition groups measures by submarket and installation year and selects on the configured metric/direction with market-applicability factors. Economic screening and policy mappings can change admissibility. Achievable competition allocates according to achievable adoption. Sales consume the corresponding market and remaining markets are shifted for subsequent replacement cases. The routine is not a global optimizer across all future installations.

​

Cohorts and impact aggregation

Per-unit time series are multiplied by the selected sales for technical, economic and achievable potential. Reporting distinguishes first-year, cumulative and lifetime impacts. With first-year cohort contributions $I^{first}_y$: I^{cum}_y=\sum_{t\le y}I^{first}_t\quad\text{when retain_savings_after_eul is true} When false, cumulative impact is the cross-sectional sum of each cohort’s actual contribution in year $y$, permitting expiry. The retained branch represents like-for-like persistence; it is not a survival model estimated from equipment data. Lifetime impacts sum energy or money across impact years and cannot be interpreted as instantaneous kW.

​

Annual and hourly output contracts

Compiled annual outputs carry end use, scenario, potential, year, impact type, reporting-level attributes and selected variables. reporting_constants controls column selection and unit conversions. HVAC and DHW retain different system/measure identifiers. The hourly collector forms generator-side unit shape $l_h=(upgrade_h-baseline_h)/(1-loss)$. It aggregates to reporting keys, joins annual compiled values $E_y$ in kWh, and scales: $$L_{y,h}=E_y\frac{l_h}{\sum_hl_h}$$ The generic scaler defaults to GWh_savings_at_generator_gross, multiplied by $10^6$. Only first-year and cumulative impact types are included. Near-zero denominators emit zero profiles with a warning. Missing annual columns or unmatched keys can cause outputs to be skipped with warnings, rather than fail the entire run. The current 8760 reshaper produces timestamp rows with scenario_id, potential, impact_type, series columns and a total. It requires one year/potential/impact type per input chunk, sums duplicate series names and uses float32 values. Timestamps are hourly offsets from January 1 for the supplied year; 8760 rows do not constitute a special leap-year calendar treatment. Gross/net, annual/hourly and meter/generator definitions must match before reconciliation.

​

Weather-sensitivity contract

The standalone HVAC weather tool reuses base-run adoption and nominal capacities, freezes the building heat/cool coefficient, and recomputes weather-dependent physics for alternate weather files. It does not rerun economic adoption or redesign the system to the new weather. Therefore annual output can change with degree-hours while installed stock and nominal sizing remain locked. Preserve cohort-specific first-year sales when rebuilding cumulative load outputs.

​

Validation and known boundaries

An annual useful demand of 36 GJ over 2,000 K·h gives $K=5$ kW/K and 10,000 kWh useful output. A fixed COP of 2.5 would require 4,000 kWh before backup/controls; this example is not a substitute for hourly dispatch. First-year cohort impacts 10 and 20 give retained cumulative impact 30 in year two. Check energy conservation, backup/unmet demand, distinct HVAC/DHW interaction accounting, bills by period, economic-screen boundaries, incentives, NTG, cohort expiry, annual/hourly reconciliation and locked weather sensitivity. Existing tests cover building shapes, sizing injection, weather sensitivity, hourly outputs, cumulative impacts, demand charges, incentives, participant/program costs and reporting. No claim of empirical calibration or future adoption accuracy follows from those implementation tests.