Initial commit

2026-05-27 08:33:45 +02:00
commit 075af25c7d
34 changed files with 259 additions and 0 deletions
@@ -0,0 +1,230 @@
+# 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
+
+```text
+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
+
+```text
+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
+
+```bash
+git clone https://github.com/<your-user>/local-pv-forecast.git
+cd local-pv-forecast
+```
+
+### Create virtual environment
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+---
+
+## Configuration
+
+Example configuration files are located in:
+
+```text
+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:
+
+```text
+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
+
+```bash
+python scripts/fetch_weather.py
+```
+
+### Generate forecast
+
+```bash
+python scripts/generate_forecast.py
+```
+
+### Compare forecast vs. measured data
+
+```bash
+python scripts/compare_day.py
+```
+
+### Fit local horizon from historical production
+
+```bash
+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.