Methodology & Assumptions

Brand glossary (translation conventions)

To keep the English and German versions consistent, the following terms are translated as follows:

Section index (mirrors the German version)

1. Solar Position — NOAA Solar Position Algorithm (Fourier-reduced form). Source: solar_math_service.dart.
2. Sun-Path Envelope — Annual min/max elevation per azimuth bin. Source: sun_path_envelope_service.dart.
3. Shading Loss (direct + diffuse) — Sky-View-Factor + sun-path integration weighted by sin(α)·max(0, cos(AoI)). Source: shading_service.dart.
4. Load Profile — BDEW H25 + deltas — Reference profile scaled by country defaults, additive deltas for presence, devices, large consumers. Heat-pump season factor s(m) = max(0.25, 1.0 + 0.85·cos(2π·(m−1)/12)). Source: load_profile_service.dart.
5. Self-Consumption Heuristic (score-based) — Linear score from 0.35 plus category deltas, clamped to [0.25, 0.85]. Source: self_consumption_service.dart.
6. Hourly Self-Consumption Overlay — min(PV, Load) aggregation over 12 monthly profiles × 24 hours with Jensen-bias correction factor 0.85. Same source as §5.
7. Economics — Year-1 Savings & Payback — Cashflow-based, no inflation modeling (deliberately conservative). Geometric-series payback solution with module degradation. Source: economics_service.dart.
8. PV Hourly Estimation — Clear-sky shape scaled to monthly kWh from the solar provider, with NOCT-like cell temperature and 0.4 %/K efficiency derate. Source: pv_hourly_estimator.dart.
9. DC/AC Clipping (Inverter Limit) — Hard cap on hourly output + heuristic minute-spike loss for high DC/AC ratios. Source: yield_provider.dart (function _sumAndCap).
10. Solar Data Routing — Region-based provider selection: PVWatts v8 (NA), PVGIS v5_3 (EU/AF/AS/AU/SA), NASA POWER (fallback). Source: solar_data_router.dart.
11. Yield Orchestration (End-to-End Data Flow) — Deterministic pipeline tying §1–§10 into a YieldComputation for the Results screen. Multi-array weighted aggregation. Source: same as §9.
12. Telemetry & Privacy — Local-only, no network telemetry.
13. Known Limits & Backlog — Country-specific load profiles, storage simulation, electricity-price inflation, etc.
14. Data Invalidation Rules (Wizard State) — When are captured data invalidated (location drift, panel re-orientation, etc.).
15. FAQ — Recurring Reviewer Questions — Why no winter consumption bump, why 18 % system loss, etc.

Notation & symbols

Identical to the German version (§Notation & Symbole in constraints.md). Greek letters used in formulas: φ (latitude), δ (declination), H (hour angle), z (zenith), α (elevation), γ (azimuth), β (tilt), γ_p (panel azimuth). Operators: · (multiplication), − (minus), Δ (difference/step), Σ (sum). Formula boxes use the same (N.k) numbering as the German version, so cross-references between the two languages work directly.

Country defaults

Identical to §0.5 in constraints.md. The country defaults table (DE, AT, CH, NL, BE, FR, IT, ES, PL, CZ — with electricity price, feed-in tariff, CO₂ factor, diffuse fraction, balcony plant defaults, household kWh per household type) is language-neutral and lives in assets/defaults/country_defaults.json.

Reproducibility

All models under lib/data/ are pure Dart, deterministic, no IO. Fixtures under code/horisol/assets/fixtures/shading/ (synthetic) and data/jrc_testdata_1000wp_180_90/ (PVGIS reference, untracked) enable regression checks via:

dart run code/horisol/tool/shading_lab.dart <fixture.json>

Tests: 293 tests passing (as of 2026-05-23). The architecture boundary test (test/architecture/no_flutter_imports_test.dart) prevents Flutter/plugin imports in the pure domain layer.

One-sentence summary

HoriSol calculates conservatively, documents every assumption, weighs inputs by location, and explicitly names where the model simplifies. If you want a pretty number, you are in the wrong place — if you want an honest number, you have one here.