local-pv-forecast

Local, horizon-aware photovoltaic forecast engine for Home Assistant and standalone use.

---

Features

• Fully local PV forecast calculation
• Horizon-aware shading model
• Open-Meteo / DWD / METAR weather integration
• Clear-sky irradiance calculation
• Calibration against historical production data
• Home Assistant integration
• CSV import/export tools
• Plotting and diagnostics
• Forecast comparison and horizon fitting scripts

---

Motivation

Most cloud-based PV forecast systems have limited knowledge of the real installation environment:

• local horizon obstructions
• trees and buildings
• seasonal shading
• module orientation differences
• site-specific losses

This project aims to build a transparent and fully local forecasting pipeline that can be calibrated against real production data and local horizon measurements.

The long-term goal is to improve short-term PV forecast accuracy for Home Assistant energy management and battery optimization.

---

Architecture

Weather Data
(Open-Meteo / DWD / METAR)
          │
          ▼
Clear Sky Model
          │
          ▼
Solar Position Calculation
          │
          ▼
Local Horizon / Shading Model
          │
          ▼
PV System Model
          │
          ▼
Calibration Layer
          │
          ▼
Forecast Output
(Home Assistant / CSV / Plots)

---

Repository Structure

src/
├── astronomy/        Solar position & irradiance
├── shading/          Horizon and shading calculations
├── weather/          Weather providers
├── model/            PV and forecast models
├── io/               Home Assistant & CSV interfaces
└── utils/            Shared utilities

scripts/
├── fetch_weather.py
├── generate_forecast.py
├── compare_day.py
└── fit_horizon.py

tests/
└── Unit tests

---

Installation

Clone repository

git clone https://github.com/<your-user>/local-pv-forecast.git
cd local-pv-forecast

Create virtual environment

python3 -m venv .venv
source .venv/bin/activate

Install dependencies

pip install -r requirements.txt

---

Configuration

Example configuration files are located in:

config/

Typical configuration parameters:

• latitude / longitude
• panel azimuth
• panel tilt
• installed peak power
• horizon profile
• inverter efficiency
• weather provider selection

---

Horizon Model

The forecast engine supports custom local horizon profiles.

Example:

azimuth,elevation
0,2
45,5
90,12
135,18
180,4

This allows modeling of:

• buildings
• trees
• terrain
• seasonal shading effects

---

Home Assistant Integration

Forecast values can be exported as Home Assistant compatible sensors.

Planned integration targets:

• Energy Dashboard
• Battery charging automation
• EV charging optimization
• Dynamic load shifting

---

Example Usage

Fetch weather data

python scripts/fetch_weather.py

Generate forecast

python scripts/generate_forecast.py

Compare forecast vs. measured data

python scripts/compare_day.py

Fit local horizon from historical production

python scripts/fit_horizon.py

---

Planned Features

• Fully local weather fallback model
• Automatic horizon fitting
• Multi-array support
• Battery-aware optimization
• Probabilistic forecast
• Docker container
• Native Home Assistant Add-on
• Web UI
• ML-assisted calibration

---

Design Philosophy

• Local-first
• Transparent calculations
• Reproducible results
• No cloud dependency required
• Easy Home Assistant integration
• Open and inspectable models

---

License

MIT License

---

Contributing

Pull requests, issue reports and calibration datasets are welcome.