# 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.