231 lines
3.8 KiB
Markdown
231 lines
3.8 KiB
Markdown
# 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.
|