How the model works

Generation sources

Nine sources the engine knows about: Solar, Nuclear, Hydro, Wind, Geothermal, Natural Gas, Coal, Biomass, Petroleum. Each carries ~25 researched values (capex, fixed O&M, LCOE, capacity factor, retirement schedule, learning rate, …) drawn from NREL ATB, EIA, EPA eGRID, and peer-reviewed literature.

Submodels

Structural sub-models that override the simple per-sector monolithic growth math for high-leverage end-uses:

• Vehicle stock (D30 LDV + D31 HDV): Bass-style S-curve adoption with fuel-price and policy feedbacks; LDV curve recalibrated to an AEO-vs-IEA midpoint (D85).
• Storage & VRE integration (D86–D90): storage deployed on an LCOS-vs-value crossing, driven by a duck curve keyed on VRE capacity penetration; a vintage capacity stock (real EIA-860 install-year cohorts) tracks installed solar/wind GW.
• Hydrogen (D32, opt-in): SMR vs electrolysis production split + sector demand.
• Data centers (D37): logistic growth ramp into Industrial grid demand.
• Building heating (D102): residential + commercial heat-pump stock turnover; carves space/water-heating fossil out of the CES and electrifies it at heat-pump COP (1 Q fossil → ~0.31 Q grid). On by default; reduces economy-wide CO₂. Per-state climate brackets since D107 (cold-cluster COP derate MN/WI/MI, warm-cluster FL/TX ahead of the US adoption curve).

Feedback loops

The engine isn't a one-pass calculation. A handful of loops connect per-year outputs back into next-year inputs:

• Wright's-law learning (D20/D34): cumulative deployment shrinks per-source LCOE.
• Demand elasticity (D26): sector demand responds to retail price changes.
• Battery-cost feedback (D27): cheaper batteries decay the VRE integration penalty.
• Duck-curve coupling (D86/D87): VRE capacity penetration deepens the duck curve, which both deflates VRE market value and raises storage's arbitrage value (LCOS-vs-value).
• Dispatch shift (D49): natural gas absorbs coal-retirement gaps via existing-fleet utilization.
• Fuel-price elasticity (D68): gasoline prices advance the BEV S-curve t_mid.

One loop the engine deliberately compresses: real-world interconnection queues, permitting, and equipment supply chains are modeled as per-source build caps (D44). The uncompressed version (who actually gates each step and why) is its own explainer: Gridlock: why it's hard to plug in.

Levers & scenarios

56 user-exposed levers across four families: generation (Wright's-law rates, retirement schedules, build caps), demand (per-sector growth + elasticity), T&D (per-ISO markups), and submodels (storage, vehicle stock, data centers, hydrogen, building heating). Defaults come from research; overrides land in a "basket" the engine consumes per-projection-year.

Wondering why even aggressive lever pulls move the projection gradually? The build caps are doing that on purpose: they compress the real world's interconnection queues, siting fights, and equipment backlogs into per-source annual limits. Gridlock: why it's hard to plug in maps that friction in full, including a "Speed it up" mode whose model-runnable fixes stage these very levers.

Policy layer

A closed-enum mechanism resolver (D29) that turns time-bounded policies (federal IRA tax credits, state RPS targets, carbon prices) into engine input adjustments. 15 mechanisms across carrots (production credit, consumer credit, capex offset, …), sticks (regulatory capex, excise tax, …), quantity constraints (mandate floors, electrification mandates), and supply-chain deployment capacity. Jurisdiction-aware: federal policies fire in every region; a state policy fires at full strength in its own state and in states that formally adopted it (§177-style adoption_states), and at a researched spillover share in the US aggregate.

State-scale modeling

Every state has a full historical Sankey (EIA SEDS, 2018–2023) and a committed default projection to 2050: the same engine, re-grounded per state:

• Scaling & overrides (D62/D63): US-aggregate submodel parameters scale by each state's load share; 31 states additionally declare researched overrides (tiered coal/nuclear retirement, BEV adoption (CA buys BEVs at ~3× the US rate), data-center concentration, build caps).
• Weather & resources (D91): solar capacity factors follow each state's irradiance, wind follows its NREL wind class, and VRE cost scales inversely (AZ solar is cheap, WY wind is strong).
• Climate-bracket heating (D107): the heat-pump submodel runs cold-climate physics in MN/WI/MI (seasonal COP ~2.3, adoption lagging the US curve) and warm-climate in FL/TX (COP ~3.5, heat pumps long dominant). The two extremes bracket the US average, so unlisted states inherit credible defaults.
• Interstate electricity trade (D105): each state carries its real net position from SEDS: importers like CA show ~0.39 Q flowing in through Net Electricity Imports; exporters like PA/WY/WV send their surplus out through an Electricity Exports node (previously it was misrendered as waste heat). Traded electricity is counted with its embedded generation losses (the SEDS state-accounting convention), so the energy burden follows the buyer. Projections hold each state's position at its baseline, supply-clamped; a price-responsive exchange model was built and backtested but did not beat the baseline-anchored approach on 2018–2023, so it ships lever-gated off (D106).

A "sum of 50 states" aggregation mode exists as a validation harness (each state projected independently, every flow summed), comparing it against the direct US projection is how per-state parameters earn their keep.

Research values & quality tiers

Every quantitative model input is wrapped in a ResearchedValue (D21) with a quality tier:

• L1 primary (EIA / NREL / EPA / IRENA).
• L2 L1-derived (computed from primary inputs).
• L3 peer-reviewed literature.
• L4 transcribed unverified, triggers the "less-verified source" callout.

One accounting convention worth knowing: every CO₂ number in the app uses the fossil-combustion basis, biomass counts zero, matching the EIA / Ember / LLNL biogenic-zero convention every published benchmark uses. The physical biomass stack CO₂ (~93 Mt per Quad burned) is never hidden: it appears as an explicit "biogenic (not counted)" line on the impact card and the biomass tooltips (D104).

Decision history

The engine's architecture grew through 100+ numbered design decisions (D1–D107 to date) recorded in DECISIONS.md. Each entry carries the call, the rationale, and a review-by date so the design stays auditable, including the negative results (mechanisms built, backtested, and deliberately kept off).