Engine · the year loop
Two homes, one loop: how the comparison is built
The engine never estimates "savings" directly. It builds two copies of your home from the same inputs, do nothing and your journey, steps both through the same years at the same prices, and records what each one spends. Your plan is the only difference between them, so the gap between the two totals is what the plan does.
Control flow, start to finish
Dashed arrows are what runs when. Solid arrows are data going into, or out to, the stores on the right. Everything above the year loop runs once. Everything inside runs once per year, for each home.
How the two homes differ, and how they don't
Both homes read the same climate zone, the same rate for each year and month, and the same tariff. Nothing about the outside world differs.
Built from one set of appliance configurations: same insulation, same gallons of hot water, same miles driven.
Do nothing keeps each appliance's baseline (usually gas) version. Your journey switches to the electric version in the swap year.
These only exist in your journey. The do-nothing home has none of them.
If an appliance is electric today (say, an induction cooktop), it is electric in both homes. "Do nothing" never goes back to gas.
When an appliance reaches its lifespan it is replaced like-for-like and its install cost is booked, in whichever home it is running.
One appliance, 20 years
The rules for a single appliance slot, run in the page. Each year the active appliance is chosen, it ages one year, and an install cost is booked either for the swap or for a like-for-like replacement at end of life.
Pricing a year: two stages
Stage 1 · per appliance. Each appliance's 12 monthly values are multiplied by that month's rate: $/therm for gas, $/kWh for electric. This gives a cost for every appliance, used for the by-category charts.
Stage 2 · the home's real electric bill. A time-of-use tariff isn't a flat price per kWh: it has tiers that depend on the whole home's monthly use, peak hours and a daily fixed charge. So the engine adds up all electric appliances, spreads them over each month's 24-hour day, and prices the home total on the actual tariff. That bill replaces the stage-1 sum, and the difference is shared across categories in proportion to their electric cost. Both homes get this stage whenever the utility has a URDB plan; with an EIA average rate there are no tiers or peak hours, so stage 1 already is the bill.
Stage 3 · solar and battery (your journey only). The hourly energy balance works out how much of that bill solar and the battery avoid, plus the export credit. The saving is capped at the year's electric bill: like a NEM true-up, solar can't push a year below zero.
What comes out, and how to read it
Every year, each home records its cost by category (heating, cooling, water heating, baseload, transportation), its kWh, therms and gallons, install-cost events, solar and battery flows, and the hourly peak / off-peak purchases. All of it goes into one table with a row per year, and every chart reads from that table.
Important: the headline cumulative cost chart is energy cost only (net of solar). Install costs, including swaps, replacements, solar and panel, are shown on their own CapEx chart. So the "payback" marker is the year your journey's cumulative energy savings turn positive. It does not include what you paid for the equipment.
What guarantees the loop is right
- Each year is recorded exactly once per category: costs are summed first, then written once.
- Starting states are preserved when the do-nothing home is built.
- A heat pump is one install event (heating and cooling together), never split in two.
- Regression suite: 32 saved scenarios (PG&E plans × projections, plus a gas-only set) must reproduce their approved results after every change.
- Unit tests check each appliance formula against reference values.
- Not modeled: financing and interest, discounting future dollars, tax credits beyond the rebate you enter.
An optional comparison mode runs a second pair of homes under a different rate scenario, so two futures can be compared side by side.