Methodology
This page describes the calculator implementations in the project. The formula tables below are imported from the same modules used by the interactive tools.
Inputs, defaults, and examples
The calculators combine values typed or selected by a reader with defaults from src/data/defaults.us.json and src/data/defaults.solar.us.json. The data-source page reads those same files. At present, the defaults are unverified illustrative placeholders; the calculators identify them as such. A reader's replacement values are user inputs, not data verified by Teranautics.
Some starting values are selected from the US data files according to the chosen climate, fuel, or solar-resource band. The heat-pump size can be estimated from floor area and an unverified watts-per-square-metre default when its size field is blank. This is a rough arithmetic rule, not a building load calculation. Files under src/lib/calc/*fixtures.json are hand-checkable test fixtures; they are not regional evidence or live market defaults.
Heat-pump area can be entered in square feet or square metres; the interface converts square feet to square metres for calculation. Heat demand, fuel price, and electricity price are supplied to the model in the kWh-based units shown by the form; area is converted from square feet to square metres when needed. The current datasets use USD and the calculators display dollar amounts. Solar system capacity is DC kW, and installed price is USD per watt. These tools currently contain US data only.
Heat-pump model v0.2
Let A be heated floor area in m² and q the selected annual heat demand per m². Estimated useful heat demand is Q = A × q. For current-system efficiency η, fuel price Pf, heat-pump seasonal performance S, and electricity price Pe:
Current annual cost = (Q ÷ η) × Pf
Heat-pump annual cost = (Q ÷ S) × Pe
Annual saving = current annual cost − heat-pump annual cost
Installation cost is (capacity × tier price + fixed cost) × scenario multiplier. User-entered incentives are subtracted from each scenario's installation cost, with net cost floored at zero. Low, typical, and high outputs pair the configured cost multipliers with the more favourable, typical, and less favourable seasonal-COP cases respectively. The resulting bounds are sensitivity scenarios; they are not confidence intervals or probability estimates.
| Heat demand (kWh/yr) | floor area (m²) × zone heat demand (kWh/m²/yr) |
|---|---|
| Install cost | (size kW × cost per kW for tier + fixed cost) × range multiplier |
| Heat pump running cost | heat demand ÷ SCOP × electricity price |
| Current running cost | heat demand ÷ current efficiency × fuel price |
| Annual saving | current running cost − heat pump running cost |
| Payback (years) | (install cost − incentive) ÷ annual saving; blank if saving ≤ 0 |
| Horizon total, heat pump | net install cost (or loan payments inside the horizon) + running cost × years |
| Horizon total, current | current running cost × years. Excludes replacing the existing system. |
| Low / high | Low: cheapest install multiplier, best SCOP. High: dearest multiplier, worst SCOP. |
Simple payback divides net installation cost by annual savings and is omitted when savings are zero or negative. The horizon comparison multiplies yearly running costs by the selected number of years and includes loan payments that fall inside the horizon when financing is enabled. It does not add a replacement cost for the current system.
The optional loan uses a level monthly payment calculated from principal, APR, and loan term. The displayed comparison is not a lender quote. The model does not discount future cash flows or adjust prices for inflation.
Heat-pump limitations
- Heat demand is a single climate-band value; there is no room-by-room load calculation, building inspection, or equipment selection.
- One seasonal COP is used for the year. Weather, defrost, backup heat, cycling, and equipment-specific performance are not modelled individually.
- Energy prices are treated as flat in the heat-pump model. Tariff tiers, fixed charges, cooling, and cooling savings are excluded.
- System size, cost tiers, heat demand, and regional default values depend on assumptions that are currently unverified.
Solar model v0.1
Let C be DC capacity in kW, H peak sun hours per day, and R the performance ratio. Year-one generation is G₁ = C × H × 365 × R. For degradation fraction d, generation in year t is Gₜ = G₁ × (1 − d)^(t − 1).
For annual household use U, self-consumption share s, import price Pi, and export price Px, self-used energy is the smaller of Gₜ × s and U; the balance is exported. Annual saving is self-used energy times the import price plus exported energy times the export price. The model escalates both prices by the selected rate when that input is non-zero.
| Install cost | capacity (kW) × 1,000 × installed cost per watt × range multiplier |
|---|---|
| Annual generation, year 1 (kWh) | capacity (kW) × peak sun hours per day × 365 × performance ratio |
| Generation in year t | year-1 generation × (1 − degradation)^(t − 1) |
| Self-used (kWh) | smaller of (generation × self-consumption share) and annual consumption |
| Exported (kWh) | generation − self-used |
| Purchased from grid (kWh) | annual consumption − self-used |
| Annual saving | self-used × import price + exported × export price |
| Prices in year t | year-1 price × (1 + escalation)^(t − 1); escalation defaults to 0 |
| Simple payback (years) | (install cost − incentive) ÷ year-1 saving; blank if saving ≤ 0 |
| Cumulative net at horizon | sum of annual savings − net install cost (or − loan payments made inside the horizon) |
| Cautious / optimistic | Cautious: dearest install multiplier, lowest performance ratio. Optimistic: cheapest multiplier, highest performance ratio. |
Solar cautious, typical, and optimistic scenarios combine the cost multipliers with lower, default, and higher performance ratios. The higher performance ratio is capped at 100%. Incentives are manually entered and reduce net installation cost to no less than zero. Simple payback uses year-one savings and does not account for financing, degradation, or later price changes. Cumulative net sums savings over the selected horizon and subtracts net installation cost, or loan payments made within the horizon.
The solar bill comparison models energy charges only. It does not simulate a household's hourly load, tariff tiers, time-of-use rates, fixed or demand charges, roof geometry, shading, batteries, taxes, maintenance, inverter replacement, or discounting. Export credits can make the modelled bill negative if the entered export value exceeds remaining energy charges; actual utility billing rules may differ.
Incentives, missing data, and uncertainty
Neither model loads a catalog of tax credits, rebates, or utility incentives. A reader enters an incentive amount; eligibility, timing, and tax treatment are not determined by the calculators. Missing or invalid required inputs produce an error rather than a fabricated estimate. Warnings identify some unusual inputs and situations, but do not verify that the values are realistic.
All current default data values are marked unverified in the data files. Scenario spreads are chosen modelling inputs, not statistically derived distributions. A range shows how selected assumptions change arithmetic; it does not indicate likelihood.
Testing and model changes
The calculation modules have automated tests using explicit test fixtures, plus checks for invalid inputs, scenario ordering, zero or negative savings, oversized incentives, and financing behavior where covered by the tests. These tests check code behavior; they are not independent engineering review or validation against measured household performance.
When a formula changes, the project process is to update its tests, increment the model version, and record the change in the changelog. For data provenance, see Data sources; for source and correction standards, see the Editorial policy.
All results are estimates, not quotes, professional site assessments, guarantees of energy savings, or individualized financial advice. Confirm equipment, costs, safety, incentives, and installation requirements with suitable local professionals and the relevant providers.