Metadata-Version: 2.4
Name: finpv
Version: 1.0.2
Summary: Solar PV payback period and irradiation analysis for Finland
Author: Shahbaz Baig
License-Expression: MIT
Project-URL: Homepage, https://github.com/shahbazbaig38/finpv
Project-URL: Documentation, https://github.com/shahbazbaig38/finpv/blob/main/docs/DOCUMENTATION.md
Project-URL: Issues, https://github.com/shahbazbaig38/finpv/issues
Keywords: solar,pv,photovoltaic,finland,payback,irradiance,renewable-energy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pvlib>=0.13.0
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# finpv

Solar PV payback period and irradiation analysis for Finland.

`finpv` estimates annual energy production, payback period, and lifetime
NPV for a rooftop/ground-mount solar PV system at any Finnish location.
It uses [pvlib](https://pvlib-python.readthedocs.io/) and PVGIS irradiance
data under the hood, and adds Finnish-specific defaults (self-consumption
vs. export pricing, snow/loss assumptions, city coordinate lookup).

## Installation

```bash
pip install finpv
```

## Quick start

```python
from finpv import calculate_payback

result = calculate_payback(
    location="Kuopio",              # or (lat, lon) tuple
    system_kwp=8,                   # installed system size, kWp
    system_cost_eur=9500,           # total installed cost
    electricity_price_eur_per_kwh=0.15,
)

print(f"Annual production: {result.annual_kwh:.0f} kWh")
print(f"Specific yield: {result.specific_yield_kwh_per_kwp:.0f} kWh/kWp")
print(f"Year 1 savings: €{result.annual_savings_eur:.0f}")
print(f"Simple payback: {result.simple_payback_years:.1f} years")
print(f"25-year NPV: €{result.npv_eur:.0f}")

# Monthly breakdown
for month, kwh in sorted(result.monthly_kwh.items()):
    print(f"  Month {month:2d}: {kwh:.0f} kWh")
```

## Supported locations

Pass a Finnish city name (case-insensitive) or explicit `(lat, lon)`
coordinates anywhere within Finland's bounding box.

```python
from finpv import list_cities

print(list_cities())
```

**Built-in cities:** Espoo, Helsinki, Hämeenlinna, Joensuu, Jyväskylä,
Kajaani, Kokkola, Kotka, Kouvola, Kuopio, Lahti, Lappeenranta, Mikkeli,
Oulu, Pori, Porvoo, Rauma, Rovaniemi, Savonlinna, Seinäjoki, Sodankylä,
Tampere, Turku, Vaasa, Vantaa.

Both ASCII (`jyvaskyla`) and accented (`jyväskylä`) spellings are accepted.

## Key assumptions (all overridable)

| Parameter                    | Default       | Notes                                                        |
| ---------------------------- | ------------- | ------------------------------------------------------------ |
| `tilt`                     | 40°          | Reasonable year-round compromise for Finnish latitudes       |
| `azimuth`                  | 180° (south) | pvlib/PVGIS convention                                       |
| `system_losses`            | 14%           | Inverter, wiring, soiling — raise this for snow-prone sites |
| `self_consumption_ratio`   | 0.7           | Fraction of generation used on-site vs exported              |
| `export_price_eur_per_kwh` | 0.03          | Price for surplus/exported energy                            |
| `price_inflation`          | 2%/yr         | Electricity price growth assumption                          |
| `discount_rate`            | 3%/yr         | Used for NPV                                                 |
| `degradation_rate`         | 0.5%/yr       | Panel output degradation                                     |
| `lifetime_years`           | 25            | System analysis horizon                                      |

## Requirements

- Python 3.9+
- pvlib ≥ 0.13.0
- Internet access at runtime (PVGIS API calls for irradiance data)

## Development

```bash
git clone https://github.com/shahbazbaig38/finpv
cd finpv
pip install -e ".[dev]"
pytest
```

## Funding

The development of this library was carried out as part of the **Turva-akku** project at **Savonia University of Applied Sciences**. The project is funded by **Pohjois-Savo Liitto** and co-funded by the **European Union**.

## License

MIT
